> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # SeeDance 비디오 생성 API 연동 설명 > ByteDance Seedance Video Generation API guide - Ace Data Cloud 본 문서에서는 SeeDance 비디오 생성 API 연동 방법을 소개합니다. 이 API는 사용자 정의 매개변수를 입력하여 SeeDance 공식 비디오를 생성할 수 있습니다. ## 신청 절차 SeeDance 비디오 생성 API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API 토큰을 받아야 하며, 이를 보관해 두십시오. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 로그인 또는 등록이 되어 있지 않은 경우, 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 요청합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. **하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다.** 처음 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있습니다; 할당량이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 일반 잔액을 충전할 수 있습니다. > 📘 전체 문서: [SeeDance 비디오 생성 API →](https://platform.acedata.cloud/documents/seedance-videos) ## 기본 사용법 먼저 기본 사용 방법을 이해해야 합니다. 즉, 입력 프롬프트 `content.text`, 유형 `content.type=text`, 모델 `model`을 입력하면 처리된 결과를 얻을 수 있습니다. 구체적인 내용은 다음과 같습니다:

여기에서 요청 헤더를 설정한 것을 볼 수 있습니다: * `accept`: 어떤 형식의 응답 결과를 받을지, 여기서는 `application/json`으로 JSON 형식을 입력합니다. * `authorization`: API 호출을 위한 키로, 신청 후 드롭다운에서 직접 선택할 수 있습니다. 또한 요청 본문을 설정했습니다: * `model`: 비디오를 생성하는 모델. * **Seedance 1.x 시리즈**: `doubao-seedance-1-0-pro-250528`, `doubao-seedance-1-0-pro-fast-251015`, `doubao-seedance-1-5-pro-251215`, `doubao-seedance-1-0-lite-t2v-250428`, `doubao-seedance-1-0-lite-i2v-250428`. * **Seedance 2.0 시리즈** (얼굴/캐릭터 참조 등 다중 모달 입력 지원): `doubao-seedance-2-0-260128` (표준), `doubao-seedance-2-0-fast-260128` (빠름), `doubao-seedance-2-0-mini-260615` (경량). 자세한 내용은 아래의 "얼굴 및 캐릭터 참조 (Seedance 2.0)" 섹션을 참조하십시오. * `content`: 입력 내용 배열, `type`은 `text` (프롬프트), `image_url` (참조 이미지), `audio_url` (참조 오디오, 2.0), `video_url` (참조 비디오, 2.0)일 수 있습니다. 이미지는 `role`을 통해 용도를 지정할 수 있습니다: `first_frame` (첫 프레임) / `last_frame` (마지막 프레임) / `reference_image` (얼굴 / 캐릭터 / 주체 참조). * `resolution`: 출력 해상도, 선택 가능: `480p` / `720p` / `1080p` (2.0 표준 모델은 `4k`도 지원; 2.0의 `fast` / `mini`는 최대 `720p`). * `ratio`: 가로 세로 비율, 선택 가능: `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`. * `duration`: 비디오 길이(초), 1.x 범위 2–12, 2.0 범위 2–15. * `seed`: 랜덤 시드, 정수, -1에서 4294967295까지. * `camerafixed`: 카메라 고정 여부, `true` / `false`. * `watermark`: 워터마크 추가 여부, `true` / `false`. * `generate_audio`: 음성 비디오 생성 여부, `true` / `false`, **오직 `doubao-seedance-1-5-pro-251215`만 지원**. * `return_last_frame`: 결과에 비디오 마지막 프레임 이미지 URL을 반환할지 여부. * `execution_expires_after`: 작업 타임아웃 시간(초), 범위 3600–259200. * `callback_url`: 비동기 콜백 주소, 설정 후 API는 즉시 `task_id`를 반환하며, 작업 완료 시 결과를 해당 주소로 POST합니다. * `async`: 선택 사항, `true`로 설정하면 인터페이스는 즉시 `task_id`를 반환하며, `callback_url`을 제공할 필요가 없고, 이후 해당 작업 조회 인터페이스를 통해 결과를 폴링하여 가져올 수 있습니다. 선택 후 오른쪽에도 해당 코드가 생성된 것을 확인할 수 있습니다, 아래 그림과 같이:

"Try" 버튼을 클릭하면 테스트를 진행할 수 있으며, 위 그림과 같이 다음과 같은 결과를 얻을 수 있습니다: ```json theme={null} { "success": true, "task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8", "trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752", "data": { "task_id": "7e4e1773-510a-4a73-9ab4-98dd1a0b2a7f", "status": "succeeded", "model": "doubao-seedance-2-0-fast-260128", "duration": 5, "resolution": "720p", "ratio": "16:9", "video_url": "https://platform2.cdn.acedata.cloud/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152.mp4" } } ``` 반환 결과는 여러 필드로 구성되어 있으며, 설명은 다음과 같습니다: * `success`: 이 시점에서 비디오 생성 작업의 상태. * `task_id`: 이 시점에서 비디오 생성 작업 ID. * `trace_id`: 이 시점에서 비디오 생성 추적 ID. * `data`: 이 시점에서 비디오 생성 작업의 결과 목록. * `task_id`: 이 시점에서 비디오 생성 작업의 서버 측 ID. * `video_url`: 이 시점에서 비디오 생성 작업의 비디오 링크. * `status`: 이 시점에서 비디오 생성 작업의 상태. * `model`: 비디오 생성에 사용된 모델. 우리는 만족스러운 비디오 정보를 얻었으며, 결과의 `data`에서 비디오 링크 주소를 통해 생성된 SeeDance 비디오를 가져올 수 있습니다. 또한 해당 연동 코드를 생성하고 싶다면, 생성된 코드를 직접 복사할 수 있습니다. 예를 들어 CURL의 코드는 다음과 같습니다: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/seedance/videos' \ -H 'authorization: Bearer ${bearer_token}' \ -H 'accept: application/json' \ -H 'content-type: application/json' \ -d '{ "content": [{"type":"text","text":"A white ceramic coffee mug on a glossy marble countertop with soft morning window light. The camera slowly orbits 360 degrees around the mug, steam gently rising."}], "model": "doubao-seedance-2-0-fast-260128", "resolution": "720p", "ratio": "16:9", "duration": 5 }' ``` ## 인라인 매개변수 설명 `content[].text` 프롬프트의 끝에 `--parameter value` 형식으로 생성 매개변수를 추가하여 전달할 수 있습니다 (구식 방법, 약한 검증, 잘못 입력 시 자동으로 기본값 사용). 전체 매개변수 목록은 다음과 같습니다: | 내장 매개변수 | 해당 필드 | 설명 | 값 범위 | | ---------- | ----------------- | ---------- | ------------------------------------------------------------- | | `--rs` | `resolution` | 출력 해상도 | `480p` / `720p` / `1080p` | | `--rt` | `ratio` | 가로 세로 비율 | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive` | | `--dur` | `duration` | 비디오 길이(초) | 2–12 | | `--frames` | `frames` | 비디오 프레임 수 | \[29, 289] 중 25+4n의 정수 | | `--fps` | `framespersecond` | 프레임 속도 | 오직 `24`만 지원 | | `--seed` | `seed` | 랜덤 시드 | -1에서 4294967295 | | `--cf` | `camerafixed` | 카메라 고정 여부 | `true` / `false` | | `--wm` | `watermark` | 워터마크 추가 여부 | `true` / `false` | > **권장 사항**: 요청 본문에서 해당 최상위 필드(예: `resolution`, `ratio` 등)를 직접 사용하여 강력한 검증 모드를 설정하십시오. 매개변수 입력 오류 시 명확한 오류 메시지가 반환되어 문제를 더 쉽게 파악할 수 있습니다. ## 음성 비디오 생성 `doubao-seedance-1-5-pro-251215`는 `generate_audio` 매개변수를 통해 오디오가 포함된 비디오를 생성할 수 있습니다: ```json theme={null} { "model": "doubao-seedance-1-5-pro-251215", "content": [ { "type": "text", "text": "여자아이가 여우를 안고 바람에 머리카락이 날리며 바람 소리를 들을 수 있습니다." } ], "generate_audio": true, "ratio": "16:9", "duration": 5 } ``` 다른 모델은 이 매개변수를 지원하지 않으며, 전달 시 무시됩니다. ## 이미지로 비디오 첫 프레임 생성 비디오 작업을 위해서는 먼저 `content` 매개변수에 `type`이 `image_url`인 항목이 포함되어야 하며, `image_url` 필드는 객체 형식이어야 합니다: `{"url": "https://..."}` 또는 Base64 형식 `{"url": "data:image/png;base64,..."}`. > **주의**: `image_url`은 문자열 형식으로 직접 전달할 수 없습니다(예: `"image_url": "https://..."`), 반드시 객체 형식 `"image_url": {"url": "https://..."}`를 사용해야 하며, 그렇지 않으면 400 오류가 반환됩니다. 해당 코드: ```python theme={null} import requests url = "https://api.acedata.cloud/seedance/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "content": [ { "type": "image_url", "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png" } }, { "type": "text", "text": "여자아이가 여우를 품에 안고 있습니다. 그녀는 눈을 뜨고 카메라를 부드럽게 바라보며, 여우는 애정 어린 눈빛으로 그녀를 바라봅니다. 카메라가 천천히 멀어지면서 그녀의 머리카락이 바람에 부드럽게 날립니다. --ratio adaptive --dur 5" } ], "model": "doubao-seedance-1-0-pro-250528" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 실행하면 즉시 다음과 같은 결과를 얻을 수 있습니다: ``` { "success": true, "task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39", "trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4", "data": { "task_id": "cgt-20251222072003-x2259", "status": "succeeded", "video_url": "https://platform.cdn.acedata.cloud/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4", "model": "doubao-seedance-1-0-pro-250528" } } ``` 생성된 효과는 이미지로 비디오를 생성한 것이며, 결과는 위와 유사합니다. ## 이미지로 비디오 첫 및 마지막 프레임 생성 비디오의 첫 및 마지막 프레임을 생성하려면, 먼저 매개변수 `content`에 `image_url` 유형을 전달해야 하며, 각각 `role`을 `first_frame` 및 `last_frame`으로 설정하여 다음 내용을 지정할 수 있습니다: * role: 첫 프레임 또는 마지막 프레임을 지정합니다. * image\_url * url 이미지 링크 동시에 `content`에는 `text` 유형을 입력하여 프롬프트 힌트를 제공해야 합니다. 해당 코드: ```python theme={null} import requests url = "https://api.acedata.cloud/seedance/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "doubao-seedance-1-0-pro-250528", "content": [ { "type": "text", "text": "360도 샷" }, { "type": "image_url", "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg" }, "role": "first_frame" }, { "type": "image_url", "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg" }, "role": "last_frame" } ] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 실행하면 즉시 다음과 같은 결과를 얻을 수 있습니다: ``` { "success": true, "task_id": "f7096c6c-9430-4392-8201-d259632d7afd", "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a", "data": { "task_id": "cgt-20251222073134-54qcw", "status": "succeeded", "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4", "model": "doubao-seedance-1-0-pro-250528" } } ``` 생성된 효과는 캐릭터 생성 비디오이며, 결과는 위와 유사합니다. ## 얼굴 및 캐릭터 참조 (Seedance 2.0) **Seedance 2.0 시리즈**(`doubao-seedance-2-0-260128`, `doubao-seedance-2-0-fast-260128`, `doubao-seedance-2-0-mini-260615`)는 `content`에 `type`이 `image_url`이고 `role`이 `reference_image`인 항목을 추가하여 "실제 인물 / 캐릭터"의 참조 자료를 전달할 수 있습니다. 인물 사진을 참조로 사용하면 모델은 생성된 비디오에서 **해당 인물의 외모 특성을 유지**하여 동일한 인물을 새로운 장면, 동작 또는 샷에 "넣을" 수 있습니다. > 📌 실제 인물 사진은 플랫폼에서 자동으로 기본 자료로 등록된 후 생성에 사용되며, 이 과정은 호출자에게 완전히 투명합니다: **요청 및 응답 형식은 변하지 않으며**, 추가 매개변수 없이도 첫 번째 생성 시 자료 처리에 몇 초가 더 소요됩니다. 사용 요점: * 오직 **Seedance 2.0 시리즈** 모델만 `reference_image`를 지원합니다; 1.x 모델은 `first_frame` / `last_frame`(영상 생성의 첫 번째 및 마지막 프레임)을 사용하십시오. * `reference_image`는 **first\_frame** / **last\_frame**과 혼용할 수 없으며, 둘 중 하나만 선택할 수 있습니다. * 다중 모달 참조 수량 상한: `image_url`은 최대 **9**장; 2.0은 `audio_url`(`role`이 `reference_audio`인 경우, 최대 3개) 및 `video_url`(`role`이 `reference_video`인 경우, 최대 3개)을 지원합니다. * 참고 이미지는 **단독 인물, 정면, 선명, 가림이 없는** 사진을 사용하는 것이 좋습니다. 얼굴이 선명할수록 유사도가 높아집니다. ### 예시 1: 인물 외모를 유지한 클로즈업 인물의 얼굴 사진을 전달하여 해당 인물이 카메라를 향해 미소를 지으며 손을 흔들게 합니다. 해당 코드: ```python theme={null} import requests url = "https://api.acedata.cloud/seedance/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "doubao-seedance-2-0-fast-260128", "content": [ { "type": "text", "text": "The woman looks at the camera, gives a warm natural smile and waves her hand, soft studio lighting, gentle camera push-in." }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg" } } ], "resolution": "480p", "ratio": "9:16", "duration": 5 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 반환 결과는 다음과 같으며, 생성된 비디오에서 인물은 참고 사진과 일치합니다: ```json theme={null} { "success": true, "task_id": "895eb5ea-bbe1-41a3-a9e9-48608e03f93a", "trace_id": "83544791-7a84-44de-b8d2-afe171a1c0e4", "data": { "task_id": "458abf29-cc39-4fd0-bcea-24f89a70d8de", "status": "succeeded", "video_url": "https://platform2.cdn.acedata.cloud/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf.mp4", "model": "doubao-seedance-2-0-fast-260128", "resolution": "480p", "ratio": "9:16", "duration": 5 } } ``` ### 예시 2: 같은 인물을 새로운 장면에 배치하기 `reference_image`의 강력한 점은: **인물의 정체성**만 유지하고, 장면, 의상, 동작은 전적으로 프롬프트에 의해 결정된다는 것입니다. 아래는 같은 얼굴 사진을 사용하여 해당 인물이 베이지색 코트를 입고 가을 공원에서 걷는 장면입니다: ```json theme={null} { "model": "doubao-seedance-2-0-fast-260128", "content": [ { "type": "text", "text": "The same woman wearing a beige coat walks through a sunny autumn park, golden leaves falling around her, she smiles softly at the camera, cinematic tracking shot." }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg" } } ], "resolution": "720p", "ratio": "9:16", "duration": 5 } ``` 반환 결과는 다음과 같으며, 인물의 외모는 유지되었고 장면은 가을 공원으로 변경되었습니다: ```json theme={null} { "success": true, "task_id": "00872de7-16b7-431f-b4f7-6bf38ae86157", "trace_id": "577a07c3-4f5f-4cc7-86fe-535bb8332614", "data": { "task_id": "32fe1537-ba3e-452a-8749-3ef8890d37fd", "status": "succeeded", "video_url": "https://platform2.cdn.acedata.cloud/seedance/44f47593-556b-4fda-afa5-7a71eefcd228.mp4", "model": "doubao-seedance-2-0-fast-260128", "resolution": "720p", "ratio": "9:16", "duration": 5 } } ``` > 💡 인물이 사진의 구성을 정확히 재현하도록 하려면(`장면을 바꾼 같은 인물`이 아닌), `first_frame`(영상 생성의 첫 번째 프레임)을 사용하여 비디오가 이 사진에서 시작하도록 하십시오. ## 비동기 콜백 SeeDance Videos Generation API의 생성 시간이 길기 때문에(약 1-2분), `callback_url` 필드를 통해 비동기 모드를 사용하여 HTTP 연결이 장시간 점유되는 것을 피할 수 있습니다. 전체 프로세스: 클라이언트가 요청을 시작할 때 `callback_url`을 지정하면, API는 즉시 `task_id`가 포함된 응답을 반환합니다; 작업이 완료되면 플랫폼은 생성 결과를 POST JSON 형식으로 `callback_url`로 전송하며, 결과에도 `task_id`가 포함되어 있어 연관성을 유지합니다. ```json theme={null} { "task_id": "f7096c6c-9430-4392-8201-d259632d7afd" } ``` 작업이 완료되면 플랫폼이 `callback_url`로 푸시하는 내용은 다음과 같습니다: ```json theme={null} { "success": true, "task_id": "f7096c6c-9430-4392-8201-d259632d7afd", "trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a", "data": { "task_id": "cgt-20251222073134-54qcw", "status": "succeeded", "video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4", "model": "doubao-seedance-1-0-pro-250528" } } ``` 결과의 `task_id` 필드는 요청 시 반환된 것과 일치하며, 이 필드를 통해 작업의 연관성을 구현할 수 있습니다. ## 오류 처리 API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어: * `400 token_mismatched`: 잘못된 요청, 누락되거나 잘못된 매개변수 때문일 수 있습니다. * `400 api_not_implemented`: 잘못된 요청, 누락되거나 잘못된 매개변수 때문일 수 있습니다. * `401 invalid_token`: 인증되지 않음, 잘못되었거나 누락된 인증 토큰. * `429 too_many_requests`: 너무 많은 요청, 비율 제한을 초과했습니다. * `500 api_error`: 내부 서버 오류, 서버에서 문제가 발생했습니다. ### 오류 응답 예시 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 결론 이 문서를 통해 SeeDance Videos Generation API를 사용하여 프롬프트, 참고 이미지 및 Seedance 2.0의 얼굴/캐릭터 참조를 통해 비디오를 생성하는 방법을 이해하셨습니다. 이 문서가 API를 더 잘 연결하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주십시오.