SeeDance 비디오 생성 API 연동 설명

본 문서에서는 SeeDance 비디오 생성 API 연동 방법을 소개합니다. 이 API는 사용자 정의 매개변수를 입력하여 SeeDance 공식 비디오를 생성할 수 있습니다.

신청 절차

SeeDance 비디오 생성 API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API 토큰을 받아야 하며, 이를 보관해 두십시오.

로그인 또는 등록이 되어 있지 않은 경우, 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 요청합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있습니다; 할당량이 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.

📘 전체 문서: SeeDance 비디오 생성 API →

기본 사용법

먼저 기본 사용 방법을 이해해야 합니다. 즉, 입력 프롬프트 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” 버튼을 클릭하면 테스트를 진행할 수 있으며, 위 그림과 같이 다음과 같은 결과를 얻을 수 있습니다:

{
  "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의 코드는 다음과 같습니다:

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 매개변수를 통해 오디오가 포함된 비디오를 생성할 수 있습니다:

{
  "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 오류가 반환됩니다.

해당 코드:

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 유형을 입력하여 프롬프트 힌트를 제공해야 합니다.

해당 코드:

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: 인물 외모를 유지한 클로즈업

인물의 얼굴 사진을 전달하여 해당 인물이 카메라를 향해 미소를 지으며 손을 흔들게 합니다. 해당 코드:

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)

반환 결과는 다음과 같으며, 생성된 비디오에서 인물은 참고 사진과 일치합니다:

{
  "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의 강력한 점은: 인물의 정체성만 유지하고, 장면, 의상, 동작은 전적으로 프롬프트에 의해 결정된다는 것입니다. 아래는 같은 얼굴 사진을 사용하여 해당 인물이 베이지색 코트를 입고 가을 공원에서 걷는 장면입니다:

{
  "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
}

반환 결과는 다음과 같으며, 인물의 외모는 유지되었고 장면은 가을 공원으로 변경되었습니다:

{
  "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가 포함되어 있어 연관성을 유지합니다.

{
  "task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}

작업이 완료되면 플랫폼이 callback_url로 푸시하는 내용은 다음과 같습니다:

{
  "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: 내부 서버 오류, 서버에서 문제가 발생했습니다.

오류 응답 예시

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

결론

이 문서를 통해 SeeDance Videos Generation API를 사용하여 프롬프트, 참고 이미지 및 Seedance 2.0의 얼굴/캐릭터 참조를 통해 비디오를 생성하는 방법을 이해하셨습니다. 이 문서가 API를 더 잘 연결하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주십시오.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

프록시

고급

SeeDance 비디오 생성 API 연동 설명

신청 절차

기본 사용법

인라인 매개변수 설명

음성 비디오 생성

이미지로 비디오 첫 프레임 생성

이미지로 비디오 첫 및 마지막 프레임 생성

얼굴 및 캐릭터 참조 (Seedance 2.0)

예시 1: 인물 외모를 유지한 클로즈업

예시 2: 같은 인물을 새로운 장면에 배치하기

비동기 콜백

오류 처리

오류 응답 예시

결론

​신청 절차

​기본 사용법

​인라인 매개변수 설명

​음성 비디오 생성

​이미지로 비디오 첫 프레임 생성

​이미지로 비디오 첫 및 마지막 프레임 생성

​얼굴 및 캐릭터 참조 (Seedance 2.0)

​예시 1: 인물 외모를 유지한 클로즈업

​예시 2: 같은 인물을 새로운 장면에 배치하기

​비동기 콜백

​오류 처리

​오류 응답 예시

​결론

신청 절차

기본 사용법

인라인 매개변수 설명

음성 비디오 생성

이미지로 비디오 첫 프레임 생성

이미지로 비디오 첫 및 마지막 프레임 생성

얼굴 및 캐릭터 참조 (Seedance 2.0)

예시 1: 인물 외모를 유지한 클로즈업

예시 2: 같은 인물을 새로운 장면에 배치하기

비동기 콜백

오류 처리

오류 응답 예시

결론