# Seedance 2.5 API

ByteDance의 Seedance 2.5 동영상 생성 모델에 대한 전체 API 참조입니다.

## 모델 종류

이 API는 세 가지 모델을 지원합니다.

| 모델 | ID | 설명 |
|-------|----|-------------|
| **Seedance 2.5 Text to Video** | `seedance-v2.5-text-to-video` | 고품질 텍스트 기반 동영상 생성 |
| **Seedance 2.5 Image to Video** | `seedance-v2.5-image-to-video` | 첫 프레임 또는 첫 프레임과 마지막 프레임 기반 동영상 생성 |
| **Seedance 2.5 Reference to Video** | `seedance-v2.5-reference-to-video` | 참조 이미지, 동영상 및 오디오를 활용한 동영상 생성 |

## 빠른 비교

| 기능 | 텍스트 기반 동영상 | 이미지 기반 동영상 | 참조 기반 동영상 |
|---------|---------------|----------------|--------------------|
| 길이 범위 | 4-30초 | 4-30초 | 4-30초 |
| 해상도 옵션 | 480p, 720p, 1080p | 480p, 720p, 1080p | 480p, 720p, 1080p |
| 화면 비율 | 필수 | 지원 안 함 | 필수 |
| 필수 미디어 | 없음 | 첫 프레임 이미지 | 없음 |
| 선택 미디어 | 없음 | 마지막 프레임 이미지 | 이미지, 동영상 및 오디오 |

### 지원 화면 비율

텍스트 기반 및 참조 기반 동영상은 다음 비율을 지원합니다.

`21:9`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`

이미지 기반 동영상은 `aspect_ratio` 매개변수를 지원하지 않습니다.

### 해상도 옵션

| 해상도 | 설명 |
|------------|-------------|
| `480p` | 표준 화질 |
| `720p` | 고화질 |
| `1080p` | 풀 HD |

## Seedance 2.5 Text to Video

### 엔드포인트

```
POST /api/v1/video/task
```

### 요청 매개변수

#### 필수

| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `model_name` | string | `"seedance-v2.5-text-to-video"`로 지정해야 함 |
| `prompt` | string | 동영상 생성 프롬프트 |
| `resolution` | string | 출력 해상도: `"480p"`, `"720p"` 또는 `"1080p"` |
| `duration` | integer | 동영상 길이(4-30초). 1초 단위의 정수로 지정 |
| `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.5-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 Image to Video

### 요청 매개변수

#### 필수

| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `model_name` | string | `"seedance-v2.5-image-to-video"`로 지정해야 함 |
| `prompt` | string | 동영상 생성 프롬프트 |
| `resolution` | string | 출력 해상도: `"480p"`, `"720p"` 또는 `"1080p"` |
| `duration` | integer | 동영상 길이(4-30초). 1초 단위의 정수로 지정 |
| `image_url` | string | 첫 프레임 이미지 URL |

#### 선택

| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `image_end_url` | string | 선택 사항인 마지막 프레임 이미지 URL |
| `sound` | boolean | 사운드 생성 여부. 기본값은 `true` |

> 이미지 기반 동영상 요청에 `aspect_ratio`를 포함하지 마세요. 이 모델은 해당 매개변수를 지원하지 않습니다.

### 요청 예시

```javascript
{
  model_name: 'seedance-v2.5-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 Reference to Video

### 요청 매개변수

#### 필수

| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `model_name` | string | `"seedance-v2.5-reference-to-video"`로 지정해야 함 |
| `prompt` | string | 동영상 생성 프롬프트. 자리표시자 없이 일반 프롬프트를 작성하거나, 선택적으로 @ (AT) 참조 기능의 `<<<image_N>>>`, `<<<video_N>>>` 및 `<<<audio_N>>>`를 사용해 해당 미디어 배열의 항목을 명시적으로 참조할 수 있음 |
| `resolution` | string | 출력 해상도: `"480p"`, `"720p"` 또는 `"1080p"` |
| `duration` | integer | 동영상 길이(4-30초). 1초 단위의 정수로 지정 |
| `aspect_ratio` | string | 동영상 화면 비율: `"21:9"`, `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"` 또는 `"3:4"` |

#### 참조 미디어

모든 참조 미디어는 선택 사항입니다. 이미지만, 동영상만, 오디오만 포함하거나 참조 미디어가 없는 요청도 지원합니다. 참조 없이 생성할 때는 텍스트 기반 동영상을 권장합니다.

| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `images` | string[] | 참조 이미지 URL 0-30개. 아래 미디어 제한 참조 |
| `videos` | string[] | MP4 또는 MOV 형식의 참조 동영상 URL 0-10개. 각 동영상은 2-30초이며 총 길이는 최대 30초 |
| `audios` | string[] | WAV 또는 MP3 형식의 참조 오디오 URL 0-10개. 각 오디오는 2-30초이고 15 MB 이하여야 하며 총 길이는 30초 이하 |

#### @ (AT) 참조 자리표시자

@ (AT) 참조 기능은 번호가 매겨진 `<<<...>>>` 자리표시자로 참조 미디어와 프롬프트를 연결합니다. 번호는 미디어 유형별로 각각 `1`부터 시작하며 해당 배열의 순서를 따릅니다.

| 자리표시자 | 참조 값 |
|-------------|------------------|
| `<<<image_1>>>` | `images[0]` |
| `<<<image_2>>>` | `images[1]` |
| `<<<video_1>>>` | `videos[0]` |
| `<<<audio_1>>>` | `audios[0]` |

예를 들어 첫 번째 이미지가 캐릭터 참조이고 두 번째가 장면 참조인 경우, `prompt`에서 캐릭터에는 `<<<image_1>>>`, 장면에는 `<<<image_2>>>`를 사용합니다. 각 자리표시자는 해당 배열에 실제로 존재하는 항목을 가리켜야 합니다.

#### 선택

| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `sound` | boolean | 사운드 생성 여부. 기본값은 `true` |

### 요청 예시

```javascript
{
  model_name: 'seedance-v2.5-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-reference-to-video',
  prompt: 'Place the explorer from <<<image_1>>> in the environment from <<<image_2>>>, following the camera movement in <<<video_1>>> and speaking with the reference voice from <<<audio_1>>>',
  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 |
| 오디오 | WAV, MP3 | 각 오디오 최대 15 MB |
| 요청 본문 | — | 최대 64 MB |

참조 오디오와 참조 동영상의 총 길이 제한은 각각 독립적으로 30초입니다. 개수도 독립적이며 이미지 최대 30개, 동영상 10개, 오디오 10개를 허용합니다. 동영상을 추가해도 이미지 허용 개수는 줄어들지 않습니다.

모든 모델의 기본 해상도는 `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`: 동영상 생성 실패

## 처리 시간

처리 시간은 길이, 해상도 및 현재 대기열 상황에 따라 달라집니다.

5-10초마다 폴링하여 상태를 확인하세요.

## 권장 사항

1. **필수 매개변수**: 항상 `resolution`과 `duration`을 지정하고, 텍스트 기반 및 참조 기반 동영상에는 `aspect_ratio`도 지정하세요
2. **이미지 기반 동영상 비율**: 이미지 기반 동영상 요청에는 `aspect_ratio`를 보내지 마세요
3. **참조 동영상**: 동영상은 선택 사항입니다. 각 동영상과 전체 동영상 길이가 문서의 제한을 준수해야 합니다
4. **참조 이미지**: 이미지는 동영상 및 오디오와 독립적인 선택 사항입니다. 지원되는 이미지 URL을 최대 30개 제출하세요
5. **참조 오디오**: 각 오디오는 2-30초 및 15 MB 이하, 전체 길이는 30초 이하로 유지하세요
6. **참조 순서**: `images`, `videos` 및 `audios`를 의도한 순서로 정렬하고 프롬프트에서 일관되게 참조하세요
7. **사운드**: `sound`를 생략하면 기본값 `true`를 사용하며, `false`로 설정하면 사운드 생성이 비활성화됩니다