curl 예시를 다룹니다.
변형(Variants)
모든 변형은 비동기입니다.
POST /api/v1/video/queue로 제출한 다음, 응답 본문이 video/mp4가 될 때까지 POST /api/v1/video/retrieve로 폴링하세요. 일반적인 큐 흐름은 Video Generation을 참고하세요.
”하나의 모델, 네 가지 워크플로” 모델
reference-to-video 변형(seedance-2-0-reference-to-video와 그의 Fast 형제)은 네 가지 다른 작업을 처리하는 동일한 기반 모델입니다. 모델은 prompt prefix와 input 형태에서 작업을 추론합니다. task나 workflow 필드가 없습니다 — prompt 문법이 라우팅입니다.
Prompt 문법은 표준이며 대소문자 구분합니다: 꺾쇠 괄호, 대문자 첫 글자, 숫자 앞 단일 공백 —
<Video 1>, <Image 1>, <Audio 1>.
워크플로 패턴
Reference 워크플로
업로드된 레퍼런스 파일을 도너 — 피사체, 장면, 모션, 스타일, 목소리 음색 — 로 사용해 완전히 새로운 비디오를 생성합니다. 표준 prompt 패턴: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 워크플로
하나의 input 비디오를 수정합니다. prompt에 명시되지 않은 것은 모두 보존됩니다. 완전히 새로운 비디오가 아닌 국소적 변경(피사체 교체, 날씨/색상 변경, 요소 추가/제거)을 원할 때 사용하세요. 표준 prompt 패턴: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>을 교체 대상의 시각적 도너로 사용합니다.
Extend 워크플로
한 클립을 시간상 앞으로 또는 뒤로 이어갑니다. 기본적으로 Seedance는 새 콘텐츠만 반환합니다 — 원본 input이 확장과 함께 이어진 형태가 아닙니다. 이는 전환 연속성을 위한 의도된 동작입니다. input 클립을 확장과 함께 보존하고 싶다면 명시적으로 그렇게 말하세요: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 워크플로(Track Completion)
2-3개의 input 클립을 AI 생성 전환으로 연결합니다. 결합된 input 총 길이는 15초 이하여야 합니다. 표준 prompt 패턴:<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>
범용 prompt 공식
네 가지 워크플로 모두에서 권장되는 작성 공식:- Subject + Motion: 논리적 기반 — “누가” “어떤 행동”을 하는지 정의
- Environment + Aesthetics: 공간 배경, 조명, 시각 스타일
- Camera: 명시적 샷 유형 또는 움직임
- Audio: 몰입감 있는 출력을 위한 환경음 또는 보이스 디렉션
Strictly edit <Video 1>, changing its <subject + motion + environment + ...>) 위에 레이어링하면 최고 품질의 출력을 만들어냅니다.
멀티모달 input 한도
아래 값은 Venice API가 허용하는 값입니다. 이 범위를 벗어나는 요청은 추론에 도달하기 전 스키마 레이어에서 400으로 거부됩니다.이미지
비디오
오디오
레퍼런스 오디오는 R2V 변형에서만 지원됩니다. 각 항목은 모델에
role: "reference_audio" 콘텐츠 항목으로 전달되며, prompt는 <Audio 1>, <Audio 2>, <Audio 3>으로 주소를 지정합니다 — 모델은 prompt가 그것을 어떻게 프레이밍하느냐에 따라 각 클립을 보이스 음색, 효과음, 배경 음악에 사용합니다. 레거시 단수 audio_url 필드는 같은 콘텐츠 형태로 매핑되며, 이제 한 개 요소 reference_audio_urls를 전달하는 것과 동등합니다.
요청 크기
queue endpoint는 최대 35 MB의 JSON 본문을 받습니다. 대용량 비디오의 인라인 data URL은 이를 초과할 수 있습니다 — 특히 멀티 클립 Stitch에서는 인라인 base64보다 URL을 선호하세요.가격
/video/queue에 제출하기 전에 주어진 요청 형태에 대한 견적을 받으려면 POST /api/v1/video/quote를 호출하세요. quote endpoint가 유일한 권위 있는 출처입니다. 가격 세부 사항은 변경될 수 있으며 클라이언트 측에서 캐시하거나 복제해서는 안 됩니다.
레퍼런스 비디오가 요청에 포함되어 있으면, 견적이 /video/queue가 부과하는 금액과 일치하도록 reference_video_total_duration(모든 레퍼런스 클립 길이의 합, 초 단위)도 전달하세요:
완전한 예시
모든 예시는VENICE_API_KEY가 환경에 설정되어 있다고 가정합니다.
Text-to-video
Image-to-video(first frame)
seedance-2-0-image-to-video(와 그의 Fast 변형)는 aspect_ratio를 받지 않습니다 — 출력 종횡비는 입력 이미지의 크기에서 자동 파생됩니다. 필드를 전달하면 “This model does not support aspect_ratio” 와 함께 400을 반환합니다. 명시적 종횡비 제어가 필요하면 T2V 또는 R2V 변형을 사용하세요.Reference 워크플로 — 피사체 도너
Reference 워크플로 — 피사체 + 오디오 도너
Edit 워크플로
이미지 그라운딩이 있는 Edit 워크플로
Extend forward
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 워크플로가 아닙니다 — 대신 seedance-2-0-text-to-video를 사용하세요. reference_audio_urls만으로는 충분하지 않습니다(위 Audio 섹션 참고).
reference_video_urls must have at most 3 videos
모델은 레퍼런스 비디오를 3개로 제한합니다. 더 많은 클립이 필요하면 먼저 Stitch를 실행(3 → 1)한 다음 그 출력을 후속 작업의 레퍼런스로 사용하세요.
Per clip must be 2–15s / 합계 > 15s
클립당 길이는 [2, 15] 초 포함이며, 모든 레퍼런스 비디오의 합도 15초로 제한됩니다. 제출 전 클라이언트 측에서 클립을 트림하세요.
Prompt가 잘못된 워크플로로 라우팅됨
워크플로는 prompt 문법에서 추론됩니다. 흔한 잘못된 라우팅:- 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>.
견적이 큐 금액과 일치하지 않음
레퍼런스 비디오를 포함했지만reference_video_total_duration을 /video/quote에 전달하지 않았다면 견적과 큐 금액이 다를 수 있습니다. 레퍼런스 비디오가 있을 때는 항상 reference_video_total_duration(모든 레퍼런스 클립 길이의 합, 초 단위)을 전달하세요.
참고 자료
- Venice 비디오 큐 endpoint:
POST /api/v1/video/queue - Venice 견적 endpoint:
POST /api/v1/video/quote - 동반 가이드: Reference to Video(Kling O3 + Grok Imagine R2V 다룸)
- 동반 가이드: Video Generation(큐 / 폴링 개요)