curl 예제를 다룹니다.
변형
모든 변형은 비동기입니다.
POST /api/v1/video/queue로 제출한 뒤 응답 본문이 video/mp4가 될 때까지 POST /api/v1/video/retrieve를 폴링하세요. 일반 큐 흐름은 Video Generation을 참고하세요.
resolution은 다음 중 하나로 전달하세요: 480p, 720p, 1080p 또는 4k(소문자). Seedance 2.0(non-Fast)은 네 가지 모두 허용합니다. 2.0 Fast와 2.5는 480p / 720p만 허용합니다. 실시간 모델 ID와 기능은 GET /models?type=video로 확인하며, 사용 가능 여부를 하드코딩하지 마세요.
”하나의 모델, 네 가지 워크플로우” 모델
reference-to-video 변형(seedance-2-0-reference-to-video-basic, 그 Fast 형제, 그리고 seedance-2-5-reference-to-video-basic)은 동일한 프롬프트 라우팅 패턴을 사용합니다. 모델은 프롬프트 접두어와 입력의 형태로부터 작업을 추론합니다. 별도의 task나 workflow 필드는 없으며, 프롬프트 문법 자체가 라우팅입니다.
프롬프트 문법은 표준이며 대소문자를 구분합니다: 꺾쇠 괄호, 첫 글자 대문자, 숫자 앞 공백 하나 —
<Video 1>, <Image 1>, <Audio 1>.
워크플로우 패턴
Reference 워크플로우
업로드된 레퍼런스 파일을 도너(subject, scene, motion, style, vocal timbre)로 사용해 완전히 새로운 비디오를 생성합니다. 표준 프롬프트 패턴:Refer to <Subject 1> in <Image 1> to generate a 5-second clip of the same character riding a horse through snow.Refer to the camera scene in <Video 1> to generate a similar establishing shot of a futuristic city at dawn.Refer to <Subject 1> in <Image 1> and use the timbre in <Audio 1> for the narrator describing the scene.(오디오 도너는 최소한 하나의 이미지 또는 비디오 레퍼런스와 함께 사용해야 하며, 오디오 단독은 거부됩니다)
Edit 워크플로우
단일 입력 비디오를 수정합니다. 프롬프트에서 명시적으로 언급되지 않은 것은 보존됩니다. 완전히 새로운 비디오가 아니라 국소적 변경(subject 교체, 날씨/색상 변경, 요소 추가/삭제)을 원할 때 사용하세요. 표준 프롬프트 패턴:Strictly edit <Video 1>, changing its weather from sunny to a heavy rainstorm.Add snacks such as fried chicken and pizza to the countertop in <Video 1>.Remove the red car from <Video 1>, keeping the rest of the video content unchanged.Replace the perfume featured in <Video 1> with the face cream from <Image 1>, with all original motions and camera work preserved.
<Image 1>을 대체 요소의 시각적 도너로 사용합니다.
소스와 일치하는 종횡비 및 길이
Seedance reference-to-video edit / extend에서는 고정된 비율이나 길이를 지정하는 대신, 출력이 소스 클립을 따라가도록 요청할 수 있습니다:
요구 사항:
- Queue: 소스와 일치하는 값을 사용하려면
reference_video_urls가 필요합니다. - Quote: 소스와 일치하는 값을 사용하려면
reference_video_total_duration이 필요합니다. 소스와 일치하는 duration은ceil(reference_video_total_duration)초로 청구됩니다. - 종횡비와 길이는 독립적입니다 — 하나만 소스와 일치시키고 다른 하나는 지정할 수 있습니다.
- Extend의 경우, 고정된
duration(얼마나 생성할지)을 지정하고 선택적으로aspect_ratio: "adaptive"를 사용하는 것이 좋습니다. 소스와 일치하는duration은 “소스와 동일한 길이” edit 스타일 작업을 위한 것입니다.
Extend 워크플로우
단일 클립을 시간적으로 앞이나 뒤로 이어갑니다. 기본적으로 Seedance는 새 콘텐츠만 반환하며, 원본 입력에 확장분을 이어붙인 결과를 반환하지 않습니다. 이는 전환 연속성을 위한 의도적 설계입니다. 확장분과 함께 입력 클립을 보존하고 싶다면 명시적으로 지정하세요:Extend <Video 1>, generate a dramatic chase scene through narrow alleys at dusk.Extend <Video 1> backward, the same character walking toward the camera before the original shot begins.Extend <Video 1>, start with <Video 1>, then the camera pulls back to reveal a vast landscape.
Stitch 워크플로우 (트랙 완성)
AI가 생성한 전환으로 입력 클립을 연결합니다. 패밀리별 결합 길이 및 클립 수 제한을 멀티모달 입력 제한에서 확인하세요 (Seedance 2.0: 클립 ≤3개 / 결합 ≤15초; Seedance 2.5: 더 높은 비디오 제한). 표준 프롬프트 패턴:<Video 1> + a smooth seamless cut + followed by <Video 2><Video 1>. The moment a leaf falls to the ground, it sets off a special effect of golden particles. A gust of wind blows by, leading into <Video 2>.<Video 1> + a wisp of smoke transforms into a flock of birds + followed by <Video 2> + a slow dolly-in + followed by <Video 3>
범용 프롬프트 공식
네 가지 워크플로우 모두에서 권장되는 작성 공식은 다음과 같습니다:- Subject + Motion: 논리적 토대 — “누가” “어떤 행동”을 하는지 정의
- Environment + Aesthetics: 공간적 배경, 조명, 시각적 스타일
- Camera: 명시적 샷 유형 또는 움직임
- Audio: 몰입감 있는 출력을 위한 배경 효과음이나 음성 방향
Strictly edit <Video 1>, changing its <subject + motion + environment + ...>) 최고 품질의 출력을 얻을 수 있습니다.
멀티모달 입력 제한
아래 값은 Venice API가 수용하는 범위입니다. 범위 밖의 요청은 추론에 도달하기 전에 스키마 계층에서 400으로 거부됩니다. Seedance 2.0과 Seedance 2.5는 서로 다른 제한을 사용합니다. 호출 중인 모델 패밀리의 컬럼을 반드시 확인하세요.공통 미디어 하한
패밀리 비교
레퍼런스 오디오는 R2V 변형에서만 지원됩니다. 각 항목은
role: "reference_audio" 콘텐츠 항목으로 모델에 전달되며, 프롬프트에서는 <Audio 1>, <Audio 2>, … 로 참조합니다. 모델은 프롬프트가 어떻게 표현하는지에 따라 각 클립을 vocal timbre, 효과음 또는 배경 음악으로 사용합니다. 기존의 단수형 audio_url 필드는 동일한 콘텐츠 형태로 매핑되며, 이제 한 요소짜리 reference_audio_urls를 전달하는 것과 동일합니다.
요청 크기
큐 엔드포인트는 최대 35 MB의 JSON 본문을 허용합니다. 큰 비디오의 인라인 data URL은 이를 넘길 수 있으므로 — 특히 다중 클립 Stitch의 경우 — 인라인 base64보다 URL 사용을 권장합니다.요금
/video/queue에 제출하기 전에 주어진 요청 형태에 대한 견적을 얻으려면 POST /api/v1/video/quote를 호출하세요. quote 엔드포인트가 유일한 권위 있는 출처이며, 가격 세부 정보는 변경될 수 있으므로 클라이언트 측에 캐시하거나 중복 저장해서는 안 됩니다.
요청에 레퍼런스 비디오가 포함된 경우, quote가 /video/queue의 청구액과 일치하도록 reference_video_total_duration(모든 레퍼런스 클립 길이의 초 단위 합계)을 함께 전달하세요:
전체 예제
모든 예제는 환경 변수VENICE_API_KEY가 설정되어 있다고 가정합니다.
Text-to-video
Seedance 2.0 text-to-video (4K)
Seedance 2.5 text-to-video (더 긴 길이)
Image-to-video (첫 프레임)
Seedance I2V 모델(
seedance-2-0-image-to-video-basic, 그 Fast 변형, seedance-2-5-image-to-video-basic)은 aspect_ratio를 허용하지 않습니다 — 출력 종횡비는 입력 이미지의 크기에서 자동으로 도출됩니다. 이 필드를 전달하면 “This model does not support aspect_ratio” 메시지와 함께 400이 반환됩니다. 명시적 종횡비 제어가 필요하면 T2V 또는 R2V 변형을 사용하세요.Reference 워크플로우 — subject 도너
Seedance 2.5 Reference 워크플로우 — 다중 이미지
Reference 워크플로우 — subject + 오디오 도너
Edit 워크플로우
Seedance 2.5 edit — 소스와 일치하는 duration 및 종횡비
duration: "auto"(또는 "-1")와 aspect_ratio: "adaptive"(또는 "auto")를 사용하면 출력이 소스 클립을 따릅니다. 소스와 일치하는 종횡비 및 길이를 참고하세요.
이미지 기반이 있는 Edit 워크플로우
Extend 앞으로
Stitch (3 클립)
완료 폴링
큐에 제출할 때마다 반환된queue_id를 저장하고, 응답 본문이 video/mp4가 될 때까지 /video/retrieve를 폴링하세요:
{ "status": "queued" | "running" | "failed", ... })이며, 완료 시 응답 본문이 video/mp4 바이트로 전환됩니다. 전체 폴링 패턴은 Video Generation을 참고하세요.
문제 해결
At least one reference is required for this model
reference-to-video 제출은 reference_image_urls, reference_video_urls, image_references 또는 video_references 중 최소 하나를 포함해야 합니다. 순수 텍스트 전용 생성은 유효한 R2V 워크플로우가 아니므로 text-to-video 모델 ID를 대신 사용하세요. reference_audio_urls만으로는 충분하지 않습니다(위 Audio 섹션 참고).
너무 많은 레퍼런스 비디오 / 이미지
Seedance 2.0은 R2V를 이미지 9개 및 비디오 3개로 제한합니다. Seedance 2.5는 이 제한을 이미지 30개 및 비디오 10개로 상향합니다. 패밀리 제한을 초과하면 입력을 정리하거나 오프라인에서 먼저 스티치하세요.길이 / 결합 길이 오류
- 2.0: 클립당 레퍼런스 비디오/오디오
[2, 15]초; 결합 비디오/오디오 ≤ 15 초; 출력 4–15 초. - 2.5: 클립당 레퍼런스 비디오/오디오
[2, 30]초; 결합 비디오/오디오 ≤ 30 초; 출력 4–30 초. - 소스와 일치하는 duration (Seedance 2.5의
-1/auto): 소스 클립은 4–30초여야 하며,reference_video_urls(queue) 또는reference_video_total_duration(quote)이 필요합니다.
프롬프트가 잘못된 워크플로우로 라우팅됨
워크플로우는 프롬프트 문법으로부터 추론됩니다. 흔한 잘못된 라우팅:- Extend를 원하지만
Refer to ...로 작성 → 모델이 비디오를 이어갈 캔버스가 아닌 도너로 취급 - Stitch를 원하지만
Refer to ...로 작성 → 모델이 하나를 도너로 선택하고 나머지는 무시 - Edit을 원하지만
Generate a video based on <Video 1>으로 작성 → 모호함; 모델이 Reference로 기본 처리할 수 있음
Strictly edit <Video 1>, ..., Extend <Video 1>, ..., <Video 1> + ... + followed by <Video 2>.
인물이 포함된 미디어 미지원
공개 Seedance API 모델은 동의 증명 흐름(consents.seedance / needs_consent)을 실행하지 않습니다. 감지 가능한 인물이 포함된 미디어는 콘텐츠 정책 또는 공급자 오류로 실패할 수 있습니다. 대신 Venice 앱 또는 Studio를 사용하세요.
견적이 큐에 청구된 금액과 일치하지 않음
레퍼런스 비디오를 포함시켰지만/video/quote에 reference_video_total_duration을 전달하지 않았다면, 견적과 큐 청구액이 다를 수 있습니다. 레퍼런스 비디오가 있는 경우 항상 reference_video_total_duration(모든 레퍼런스 클립 길이의 초 단위 합계)을 전달하세요.
참조
- Venice 비디오 큐 엔드포인트:
POST /api/v1/video/queue - Venice quote 엔드포인트:
POST /api/v1/video/quote - 관련 가이드: Reference to Video (Kling O3 + Grok Imagine R2V를 다룸)
- 관련 가이드: Video Generation (큐/폴링 개요)