# Seedance 2.5 Flash API ByteDance의 Seedance 2.5 Flash 동영상 생성 모델을 위한 전체 API 레퍼런스입니다. ## 모델 종류 이 API는 세 가지 모델을 지원합니다. | 모델 | ID | 설명 | |-------|----|-------------| | **Seedance 2.5 Flash Text to Video** | `seedance-v2.5-flash-text-to-video` | 텍스트로 고품질 동영상 생성 | | **Seedance 2.5 Flash Image to Video** | `seedance-v2.5-flash-image-to-video` | 첫 프레임 또는 첫 프레임과 마지막 프레임으로 동영상 생성 | | **Seedance 2.5 Flash Reference to Video** | `seedance-v2.5-flash-reference-to-video` | 이미지, 동영상, 오디오를 참조하여 동영상 생성 | ## 기능 비교 | 기능 | 텍스트로 동영상 생성 | 이미지로 동영상 생성 | 참조 자료로 동영상 생성 | |---------|---------------|----------------|--------------------| | 길이 범위 | 4–30초 | 4–30초 | 4–30초 | | 해상도 옵션 | 480p, 720p | 480p, 720p | 480p, 720p | | 화면 비율 | 선택 사항(기본값 16:9) | 지원하지 않음 | 선택 사항(기본값 16:9) | | 필수 미디어 | 없음 | 첫 프레임 이미지 | 없음 | | 선택 미디어 | 없음 | 마지막 프레임 이미지 | 이미지, 동영상, 오디오 | ### 지원하는 화면 비율 텍스트 기반 생성과 참조 자료 기반 생성은 다음 비율을 지원합니다. `21:9`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4` 이미지 기반 생성은 `aspect_ratio` 매개변수를 지원하지 않습니다. ### 해상도 옵션 | 해상도 | 설명 | |------------|-------------| | `480p` | 표준 화질 | | `720p` | 고화질 | ## Seedance 2.5 Flash Text to Video ### 엔드포인트 ``` POST /api/v1/video/task ``` ### 요청 매개변수 #### 필수 | 매개변수 | 자료형 | 설명 | |-----------|------|-------------| | `model_name` | string | `"seedance-v2.5-flash-text-to-video"`로 지정 | | `prompt` | string | 동영상 생성 프롬프트(최대 5000자) | | `resolution` | string | 출력 해상도는 `"480p"` 또는 `"720p"`. 기본값 없음 | | `duration` | integer | 동영상 길이를 4–30초 사이의 정수로 1초 단위로 지정. 기본값 없음 | #### 선택 사항 | 매개변수 | 자료형 | 설명 | |-----------|------|-------------| | `aspect_ratio` | string | 동영상 화면 비율은 `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"` 중 하나. 기본값은 `"16:9"` | | `sound` | boolean | 소리 생성 여부. 기본값은 `true`이며 `false`로 설정하면 무음 동영상 생성 | ### 요청 예시 ```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.5-flash-text-to-video', prompt: 'A golden retriever running through a sunlit meadow', resolution: '720p', duration: 8, aspect_ratio: '16:9', sound: true }) }); const { data } = await response.json(); const taskId = data.task_id; ``` ## Seedance 2.5 Flash Image to Video ### 요청 매개변수 #### 필수 | 매개변수 | 자료형 | 설명 | |-----------|------|-------------| | `model_name` | string | `"seedance-v2.5-flash-image-to-video"`로 지정 | | `prompt` | string | 동영상 생성 프롬프트(최대 5000자) | | `resolution` | string | 출력 해상도는 `"480p"` 또는 `"720p"`. 기본값 없음 | | `duration` | integer | 동영상 길이를 4–30초 사이의 정수로 1초 단위로 지정. 기본값 없음 | | `image_url` | string | 첫 프레임 이미지 URL. 아래 미디어 제한을 참조하세요. 출력 화면 비율은 이 이미지의 비율을 따릅니다 | #### 선택 사항 | 매개변수 | 자료형 | 설명 | |-----------|------|-------------| | `image_end_url` | string | 마지막 프레임 이미지 URL(선택 사항). 아래 미디어 제한을 참조하세요. 첫 프레임과 같은 화면 비율을 권장합니다 | | `sound` | boolean | 소리 생성 여부. 기본값은 `true`이며 `false`로 설정하면 무음 동영상 생성 | > 이미지 기반 동영상 생성 요청에는 `aspect_ratio`를 포함하지 마세요. 이 모델은 해당 매개변수를 지원하지 않습니다. ### 요청 예시 ```javascript { model_name: 'seedance-v2.5-flash-image-to-video', image_url: 'https://example.com/first-frame.jpg', image_end_url: 'https://example.com/last-frame.jpg', prompt: 'Camera slowly pulls back to reveal the full landscape', resolution: '720p', duration: 8, sound: true } ``` ## Seedance 2.5 Flash Reference to Video ### 요청 매개변수 #### 필수 | 매개변수 | 자료형 | 설명 | |-----------|------|-------------| | `model_name` | string | `"seedance-v2.5-flash-reference-to-video"`로 지정 | | `prompt` | string | 동영상 생성 프롬프트(최대 5000자). 자리표시자 없이 일반 프롬프트를 작성하거나 @ (AT) 참조 기능의 `<<>>`, `<<>>`, `<<>>`를 사용해 해당 미디어 배열의 항목을 명시적으로 참조할 수 있습니다 | | `resolution` | string | 출력 해상도는 `"480p"` 또는 `"720p"`. 기본값 없음 | | `duration` | integer | 동영상 길이를 4–30초 사이의 정수로 1초 단위로 지정. 기본값 없음 | #### 참조 미디어 참조 미디어는 모두 선택 사항입니다. 이미지, 동영상, 오디오 중 한 종류만 사용하거나 참조 미디어 없이 요청할 수 있습니다. 참조 자료가 없다면 텍스트 기반 동영상 생성을 권장합니다. | 매개변수 | 자료형 | 설명 | |-----------|------|-------------| | `images` | string[] | 참조 이미지 URL 0–10개. 배열 순서대로 참조합니다. 아래 미디어 제한을 참고하세요 | | `videos` | string[] | MP4 또는 MOV 형식의 참조 동영상 URL 0–5개. 각 동영상은 2–30초이고 합계는 30초 이하여야 합니다. 아래 미디어 제한을 참고하세요. 요금 계산 시 참조 동영상의 총길이를 초 단위로 반올림한 뒤(0.5초는 올림) 출력 동영상 길이에 더합니다 | | `audios` | string[] | WAV 또는 MP3 형식의 참조 오디오 URL 0–5개. 각 오디오는 2–30초, 15 MB 이하이고 총길이는 30초 이하여야 합니다 | #### @ (AT) 참조 자리표시자 @ (AT) 참조 기능은 번호가 붙은 `<<<...>>>` 자리표시자로 참조 미디어를 프롬프트에 연결합니다. 번호는 미디어 유형별로 `1`부터 시작하며 해당 배열의 순서를 따릅니다. | 자리표시자 | 참조되는 값 | |-------------|------------------| | `<<>>` | `images[0]` | | `<<>>` | `images[1]` | | `<<>>` | `videos[0]` | | `<<>>` | `audios[0]` | 예를 들어 첫 번째 이미지는 인물, 두 번째 이미지는 장면을 참조한다면 `prompt`에서 인물은 `<<>>`, 장면은 `<<>>`로 지정하세요. 각 자리표시자는 해당 배열에 존재하는 항목을 가리켜야 합니다. #### 선택 사항 | 매개변수 | 자료형 | 설명 | |-----------|------|-------------| | `aspect_ratio` | string | 동영상 화면 비율은 `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"` 중 하나. 기본값은 `"16:9"` | | `sound` | boolean | 소리 생성 여부. 기본값은 `true`이며 `false`로 설정하면 무음 동영상 생성 | ### 요청 예시 ```javascript { model_name: 'seedance-v2.5-flash-reference-to-video', prompt: 'Use image one for the subject, video one for the movement, and audio one for the atmosphere', resolution: '720p', duration: 8, 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.5-flash-reference-to-video', prompt: 'Place the explorer from <<>> in the environment from <<>>, following the camera movement in <<>> and speaking with the reference voice from <<>>', resolution: '720p', duration: 10, aspect_ratio: '16:9', sound: true, images: [ 'https://example.com/explorer-reference.jpg', 'https://example.com/environment-reference.png' ], videos: ['https://example.com/camera-movement-reference.mp4'], audios: ['https://example.com/voice-reference.mp3'] } ``` ## 미디어 제한 다음 제한은 이 페이지에 나온 모델의 첫 프레임 이미지, 마지막 프레임 이미지 및 참조 미디어에 적용됩니다. | 미디어 | 형식 | 제한 | |-------|---------|--------| | 이미지 | 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, 총 픽셀 수는 407696–8295044 | | 오디오 | WAV, MP3 | 파일당 최대 15 MB | 참조 오디오와 참조 동영상의 총길이 제한은 각각 30초입니다. 개수도 별도로 계산하며 이미지 10개, 동영상 5개, 오디오 클립 5개까지 사용할 수 있습니다. 모든 모델에서 `resolution`과 `duration`은 필수이며 기본값이 없습니다. 텍스트 기반 생성과 참조 자료 기반 생성에서는 `aspect_ratio`를 생략하면 `16:9`가 적용됩니다. 소리 생성의 기본값은 `true`입니다. 무음 동영상을 생성하려면 `false`로 설정하세요. ## 응답 형식 ### 최초 응답 모든 모델은 폴링에 사용할 `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`: 동영상 생성 실패 ## 처리 시간 처리 시간은 동영상 길이와 해상도, 현재 대기열 상황에 따라 달라집니다. 5–10초 간격으로 폴링하여 상태를 확인하세요. ## 권장 사항 1. **필수 매개변수**: `prompt`, `resolution`, `duration`는 항상 지정하세요. 텍스트 기반 생성과 참조 자료 기반 생성에서 `aspect_ratio`는 선택 사항이며 기본값은 `16:9`입니다 2. **이미지 기반 생성의 화면 비율**: 이미지로 동영상을 생성하는 요청에는 `aspect_ratio`를 보내지 마세요 3. **참조 동영상**: 동영상은 선택 사항입니다. 각 동영상의 길이와 총길이는 위 제한을 준수해야 합니다 4. **참조 이미지**: 동영상이나 오디오의 유무와 관계없이 이미지는 선택 사항입니다. 지원 형식의 이미지 URL을 최대 10개까지 제출하세요 5. **참조 오디오**: 각 클립은 2–30초, 15 MB 이하로 유지하고 총길이는 30초를 넘기지 마세요 6. **참조 순서**: `images`, `videos`, `audios`의 항목을 의도한 순서로 배치하고 프롬프트에서도 그 순서에 맞게 참조하세요 7. **소리**: `sound`를 생략하면 기본값 `true`가 적용됩니다. 소리 생성을 끄려면 `false`로 설정하세요