# Seedance 2.0 API ByteDance의 Seedance 2.0 동영상 생성 모델에 대한 전체 API 참조 문서입니다. ## 모델 종류 이 API는 여섯 가지 모델을 지원합니다. | 모델 | ID | 설명 | |-------|-----|-------------| | **Seedance 2.0 Text to Video** | `seedance-v2.0-text-to-video` | 고품질 텍스트 기반 동영상 생성 | | **Seedance 2.0 Image to Video** | `seedance-v2.0-image-to-video` | 동작 제어를 통한 이미지 애니메이션 생성 | | **Seedance 2.0 Reference to Video** | `seedance-v2.0-reference-to-video` | 참조 동영상을 활용한 동영상 생성 | | **Seedance 2.0 Fast Text to Video** | `seedance-v2.0-fast-text-to-video` | 더 빠른 텍스트 기반 동영상 생성 | | **Seedance 2.0 Fast Image to Video** | `seedance-v2.0-fast-image-to-video` | 더 빠른 이미지 기반 동영상 생성 | | **Seedance 2.0 Fast Reference to Video** | `seedance-v2.0-fast-reference-to-video` | 더 빠른 참조 자료 기반 동영상 생성 | ## 빠른 비교 | 기능 | 표준 모델 | Fast 모델 | |---------|-----------------|-------------| | 품질 | 더 높은 품질 | 속도에 최적화 | | 처리 시간 | 3-8분 | 1-4분 | | 길이 범위 | 4-15초 | 4-15초 | | 해상도 옵션 | 480p, 720p, 1080p, 4k | 480p, 720p | | 참조 자료 | Reference-to-Video용 이미지, 동영상 및 오디오 | Fast Reference-to-Video용 이미지, 동영상 및 오디오 | ### 지원 화면 비율 `21:9`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4` ### 해상도 옵션 | 해상도 | 설명 | |------------|-------------| | `480p` | 표준 화질, 더 빠른 처리 | | `720p` | 고화질, 품질과 속도의 균형 | | `1080p` | Full HD, 모든 표준 Seedance 2.0 모델에서 사용 가능 | | `4k` | Ultra HD, 모든 표준 Seedance 2.0 모델에서 사용 가능 | ## Seedance 2.0 텍스트 기반 동영상 생성 ### 엔드포인트 ``` POST /api/v1/video/task ``` ### 요청 매개변수 #### 필수 | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `model_name` | string | `"seedance-v2.0-text-to-video"`여야 함 | | `prompt` | string | 동영상 생성 프롬프트 | | `duration` | integer | 동영상 길이: 정수 초 단위(4-15), 간격 1초 | | `resolution` | string | 출력 해상도: `"480p"`, `"720p"`, `"1080p"` 또는 `"4k"` | | `aspect_ratio` | string | 동영상 화면 비율: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` 또는 `"3:4"` | #### 선택 | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `sound` | boolean | 소리를 생성할지 여부. 기본값은 `true`이며 가격에 영향을 주지 않음 | ### 요청 예제 ```javascript const response = await fetch('https://api.flaq.ai/api/v1/video/task', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ model_name: 'seedance-v2.0-text-to-video', prompt: 'A golden retriever running through a sunlit meadow', duration: 6, resolution: '720p', aspect_ratio: '16:9' }) }); const { data } = await response.json(); const taskId = data.task_id; ``` ## Seedance 2.0 이미지 기반 동영상 생성 ### 요청 매개변수 #### 필수 | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `model_name` | string | `"seedance-v2.0-image-to-video"`여야 함 | | `prompt` | string | 동영상 생성 프롬프트 | | `duration` | integer | 동영상 길이: 정수 초 단위(4-15), 간격 1초 | | `resolution` | string | 출력 해상도: `"480p"`, `"720p"`, `"1080p"` 또는 `"4k"` | | `aspect_ratio` | string | 동영상 화면 비율: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` 또는 `"3:4"` | | `image_url` | string | 동영상의 첫 프레임 | #### 선택 | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `image_end_url` | string | 선택 사항인 마지막 프레임 이미지 URL | | `sound` | boolean | 소리를 생성할지 여부. 기본값은 `true`이며 가격에 영향을 주지 않음 | ### 요청 예제 ```javascript { model_name: 'seedance-v2.0-image-to-video', image_url: 'https://example.com/image.jpg', image_end_url: 'https://example.com/end-frame.jpg', prompt: 'Camera slowly pulls back to reveal the full landscape', duration: 6, resolution: '720p', aspect_ratio: '16:9' } ``` ## Seedance 2.0 참조 자료 기반 동영상 생성 ### 요청 매개변수 #### 필수 | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `model_name` | string | `"seedance-v2.0-reference-to-video"`여야 함 | | `prompt` | string | 동영상 생성 프롬프트. 자리표시자 없이 일반 프롬프트를 작성하거나, 선택적으로 @ (AT) 참조 기능과 `<<>>`, `<<>>`, `<<>>`를 사용해 해당 미디어 배열의 항목을 명시적으로 참조할 수 있음 | | `duration` | integer | 동영상 길이: 정수 초 단위(4-15), 간격 1초 | | `resolution` | string | 출력 해상도: `"480p"`, `"720p"`, `"1080p"` 또는 `"4k"` | | `aspect_ratio` | string | 동영상 화면 비율: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` 또는 `"3:4"` | #### 참조 자료 이미지 1-9장을 제출하세요. 참조 동영상을 하나 이상 제공하는 경우에만 이미지를 생략할 수 있습니다. | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `images` | string[] | 참조 이미지 URL 1-9개. `videos`가 비어 있지 않으면 빈 배열 사용 가능 | | `videos` | string[] | 참조 동영상 URL 최대 3개. 각 동영상은 2-15초이며 총길이는 최대 15초 | | `audios` | string[] | 참조 오디오 URL 최대 3개. 각 오디오는 2-15초이며 총길이는 최대 15초. WAV 또는 MP3, 파일당 최대 15 MB. 이미지 또는 동영상이 하나 이상 필요 | #### @ (AT) 참조 자리표시자 @ (AT) 참조 기능은 번호가 붙은 `<<<...>>>` 자리표시자로 참조 자료와 프롬프트를 연결합니다. 번호는 미디어 유형별로 각각 `1`부터 시작하며 해당 배열의 순서를 따릅니다. | 자리표시자 | 참조 값 | |-------------|------------------| | `<<>>` | `images[0]` | | `<<>>` | `images[1]` | | `<<>>` | `videos[0]` | | `<<>>` | `audios[0]` | 예를 들어 첫 번째 이미지가 캐릭터 참조이고 두 번째 이미지가 장면 참조라면, `prompt`에서 캐릭터에는 `<<>>`, 장면에는 `<<>>`를 사용합니다. 각 자리표시자는 해당 배열에 실제로 존재하는 항목을 가리켜야 합니다. #### 선택 | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `sound` | boolean | 동기화된 소리를 생성할지 여부. 기본값은 `true` | ### 요청 예제 ```javascript { model_name: 'seedance-v2.0-reference-to-video', prompt: 'Use image one for the subject, video one for the movement, and audio one for the atmosphere', duration: 8, resolution: '1080p', aspect_ratio: '16:9', sound: true, images: ['https://example.com/subject-reference.jpg'], videos: ['https://example.com/motion-reference.mp4'], audios: ['https://example.com/atmosphere-reference.mp3'] } ``` ### @ (AT) 참조 자료 기반 동영상 요청 예제 ```javascript { model_name: 'seedance-v2.0-reference-to-video', prompt: 'Place the explorer from <<>> in the environment from <<>>, following the camera movement in <<>> and speaking with the reference voice from <<>>', duration: 8, resolution: '1080p', aspect_ratio: '16:9', sound: true, images: [ 'https://example.com/explorer-reference.jpg', 'https://example.com/environment-reference.jpg' ], videos: ['https://example.com/camera-movement-reference.mp4'], audios: ['https://example.com/voice-reference.mp3'] } ``` ## Fast 버전 Fast 버전은 처리 속도를 우선합니다. 모든 Fast 모델은 `"480p"`와 `"720p"` 출력만 지원합니다. Fast 텍스트 기반 및 이미지 기반 동영상 모델의 나머지 요청 구조는 대응하는 표준 모델과 같으며, Fast 참조 자료 기반 모델도 표준 참조 모델과 동일한 참조 자료 제한을 적용합니다. ### Fast 요청 예제 ```javascript { model_name: 'seedance-v2.0-fast-reference-to-video', prompt: 'Use image one for the subject, follow the movement from video one, and use audio one for the atmosphere', duration: 8, resolution: '720p', aspect_ratio: '9:16', sound: true, images: ['https://example.com/subject-reference.jpg'], videos: ['https://example.com/motion-reference.mp4'], audios: ['https://example.com/atmosphere-reference.mp3'] } ``` ### @ (AT) Fast 참조 자료 기반 동영상 요청 예제 ```javascript { model_name: 'seedance-v2.0-fast-reference-to-video', prompt: 'Have the dancer from <<>> perform the movement from <<>> on the stage in <<>>, using the rhythm from <<>>', duration: 8, resolution: '720p', aspect_ratio: '9:16', sound: true, images: [ 'https://example.com/dancer-reference.jpg', 'https://example.com/stage-reference.jpg' ], videos: ['https://example.com/dance-movement-reference.mp4'], audios: ['https://example.com/rhythm-reference.mp3'] } ``` ### Seedance 2.0 Fast 참조 자료 기반 동영상 매개변수 #### 필수 | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `model_name` | string | `"seedance-v2.0-fast-reference-to-video"`여야 함 | | `prompt` | string | 동영상 생성 프롬프트. 자리표시자 없이 일반 프롬프트를 작성하거나, 선택적으로 @ (AT) 참조 기능과 `<<>>`, `<<>>`, `<<>>`를 사용해 해당 미디어 배열의 항목을 명시적으로 참조할 수 있음 | | `duration` | integer | 동영상 길이: 정수 초 단위(4-15), 간격 1초 | | `resolution` | string | 출력 해상도: `"480p"` 또는 `"720p"` | | `aspect_ratio` | string | 동영상 화면 비율: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` 또는 `"3:4"` | #### 참조 자료 | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `images` | string[] | 참조 이미지 URL 1-9개. `videos`가 비어 있지 않으면 빈 배열 사용 가능 | | `videos` | string[] | 참조 동영상 URL 최대 3개. 각 동영상은 2-15초이며 총길이는 최대 15초 | | `audios` | string[] | 참조 오디오 URL 최대 3개. 각 오디오는 2-15초이며 총길이는 최대 15초. WAV 또는 MP3, 파일당 최대 15 MB. 이미지 또는 동영상이 하나 이상 필요 | 위에서 설명한 1부터 시작하는 자리표시자 규칙은 Fast 참조 자료 기반 동영상 모델에도 적용됩니다. #### 선택 | 매개변수 | 유형 | 설명 | |-----------|------|-------------| | `sound` | boolean | 동기화된 소리를 생성할지 여부. 기본값은 `true` | ## 미디어 제한 이 제한은 이 페이지에 있는 모델의 첫 프레임 이미지, 마지막 프레임 이미지 및 참조 자료에 적용됩니다. | 미디어 | 형식 | 제한 | |-------|---------|--------| | 이미지 | JPEG, PNG, WEBP, BMP, TIFF, GIF, HEIC, HEIF | 이미지당 30 MB 미만. 너비와 높이는 각각 300-6000 px, 너비 대 높이 비율은 0.4-2.5 | | 동영상 | MP4, MOV | 파일당 최대 200 MB. 너비와 높이는 각각 300-6000 px, 너비 대 높이 비율은 0.4-2.5, 프레임 속도는 24-60 FPS | | 오디오 | WAV, MP3 | 파일당 최대 15 MB | | 요청 본문 | — | 최대 64 MB | 참조 오디오와 참조 동영상에는 각각 별도로 총길이 15초 제한이 적용됩니다. 개수도 독립적이며 이미지 최대 9장, 동영상 3개, 오디오 3개입니다. 동영상을 추가해도 허용 이미지 수는 줄어들지 않습니다. 모든 모델의 기본값은 `720p`이지만 `resolution`은 반드시 제공해야 합니다. 소리 스위치의 기본값은 `true`이며, 이 스위치와 참조 오디오는 가격에 영향을 주지 않습니다. 참조 자료 기반 동영상에는 이미지 또는 동영상이 하나 이상 필요하며 오디오만 포함한 요청은 지원하지 않습니다. 참조 동영상을 업로드하면 개수나 길이와 관계없이 생성 요금이 두 배가 됩니다. ## 응답 형식 ### 초기 응답 모든 모델은 폴링에 사용할 `task_id`를 반환합니다. ```json { "code": 0, "message": "success", "data": { "task_id": "{task_id}", "response_url": "https://api.flaq.ai/api/v1/video/{task_id}", "task_status": "submitted" } } ``` ### 폴링 응답 `GET /api/v1/video/{taskId}`를 폴링하여 상태를 확인하세요. ```json { "code": 0, "message": "success", "data": { "task_id": "{task_id}", "response_url": "https://api.flaq.ai/api/v1/video/{task_id}", "task_status": "succeed", "task_status_msg": null, "task_result": { "credit": 0.2, "videos": [ { "url": "https://example.com/generated-video.mp4" } ] } } } ``` ### 상태 값 - `submitted`: 작업이 접수되어 처리 대기 중 - `processing`: 동영상 생성 중 - `succeed`: 동영상 생성 완료 - `failed`: 동영상 생성 실패 ## 처리 시간 **표준 모델**: 길이와 해상도에 따라 3-8분. **Fast 모델**: 대부분의 설정에서 1-4분. 5-10초마다 폴링하여 상태를 확인하세요. ## 권장 사용법 1. **적절한 모델 선택**: 반복 작업에는 Fast 모델을, 최종 출력에는 표준 모델을 사용하세요 2. **동작을 명확히 설명**: 프롬프트에 구체적인 동작 설명을 포함하세요 3. **해상도 선택**: 모든 표준 Seedance 2.0 모델은 `480p`, `720p`, `1080p`, `4k`를 지원하며, 모든 Fast 모델은 `480p`와 `720p`만 지원합니다 4. **참조 자료 순서**: `images`, `videos`, `audios`를 의도한 순서로 배치하고 프롬프트에서 일관되게 참조하세요 5. **동영상만 포함한 요청**: 참조 동영상을 하나 이상 제공하는 경우에만 빈 `images` 배열을 사용하세요 6. **미디어 길이**: 각 참조 오디오와 동영상의 길이를 2-15초로 유지하세요 7. **오디오 활용**: `sound`를 생략하면 기본값 `true`가 적용되며, 소리 생성을 끄려면 `false`로 설정하세요