신청 절차
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.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 형식으로 생성 매개변수를 추가하여 전달할 수 있습니다(구식 방식, 약한 검증, 잘못 입력 시 자동으로 기본값 사용). 전체 매개변수 목록은 다음과 같습니다:
권장 방법: 요청 본문에서 해당 최상위 필드(예: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에는 프롬프트로 사용할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를 지원합니다. 자사 또는 허가된 자료를 사용하여 캐릭터, 주체, 동작, 카메라 움직임, 소리 및 리듬의 일관성을 유지할 수 있습니다.
반드시 자사 또는 허가된 실제 인물 및 캐릭터 자료만 업로드하십시오. 서로 다른 모델은 실제 인물 자료에 대한 지원 방식이 다릅니다; 요청 형식은 변하지 않으며, 자료가 요구 사항에 부합하지 않으면 명확한 오류가 반환됩니다.사용 요점:
- 오직 Seedance 2.0 시리즈 모델만
reference_image를 지원합니다; 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:내부 서버 오류, 서버에서 문제가 발생했습니다.

