# Seedance 2.0 Mini API

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

## 모델 종류

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

| 모델 | ID | 설명 |
|-------|-----|-------------|
| **Seedance 2.0 Mini Text to Video** | `seedance-v2.0-mini-text-to-video` | 비용 효율적인 텍스트 기반 동영상 생성 |
| **Seedance 2.0 Mini Image to Video** | `seedance-v2.0-mini-image-to-video` | 동작 제어를 지원하는 비용 효율적인 이미지 애니메이션 생성 |
| **Seedance 2.0 Mini Reference to Video** | `seedance-v2.0-mini-reference-to-video` | 참조 이미지, 동영상, 오디오를 활용한 비용 효율적인 동영상 생성 |

## 빠른 비교

| 기능 | 값 |
|---------|-------|
| 길이 범위 | 4~15초 |
| 해상도 옵션 | 480p, 720p |
| 화면 비율 옵션 | 21:9, 16:9, 9:16, 1:1, 4:3, 3:4 |
| 오디오 지원 | 지원(기본값: 활성화) |
| 참조 미디어 | 참조 기반 동영상 생성에 이미지, 동영상, 오디오 사용 |
| 시드 제어 | 모든 Seedance 2.0 Mini 모델에서 지원하지 않음 |

### 지원 화면 비율

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

### 해상도 옵션

| 해상도 | 설명 |
|------------|-------------|
| `480p` | 표준 화질, 빠른 처리 |
| `720p` | 고화질 |

## Seedance 2.0 Mini Text to Video

### 엔드포인트

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

### 요청 매개변수

#### 필수

| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `model_name` | string | `"seedance-v2.0-mini-text-to-video"`여야 함 |
| `prompt` | string | 동영상 생성 프롬프트 |
| `duration` | integer | 정수 초 단위의 동영상 길이(4~15), 간격은 1초 |
| `resolution` | string | 출력 해상도: `"480p"` 또는 `"720p"` |
| `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-mini-text-to-video',
    prompt: 'A golden retriever running through a sunlit meadow',
    duration: 6,
    resolution: '720p',
    aspect_ratio: '16:9',
    sound: true
  })
});

const { data } = await response.json();
const taskId = data.task_id;
```

## Seedance 2.0 Mini Image to Video

### 요청 매개변수

#### 필수

| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `model_name` | string | `"seedance-v2.0-mini-image-to-video"`여야 함 |
| `prompt` | string | 동영상 생성 프롬프트 |
| `duration` | integer | 정수 초 단위의 동영상 길이(4~15), 간격은 1초 |
| `resolution` | string | 출력 해상도: `"480p"` 또는 `"720p"` |
| `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
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-mini-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',
    sound: true
  })
});

const { data } = await response.json();
const taskId = data.task_id;
```

## Seedance 2.0 Mini Reference to Video

### 요청 매개변수

#### 필수

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

#### 참조 미디어

각 요청에는 이미지나 동영상이 하나 이상 포함되어야 합니다. 이미지를 참조할 때는 1~9장을 제출하세요. `videos` 배열에 참조 동영상이 하나 이상 있는 경우에만 `images` 배열을 생략하거나 비워 둘 수 있습니다. 오디오만 포함된 요청은 지원하지 않습니다.

| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `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`부터 시작하며 해당 배열의 순서를 따릅니다.

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

각 자리표시자는 해당 배열에 존재하는 항목을 가리켜야 합니다.

#### 선택

| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `sound` | boolean | 동기화된 소리 생성 여부. 기본값은 `true` |

### 참조 동영상 요금

Seedance V2.0 Mini Reference-to-Video는 다른 Seedance 2.0 참조 모델과 동일하게 해상도에 따른 초당 요금 구조를 사용합니다. `videos` 배열에 참조 동영상이 하나 이상 있으면 총 생성 요금에 2를 곱합니다. 이 배수는 업로드한 참조 동영상의 개수나 길이와 관계없이 한 번만 적용됩니다.

### 요청 예제

```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-mini-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>>>',
    duration: 8,
    resolution: '720p',
    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']
  })
});

const { data } = await response.json();
const taskId = data.task_id;
```

## 미디어 제한

이 제한은 이 페이지에 있는 모델의 첫 프레임 이미지, 마지막 프레임 이미지 및 참조 미디어에 적용됩니다.

| 미디어 | 형식 | 제한 |
|-------|---------|--------|
| 이미지 | 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`: 동영상 생성 실패

## 처리 시간

일반적인 처리 시간은 길이와 해상도에 따라 2~6분입니다.

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

## 권장 사항

1. **동작을 명확하게 설명**: 프롬프트에 구체적인 움직임 설명을 포함하세요
2. **해상도 선택**: 빠른 처리에는 `480p`, 높은 화질에는 `720p`를 사용하세요
3. **오디오 활용**: 몰입감 있는 동영상을 위해 `sound`를 활성화하세요
4. **이미지 기반 동영상 생성**: `image_url`로 선명한 첫 프레임을 제공하고, 시작 및 끝 프레임을 제어하려면 `image_end_url`을 사용하세요
5. **참조 미디어**: 지원되는 이미지, 동영상, 오디오를 사용하고 이미지나 동영상을 하나 이상 포함하세요
6. **참조 동영상 요금**: 참조 동영상이 하나 이상 포함된 참조 기반 동영상 생성 요청에는 업로드한 동영상의 개수나 길이와 관계없이 2배 요금이 적용됩니다
7. **시드 매개변수**: `seed`를 보내지 마세요. Seedance 2.0 Mini 모델은 지원하지 않습니다