신청 절차
SeeDance Videos Generation API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 발급받아 예비용으로 보관하세요.
아직 로그인 또는 등록하지 않은 경우, 로그인 페이지로 자동 이동하여 등록과 로그인을 안내하며, 완료 후 현재 페이지로 자동 돌아옵니다.
하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스마다 별도로 신청할 필요가 없습니다. 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 콘솔에서 공통 잔액을 충전할 수 있습니다.
📘 전체 문서: SeeDance Videos Generation API →
기본 사용법
먼저 기본 사용 방식을 살펴보겠습니다. 프롬프트content.text, 유형 content.type=text, 그리고 모델 model을 입력하면 처리된 결과를 얻을 수 있으며, 구체적인 내용은 다음과 같습니다:

accept: 어떤 형식의 응답 결과를 받을지 지정하며, 여기서는 JSON 형식인application/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.5:
doubao-seedance-2-5-260628, 최대 30초, 순수 오디오 참조, 더 많은 소재, 동영상 편집 및 연장을 지원합니다.
- Seedance 1.x 시리즈:
content: 입력 콘텐츠 배열이며,type은text(프롬프트),image_url(참조 이미지),audio_url(참조 오디오),video_url(참조 동영상)일 수 있습니다. 이미지는role을 통해 용도를 지정할 수 있습니다:first_frame(첫 프레임) /last_frame(마지막 프레임) /reference_image(캐릭터 / 주체 참조).resolution: 출력 해상도이며,480p/720p/1080p/4k를 선택할 수 있습니다. 2.5는 480p, 720p, 1080p를 지원하며, 2.0 Fast/Mini는 480p, 720p를 지원하고, 2.0 Standard는 최대 4k를 지원합니다.ratio: 가로세로 비율이며,16:9/4:3/1:1/3:4/9:16/21:9/adaptive를 선택할 수 있습니다.duration: 동영상 길이(초, 정수)입니다. 1.0 시리즈는 2–12, 1.5 Pro는 4–12, 2.0 시리즈는 4–15, 2.5는 4–30입니다. 1.5/2.x는-1(자동 길이)을 지원합니다.seed: 랜덤 시드이며, 정수이고 -1부터 4294967295까지입니다.camerafixed: 카메라 고정 여부이며,true/false입니다.watermark: 워터마크 추가 여부이며,true/false입니다.generate_audio: 오디오가 포함된 동영상 생성 여부이며,true/false이고, Seedance 1.5 Pro 및 2.x 시리즈에서 지원합니다.return_last_frame: 결과에 동영상 마지막 프레임 이미지 URL을 반환할지 여부입니다.omni_reference_task_type: 2.5 전용이며,auto/reference/edit/extend입니다.output_format: 2.5 전용이며,mp4/mov이고 기본값은mp4입니다.tools: 2.5 전용이며, 현재web_search온라인 검색 도구를 지원하고 결과 수, 키워드 수 및 검색 소스를 제한할 수 있습니다.priority: 2.5의 선택 가능한 작업 우선순위이며, 정수 0–9이고 기본값은 0입니다.safety_identifier: 최대 64자 길이의 안정적인 익명 최종 사용자 식별자입니다. 해시 또는 내부 익명 ID를 사용하고, 이름, 이메일 또는 휴대폰 번호를 전달하지 마세요.execution_expires_after: 작업 타임아웃 시간(초)이며, 범위는 3600–259200입니다.callback_url: 비동기 콜백 주소이며, 설정 후 API는 즉시task_id를 반환하고 작업 완료 시 결과를 해당 주소로 POST합니다.async: 선택 사항이며,true로 설정하면 인터페이스가 즉시task_id를 반환하고callback_url을 제공할 필요가 없으며, 이후 해당 작업 조회 인터페이스를 통해 폴링하여 결과를 가져옵니다.

success, 이때 동영상 생성 작업의 상태입니다.task_id, 이때 동영상 생성 작업 ID입니다.trace_id, 이때 동영상 생성 추적 ID입니다.data, 이때 동영상 생성 작업의 결과 목록입니다.task_id, 이때 동영상 생성 작업의 서버 측 ID입니다.video_url, 이때 동영상 생성 작업의 동영상 링크입니다.status, 이때 동영상 생성 작업의 상태입니다.model, 동영상 생성에 사용된 모델입니다.
data의 동영상 링크 주소를 통해 생성된 SeeDance 동영상을 가져오기만 하면 됩니다.
또한 해당 연동 코드를 생성하려면 직접 복사하여 생성할 수 있으며, 예를 들어 CURL 코드는 다음과 같습니다:
인라인 파라미터 설명
content[].text 프롬프트 끝에 --parameter value 형식으로 생성 파라미터를 추가하여 전달할 수 있습니다(이전 방식, 약한 검증, 잘못 입력한 경우 자동으로 기본값 사용). 전체 파라미터 목록은 다음과 같습니다:
권장 방법:Request Body에서 직접 대응되는 최상위 필드(예:resolution,ratio등)를 사용하세요. 이는 강한 검증 모드이며, 파라미터를 잘못 입력한 경우 명확한 오류 메시지를 반환하므로 문제를 더 쉽게 추적할 수 있습니다.
오디오 포함 영상 생성
Seedance 1.5 Pro 및 2.x 시리즈는generate_audio 파라미터를 통해 오디오가 포함된 영상을 생성할 수 있습니다:
Seedance 2.5 옴니모달 생성, 편집 및 연장
doubao-seedance-2-5-260628은 480p / 720p / 1080p, 4–30초 또는 자동 길이를 지원하며, 자료 한도를 참조 이미지 30장, 참조 영상 10개, 참조 오디오 10개(총 최대 50개)로 늘렸습니다. 2.5는 참조 오디오만 전달하는 것도 지원하며, 더 이상 이미지나 영상을 함께 제공할 필요가 없습니다.
일반 옴니모달 생성에서는 omni_reference_task_type을 생략하거나 auto로 설정하거나, 명시적으로 reference로 설정할 수 있습니다. 영상 편집 및 연장은 반드시 reference_video를 전달해야 합니다:
reference:최소 하나의reference_image,reference_video또는reference_audio를 전달합니다. 2.5는 참조 오디오만 전달하는 것을 지원합니다.edit:반드시ratio: adaptive및duration: -1을 사용해야 합니다. 출력 길이는 실제 결과에 따라 과금됩니다.extend:반드시ratio: adaptive를 사용해야 합니다.duration은 4–30 또는-1일 수 있습니다.auto:모델이 프롬프트와 자료에 따라 생성, 편집 또는 연장을 자동으로 선택합니다.- 작업 유형이 자료 또는 프롬프트와 일치하지 않으면 작업이 실패하고 위치를 파악할 수 있는 파라미터 오류를 반환합니다. 위 제약 조건에 따라 조정한 후 다시 제출하세요.
이미지 기반 영상 첫 프레임
이미지 기반 영상 작업을 하려면 먼저content 파라미터에 type이 image_url인 항목이 포함되어야 하며, image_url 필드는 반드시 객체 형식이어야 합니다: {"url": "https://..."} 또는 Base64 형식 {"url": "data:image/png;base64,..."}.
주의:대응하는 코드:image_url은 문자열 형식(예:"image_url": "https://cdn.acedata.cloud/e724d7f13d.png")을 직접 전달하는 것을 지원하지 않으며, 반드시 객체 형식"image_url": {"url": "https://..."}을 사용해야 합니다. 그렇지 않으면 400 오류가 반환됩니다.
이미지 기반 영상 첫 프레임 및 마지막 프레임
이미지 기반 영상의 첫 프레임 및 마지막 프레임을 만들려면, 먼저 파라미터content에 유형 image_url을 전달하고, 각각 role을 first_frame 및 last_frame으로 설정하면 다음 내용을 지정할 수 있습니다:
- role:첫 프레임 또는 마지막 프레임을 지정합니다.
- image_url
- url 이미지 링크
동시에
content에는 prompt 프롬프트로서 유형text도 입력해야 합니다
- url 이미지 링크
동시에
캐릭터 및 오디오·비디오 멀티모달 참조(Seedance 2.0)
Seedance 2.0 시리즈(doubao-seedance-2-0-260128、doubao-seedance-2-0-fast-260128、doubao-seedance-2-0-mini-260615)는 reference_image, reference_audio 및 reference_video를 지원합니다. 자체 보유하거나 권한을 획득한 소재를 사용하여 캐릭터, 피사체, 동작, 카메라 워크, 사운드 및 리듬의 일관성을 유지할 수 있습니다.
자체 보유하거나 권한을 획득한 실제 인물 및 캐릭터 소재만 업로드하세요. 모델마다 실제 인물 소재를 지원하는 방식이 다릅니다. 요청 형식은 동일하게 유지되며, 소재가 요구 사항에 부합하지 않으면 명확한 오류가 반환됩니다.사용 핵심 사항:
reference_image는 Seedance 2.0 시리즈 모델만 지원합니다. 1.x 모델에서는first_frame/last_frame(이미지-비디오 생성의 첫·마지막 프레임)을 사용하세요.- 이미지-비디오 생성 첫 프레임, 이미지-비디오 생성 첫·마지막 프레임, 전체 모달 참조는 서로 배타적인 세 가지 시나리오입니다.
first_frame/last_frame는reference_image/reference_video/reference_audio와 함께 사용할 수 없습니다. - 전체 모달 참조에서 첫·마지막 프레임을 지정하려면 이미지를
reference_image로 표시하고, 프롬프트에 “이미지 1을 첫 프레임으로” 또는 “이미지 2를 마지막 프레임으로”라고 명시하세요. 첫·마지막 프레임을 엄격하게 고정해야 한다면first_frame/last_frame만 사용하세요. - 멀티모달 참조 수량 한도:
image_url은 최대 9장입니다. 2.0은audio_url(role은reference_audio, 최대 3개)과video_url(role은reference_video, 최대 3개)도 지원합니다. - 참조 오디오(
audio_url) 소재 요구 사항: 형식은wav/mp3; 각 항목 길이는 2~15초, 최대 3개이며 총 길이는 15초를 초과할 수 없음; 각 항목은 15MB를 초과할 수 없습니다. 길이 범위를 초과하면 소재 처리 단계에서 실패합니다. - 참조 비디오(
video_url) 소재 요구 사항: 형식은mp4/mov; 각 항목 길이는 2~15초, 최대 3개이며 총 길이는 15초를 초과할 수 없음. - 참조 이미지는 한 명, 정면 얼굴, 선명함, 가림 없음의 사진을 권장합니다. 얼굴이 선명할수록 유사도가 높아집니다.
예시 1: 인물 외모를 유지하는 클로즈업
얼굴 사진 한 장을 전달하여, 해당 인물이 카메라를 향해 미소 짓고 손을 흔들게 합니다. 해당 코드:예시 2: 같은 인물을 완전히 새로운 장면에 배치하기
reference_image의 강력한 점은 인물 정체성만 유지하고, 장면, 의상, 동작은 모두 프롬프트로 결정된다는 것입니다. 아래에서는 같은 얼굴 사진을 사용하여 해당 인물이 베이지색 코트를 입고 가을 공원을 걷게 합니다:
💡 인물이 사진 속 구도를 정확하게 재현하도록 하려면(「다른 장면의 같은 인물」이 아니라), first_frame(이미지-비디오 첫 프레임)을 대신 사용하여 이 사진에서부터 영상이 움직이도록 할 수 있습니다.
비동기 콜백
SeeDance Videos Generation API의 생성 시간은 비교적 길기 때문에(약 1~2분),callback_url 필드를 통해 비동기 모드를 사용할 수 있으며, HTTP 연결이 장시간 점유되는 것을 방지할 수 있습니다.
전체 프로세스: 클라이언트가 요청을 시작할 때 callback_url을 지정하면, API는 즉시 task_id가 포함된 응답을 반환합니다. 작업이 완료된 후 플랫폼은 생성 결과를 POST JSON 형식으로 callback_url에 전송하며, 결과에도 연결을 위해 동일하게 task_id가 포함됩니다.
callback_url로 푸시합니다:
task_id 필드는 요청 시 반환된 값과 일치하며, 이 필드를 통해 작업을 연결할 수 있습니다.
오류 처리
API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예:400 token_mismatched:잘못된 요청이며, 매개변수가 누락되었거나 유효하지 않기 때문일 수 있습니다.400 api_not_implemented:잘못된 요청이며, 매개변수가 누락되었거나 유효하지 않기 때문일 수 있습니다.401 invalid_token:권한이 없으며, 인증 토큰이 유효하지 않거나 누락되었습니다.429 too_many_requests:요청이 너무 많으며, 속도 제한을 초과했습니다.500 api_error:내부 서버 오류이며, 서버에서 문제가 발생했습니다.

