> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 비디오 생성 API

>  AiHubMix는 OpenAI Sora 인터페이스 형식과 호환되는 통합 비디오 생성 API를 제공하며, 백엔드는 여러 제조사의 모델을 지원합니다

## 빠른 시작

비디오 생성은 비동기 작업이며, 전체 프로세스는 세 단계로 나뉩니다.

```text theme={null}
1. 작업 제출 → video_id 획득
2. 상태 폴링 → status가 completed가 될 때까지 대기
3. 비디오 다운로드 → MP4 파일 획득
```

**최소 예제**

```shellscript theme={null}
# 1단계: 비디오 생성 작업 제출
curl -X POST https://aihubmix.com/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A cat playing jazz on a piano, warm lighting, cinematic shot",
    "seconds": "5",
    "size": "1280x720"
  }'

# 응답 예시:
# {
#   "id": "eyJtb2RlbCI6IndhbjI...",
#   "object": "video",
#   "status": "in_progress",
#   "model": "wan2.6-t2v",
#   "duration": 5,
#   "width": 1280,
#   "height": 720,
#   ...
# }

# 2단계: 상태 폴링 조회 (15초마다 한 번씩 조회, status가 completed가 될 때까지)
curl https://aihubmix.com/v1/videos/{video_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 3단계: 비디오 다운로드
curl https://aihubmix.com/v1/videos/{video_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output video.mp4
```

## API 개요

| API      | 메서드    | 경로                              | 설명               |
| :------- | :----- | :------------------------------ | :--------------- |
| 비디오 생성   | POST   | `/v1/videos`                    | 비디오 생성 작업 제출     |
| 상태 조회    | GET    | `/v1/videos/{video_id}`         | 작업 상태 및 진행률 조회   |
| 비디오 다운로드 | GET    | `/v1/videos/{video_id}/content` | 생성된 MP4 비디오 다운로드 |
| 작업 삭제    | DELETE | `/v1/videos/{video_id}`         | 비디오 작업 삭제        |

Base URL: `https://aihubmix.com`

인증 방식: Bearer Token

```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
```

## 지원 모델

### 텍스트-비디오 (Text-to-Video)

| 제조사       | 모델명                                                     | 특징                                           |
| --------- | ------------------------------------------------------- | -------------------------------------------- |
| OpenAI    | `sora-2`                                                | 표준 비디오 생성, 음성-영상 동기화 지원                      |
| OpenAI    | `sora-2-pro`                                            | 고품질 버전, 더욱 정교하고 안정적인 화면                      |
| Google    | `veo-3.1-generate-preview`                              | 최신 Veo 3.1, 네이티브 오디오, 4K 지원                  |
| Google    | `veo-3.1-fast-generate-preview`                         | Veo 3.1 고속 버전, 더 빠른 생성 속도                    |
| Google    | `veo-3.0-generate-preview`                              | Veo 3.0, 고충실도 비디오                            |
| Google    | `veo-2.0-generate-001`                                  | Veo 2.0, 안정 버전                               |
| Alibaba   | `wan2.6-t2v`                                            | Tongyi Wanxiang 최신 버전, 음성-영상 동기화             |
| Alibaba   | `wan2.5-t2v-preview`                                    | Tongyi Wanxiang 2.5, 중국어 최적화                 |
| Alibaba   | `wan2.2-t2v-plus`                                       | Tongyi Wanxiang 2.2                          |
| ByteDance | `jimeng-3.0-pro`                                        | Jimeng 3.0 Pro, 1080P 고화질                    |
| ByteDance | `jimeng-3.0-1080p`                                      | Jimeng 3.0 1080P                             |
| ByteDance | `doubao-seedance-2-0-260128`                            | 프로페셔널급 멀티모달 창작 비디오 모델 Seedance 2.0           |
| ByteDance | `doubao-seedance-2-0-fast-260128`                       | Seedance 2.0 고속 버전                           |
| Kuaishou  | `kling-v3`、`kling-v2-6`、`kling-v2-5-turbo`、`kling-v2-1` | Kling 텍스트/이미지-비디오, 신규 버전은 3\~15초 지원          |
| Kuaishou  | `kling-v3-omni`、`kling-video-o1`                        | Kling OmniVideo 멀티모달, 참조 비디오·네이티브 오디오·멀티샷 지원 |

### 이미지-비디오 (Image-to-Video)

| 제조사       | 모델명                               | 특징                                         |
| --------- | --------------------------------- | ------------------------------------------ |
| Alibaba   | `wan2.6-i2v`                      | Tongyi Wanxiang 최신 버전 이미지-비디오              |
| Alibaba   | `wan2.5-i2v-preview`              | Tongyi Wanxiang 2.5 이미지-비디오                |
| Alibaba   | `wan2.2-i2v-plus`                 | Tongyi Wanxiang 2.2 이미지-비디오                |
| ByteDance | `doubao-seedance-2-0-260128`      | 멀티모달 참조 입력, 이미지/비디오/오디오 지원                 |
| ByteDance | `doubao-seedance-2-0-fast-260128` | Seedance 2.0 고속 버전                         |
| Kuaishou  | `kling-v1-6` 등                    | Kling 이미지-비디오, 마지막 프레임·다중 이미지 참조(최대 4장) 지원 |

<Note>
  이미지-비디오는 `input_reference` 파라미터로 참조 이미지를 전달합니다(Alibaba Tongyi Wanxiang). Doubao Seedance는 `extra_body.content` 배열로 전달하며 이미지, 비디오, 오디오 등 다양한 참조 유형을 지원합니다. Kling은 `image` / `image_tail` / `image_list`로 이미지를 전달하며, 자세한 내용은 아래 [Kling](#kling) 섹션을 참조하세요.
</Note>

## API 상세 설명

### 요청 헤더

```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
Content-Type: application/json
```

### 비디오 생성 작업 생성

```shellscript theme={null}
POST /v1/videos
```

#### **요청 본문**

| 파라미터              | 타입            | 필수  | 설명                                                     |
| :---------------- | :------------ | :-- | :----------------------------------------------------- |
| `model`           | string        | 예   | 모델명, 예: `wan2.6-t2v`、`sora-2`                          |
| `prompt`          | string        | 예   | 비디오 설명 텍스트                                             |
| `seconds`         | string        | 아니오 | 비디오 길이(초), 통일적으로 문자열 타입 사용, 예: `"5"`、`"8"`(각 모델 상세 참조) |
| `size`            | string        | 아니오 | 해상도, 형식 `너비x높이`, 예: `1920x1080`(모델별 지원 값이 다름)          |
| `input_reference` | string/object | 아니오 | 참조 이미지(이미지-비디오), URL 또는 base64 지원                      |

> 모델별로 응답 형식이 약간 다르지만, 모두 `id`(video\_id)와 `status` 필드를 포함합니다. `status`로 작업 진행 상황을 판단하면 됩니다.

#### 응답 예시 (**Tongyi Wanxiang/Veo/Jimeng**)

```json theme={null}
{
  "id": "eyJtb2RlbCI6IndhbjI...",
  "object": "video",
  "created": 1772460274,
  "model": "wan2.6-t2v",
  "status": "in_progress",
  "prompt": "A cat watching the rain on a windowsill",
  "duration": 5,
  "width": 1920,
  "height": 1080,
  "url": null,
  "error": null
}
```

**응답 예시 (Sora)**

```json theme={null}
{
  "id": "eyJtb2RlbCI6InNvcmEtMi...",
  "object": "video",
  "created_at": 1772451930,
  "status": "queued",
  "model": "sora-2",
  "progress": 0,
  "prompt": "A cinematic drone shot over mountains",
  "seconds": "8",
  "size": "1280x720"
}
```

#### 공통 상태 값 설명

| 상태            | 설명             |
| :------------ | :------------- |
| `queued`      | 대기 중(Sora 전용)  |
| `in_progress` | 생성 중           |
| `completed`   | 생성 완료, 다운로드 가능 |
| `failed`      | 생성 실패          |

### 비디오 상태 조회

```shellscript theme={null}
GET /v1/videos/{video_id}
```

이 API를 폴링하여 작업 완료 여부를 확인합니다. **15초**마다 한 번씩 조회하는 것을 권장합니다.

#### **응답 예시 (생성 완료 - Tongyi Wanxiang)**

```json theme={null}
{
  "id": "eyJtb2RlbCI6IndhbjI...",
  "object": "video",
  "status": "completed",
  "model": "wan2.5-t2v-preview",
  "duration": 5,
  "width": 1920,
  "height": 1080,
  "url": "https://aihubmix.com/v1/videos/eyJtb2RlbCI6IndhbjI.../content",
  "error": null
}
```

#### **응답 예시 (생성 완료 - Sora)**

```json theme={null}
{
  "id": "eyJtb2RlbCI6InNvcmEtMi...",
  "object": "video",
  "created_at": 1772451930,
  "status": "completed",
  "completed_at": 1772452114,
  "expires_at": 1772538330,
  "model": "sora-2",
  "progress": 100,
  "prompt": "A cinematic drone shot over mountains",
  "seconds": "8",
  "size": "1280x720"
}
```

> 모든 모델은 `status == "completed"`로 완료 상태를 판단한 후, `/content` API를 호출하여 다운로드합니다.

### 비디오 콘텐츠 다운로드

```shellscript theme={null}
GET /v1/videos/{video_id}/content
```

상태가 `completed`가 되면 이 API를 호출하여 MP4 비디오 파일을 다운로드합니다.

**응답**: 비디오 바이너리 스트림을 직접 반환합니다(`Content-Type: video/mp4`).

```shellscript theme={null}
curl https://aihubmix.com/v1/videos/{video_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output my_video.mp4
```

> **주의**: 비디오 다운로드 링크는 일반적으로 24시간의 유효 기간이 있으므로, 제때 다운로드하여 저장하세요.

### 비디오 작업 삭제

이 API는 이미 생성된 비디오 작업을 삭제하는 데 사용됩니다.

```shellscript theme={null}
DELETE /v1/videos/{video_id}
```

## 각 모델 파라미터 상세

### **OpenAI Sora**

| 파라미터         | 지원 값                                               |
| ------------ | -------------------------------------------------- |
| 모델           | `sora-2`、`sora-2-pro`                              |
| 길이 (seconds) | `"4"`(기본값)、`"8"`、`"12"`                            |
| 해상도 (size)   | `720x1280`(기본값)、`1280x720`、`1024x1792`、`1792x1024` |
| 이미지-비디오      | 지원, `input_reference`로 이미지 전달                      |

> 팁: 모든 모델의 `seconds` 파라미터는 통일적으로 문자열 타입으로 전달합니다(예: `"8"`).

**예제**

<CodeGroup>
  ```shellscript Sora theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sora-2",
      "prompt": "A cinematic drone shot soaring over a misty mountain range at sunrise, golden light filtering through the clouds",
      "seconds": "8",
      "size": "1280x720"
    }'
  ```

  ```shellscript Sora Pro 세로형 비디오 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sora-2-pro",
      "prompt": "A person walking through a neon-lit city street at night, rain reflecting on the pavement, cinematic lighting",
      "seconds": "12",
      "size": "720x1280"
    }'
  ```
</CodeGroup>

### Google Veo

| 파라미터              | 지원 값                                                                                                                                                                                                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 모델                | `veo-3.1-generate-preview`(권장)、`veo-3.1-fast-generate-preview`(고속)、`veo-3.0-generate-preview`、`veo-2.0-generate-001`                                                                                                                                                                              |
| 길이 (seconds)      | Veo 3/3.1: `"4"`、`"6"`、`"8"`; Veo 2: `"5"`\~`"8"`(기본값 `"8"`)                                                                                                                                                                                                                                      |
| 해상도 (size)        | `720p`(기본값)、`1080p`、`4k`(4K는 Veo 3+만), 또는 픽셀 형식 예: `1280x720`、`1920x1080`                                                                                                                                                                                                                         |
| 가로세로 비율           | 16:9(기본값)、9:16                                                                                                                                                                                                                                                                                    |
| 이미지-비디오 (Veo 3.1) | **첫 프레임**: `first_frame`(또는 호환 필드 `input_reference`); **마지막 프레임**: `last_frame`; **참조 이미지**: `reference_images`(배열, 최대 3장). 이미지는 공개 URL, base64 데이터 URL, 또는 `{"mime_type": "...", "data": "..."}` 객체를 허용합니다. **길이**: 첫 프레임 / 첫·마지막 프레임은 `"4"`/`"6"`/`"8"`을 지원; 참조 이미지를 사용하면 Google이 출력을 8초로 고정합니다 |

**예제**

<CodeGroup>
  ```shellscript Veo 3.1 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-generate-preview",
      "prompt": "A tranquil Japanese garden, cherry blossom petals slowly drifting down, koi swimming in the pond, with the melodious sound of wind chimes in the background",
      "seconds": "8",
      "size": "1280x720"
    }'
  ```

  ```shellscript Veo 3.1 Fast theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-fast-generate-preview",
      "prompt": "Ocean waves crashing on rocky cliffs at sunset, seagulls flying overhead",
      "seconds": "8",
      "size": "1280x720"
    }'
  ```

  ```shellscript 첫/마지막 프레임 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-generate-preview",
      "prompt": "The camera slowly pushes in from a valley at dawn, transitioning naturally into sunset",
      "seconds": "8",
      "size": "1280x720",
      "first_frame": "https://example.com/first.jpg",
      "last_frame": "https://example.com/last.jpg"
    }'
  ```

  ```shellscript 참조 이미지 (최대 3장) theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-generate-preview",
      "prompt": "The character from the reference images walks through a forest, cinematic shot",
      "seconds": "8",
      "size": "1280x720",
      "reference_images": [
        "https://example.com/ref1.jpg",
        "https://example.com/ref2.jpg"
      ]
    }'
  ```
</CodeGroup>

<Note>
  **이미지 필드 참고**:

  * 첫 프레임 우선순위: `first_frame` > `input_reference`(OpenAI 호환 단일 프레임).
  * `first_frame` / `last_frame` / `reference_images`의 각 요소는 다음을 허용합니다: 공개 URL, base64 데이터 URL(`data:image/png;base64,...`), 또는 `{"mime_type":"image/png","data":"<base64>"}` 객체.
  * OpenRouter 스타일의 `frame_images`(요소에 `frame_type: first_frame | last_frame`) 및 `input_references` 별칭도 허용됩니다.
  * 참조 이미지는 최대 3장까지 허용하며, 초과하면 400을 반환합니다.
</Note>

> 팁: Veo는 네이티브 오디오 생성을 지원하므로, prompt에 효과음을 묘사할 수 있습니다. 예: "배경에 새소리가 들린다", "피아노 선율".

### Tongyi Wanxiang

| 파라미터         | 지원 값                                                           |
| ------------ | -------------------------------------------------------------- |
| 텍스트-비디오 모델   | `wan2.6-t2v`(권장)、`wan2.5-t2v-preview`、`wan2.2-t2v-plus`        |
| 이미지-비디오 모델   | `wan2.6-i2v`(권장)、`wan2.5-i2v-preview`、`wan2.2-i2v-plus`        |
| 길이 (seconds) | 모델에 따라 다름(아래 설명 참조), 기본값 `"5"`                                 |
| 해상도 (size)   | 아래 표 참조, `x` 와 `*` 구분자 모두 사용 가능(예: `1920x1080` 또는 `1920*1080`) |
| 이미지-비디오      | `input_reference`로 이미지 URL 또는 base64 전달                        |

**각 모델 지원 길이**

| 모델                                          | seconds 선택 가능 값         | 기본값   |
| :------------------------------------------ | :---------------------- | :---- |
| `wan2.6-t2v` / `wan2.6-i2v`                 | `"2"`\~`"15"`(임의의 정수 값) | `"5"` |
| `wan2.5-t2v-preview` / `wan2.5-i2v-preview` | `"5"` 또는 `"10"`         | `"5"` |
| `wan2.2-t2v-plus` / `wan2.2-i2v-plus`       | `"5"`(고정)               | `"5"` |

**지원 해상도 (너비\*높이)**

| 화질    | 선택 가능 해상도                                                             |
| :---- | :-------------------------------------------------------------------- |
| 480P  | `832x480`、`480x832`、`624x624`                                         |
| 720P  | `1280x720`(기본값)、`720x1280`、`960x960`、`1088x832`(4:3)、`832x1088`(3:4)  |
| 1080P | `1920x1080`、`1080x1920`、`1440x1440`、`1632x1248`(4:3)、`1248x1632`(3:4) |

> **주의**: wan2.6은 720P와 1080P만 지원; wan2.5는 480P, 720P, 1080P 지원; wan2.2는 480P와 1080P만 지원.

**예제**

<CodeGroup>
  ```shellscript 텍스트-비디오 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "wan2.6-t2v",
      "prompt": "A winding stream flows through an autumn forest, golden fallen leaves drifting on the water surface, sunlight casting dappled light and shadow through the leaves",
      "seconds": "5",
      "size": "1920x1080"
    }'
  ```

  ```shellscript 이미지-비디오 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "wan2.6-i2v",
      "prompt": "The character in the frame slowly turns their head and smiles, the camera slowly pushes in",
      "seconds": "5",
      "size": "1280x720",
      "input_reference": "https://example.com/my-image.jpg"
    }'
  ```
</CodeGroup>

> 팁: wan2.5 이상 버전은 기본적으로 음성이 있는 비디오를 생성하며(자동 더빙), 중국어 prompt의 효과가 더 좋습니다.

### Jimeng

| 파라미터         | 지원 값                                        |
| ------------ | ------------------------------------------- |
| 모델           | `jimeng-3.0-pro`(권장)、`jimeng-3.0-1080p`     |
| 길이 (seconds) | `"5"` 또는 `"10"`(기본값 `"5"`)                  |
| 해상도 (size)   | 가로세로 비율 형식 또는 픽셀 형식 지원                      |
| 이미지-비디오      | 지원, `input_reference`로 이미지 URL 또는 base64 전달 |

**지원 가로세로 비율 및 대응 해상도**

| 가로세로 비율 (size)        | 실제 해상도    |
| :-------------------- | :-------- |
| `16:9` 또는 `1920x1080` | 1920×1088 |
| `9:16` 또는 `1080x1920` | 1088×1920 |
| `4:3` 또는 `1664x1248`  | 1664×1248 |
| `3:4` 또는 `1248x1664`  | 1248×1664 |
| `1:1` 또는 `1440x1440`  | 1440×1440 |
| `21:9` 또는 `2176x928`  | 2176×928  |

**예제**

<CodeGroup>
  ```shellscript Jimeng theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "jimeng-3.0-pro",
      "prompt": "A young woman in Hanfu dances gracefully amid a bamboo forest, her long dress flowing in the wind, with a faint morning mist in the background",
      "seconds": "5",
      "size": "16:9"
    }'
  ```

  ```Jimeng 세로형 버전 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "jimeng-3.0-1080p",
      "prompt": "A sunset over the ocean, waves gently rolling, warm golden light",
      "seconds": "5",
      "size": "9:16"
    }'
  ```
</CodeGroup>

### Doubao Seedance

| 파라미터                     | 지원 값                                                                        |
| ------------------------ | --------------------------------------------------------------------------- |
| 모델                       | `doubao-seedance-2-0-260128`、`doubao-seedance-2-0-fast-260128`              |
| 해상도 (resolution)         | `"480p"`、`"720p"`(기본값)                                                      |
| 길이 (duration)            | 정수, 범위 `4`\~`15`, 또는 `-1`(모델이 자동 결정)                                        |
| 가로세로 비율 (ratio)          | `"adaptive"`(기본값, 자동 적응)、`"16:9"`、`"9:16"`、`"1:1"`、`"4:3"`、`"3:4"`、`"21:9"` |
| 음성 비디오 (generate\_audio) | 기본값 `true`; `false`로 설정 시 무음 비디오 생성                                         |
| 워터마크 (watermark)         | 기본값 `false`                                                                 |
| 멀티모달 참조                  | 이미지, 비디오, 오디오 지원                                                            |

**`extra_body.content` 지원 참조 유형**

| 유형     | `type` 값    | `role` 값          | 설명               |
| ------ | ----------- | ----------------- | ---------------- |
| 참조 이미지 | `image_url` | `reference_image` | 화면/스타일 참조 이미지    |
| 참조 비디오 | `video_url` | `reference_video` | 카메라 워크/구도 참조 비디오 |
| 참조 오디오 | `audio_url` | `reference_audio` | 배경 음악 오디오 파일     |

**예제**

```shellscript Seedance 2.0 / 2.0 Fast theme={null}
curl -X POST "https://aihubmix.com/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "Use the first-person POV framing from Video 1 throughout, and use Audio 1 as the background music for the entire clip. Create a first-person fruit tea commercial featuring the Seedance brand limited-edition apple fruit tea, "Ping Ping An An." 

Opening frame: Image 1. From a first-person perspective, your hand picks a dew-covered Aksu red apple, accompanied by a crisp, satisfying bite-like tapping sound.

Seconds 2–4: Fast-paced cuts. Your hand drops freshly cut apple chunks into a shaker, adds ice and tea base, then shakes vigorously. The sound of ice clinking and shaking syncs with upbeat percussion. Background voiceover: "Freshly cut, freshly shaken."

Seconds 4–6: First-person close-up of the finished drink. The layered fruit tea is poured into a clear cup. Your hand gently squeezes a creamy topping across the surface. A pink label is placed on the cup. The camera pushes in to highlight the rich texture and layering.

Seconds 6–8: First-person hand holding the drink. You raise the fruit tea from Image 2 toward the camera, as if offering it directly to the viewer. The label is clearly visible. Background voiceover: "Take a refreshing sip."

Final frame: Freeze on Image 2. 

All background voiceovers should be in a female voice.",
    "extra_body": {
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
          },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
          },
          "role": "reference_image"
        },
        {
          "type": "video_url",
          "video_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
          },
          "role": "reference_video"
        },
        {
          "type": "audio_url",
          "audio_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
          },
          "role": "reference_audio"
        }
      ],
      "ratio": "16:9",
      "duration": 11,
      "watermark": false
    }
  }'
```

### Kling

Kling은 **텍스트-비디오, 이미지-비디오, 다중 이미지 참조 비디오, OmniVideo 멀티모달**의 네 가지 기능을 지원하며, 통일적으로 `/v1/videos` API로 호출합니다. 게이트웨이가 「모델명 + 입력 형태」에 따라 Kling의 해당 엔드포인트로 자동 라우팅하므로 호출자가 구분할 필요가 없습니다.

| 기능             | 모델                                                                                           |
| -------------- | -------------------------------------------------------------------------------------------- |
| 텍스트 / 이미지      | `kling-v1`、`kling-v1-5`、`kling-v1-6`、`kling-v2-1`、`kling-v2-5-turbo`、`kling-v2-6`、`kling-v3` |
| 다중 이미지 참조      | `kling-v1-6`                                                                                 |
| OmniVideo 멀티모달 | `kling-video-o1`、`kling-v3-omni`                                                             |

**파라미터**

| 파라미터                   | 타입     | 설명                                                                                                                    |
| ---------------------- | ------ | --------------------------------------------------------------------------------------------------------------------- |
| `model`                | string | **필수**, `kling-*`, 기능과 버전을 결정                                                                                         |
| `prompt`               | string | 텍스트 프롬프트                                                                                                              |
| `negative_prompt`      | string | 네거티브 프롬프트                                                                                                             |
| `mode`                 | string | 생성 모드: `std`(720P)/ `pro`(1080P)/ `4k`, 기본값 `std`                                                                     |
| `duration` / `seconds` | string | 길이(초), 구 모델 `5`/`10`, 신규 모델 `3`\~`15`, 기본값 `5`                                                                        |
| `aspect_ratio`         | string | 화면 비율: `16:9` / `9:16` / `1:1`(omni 순수 텍스트 생성, 비디오 참조 시 필수, 미지정 시 자동으로 `16:9` 보충)                                     |
| `cfg_scale`            | float  | 프롬프트 연관성 `[0, 1]`, 기본값 `0.5`(`kling-v2.x`는 미지원)                                                                       |
| `image`                | string | **이미지 생성**: 단일 이미지, 이미지 URL 또는 Base64(Base64는 `data:image/...;base64,` 접두사 없음)                                        |
| `image_tail`           | string | **이미지 생성**: 마지막 프레임 이미지(선택)                                                                                           |
| `image_list`           | array  | **다중 이미지 참조**: 이미지 URL 배열, 최대 4장                                                                                      |
| `sound`                | string | **omni**: `on`/`off`, 네이티브 오디오 생성 여부, 기본값 `off`                                                                       |
| `video_list`           | array  | **omni**: 참조 비디오 `[{ "video_url": "...", "refer_type": "feature" }]`, `refer_type`은 `feature`(비디오 참조)/ `base`(비디오 편집) |

<Note>
  지원하지 않거나 매핑되지 않은 핵심 파라미터는 명시적으로 오류를 반환하며, 조용히 누락되지 않습니다. 그 외 Kling 네이티브 파라미터는 `extra_body`에 넣어 업스트림으로 전달할 수 있습니다.
</Note>

**예제**

<CodeGroup>
  ```shellscript 텍스트-비디오 theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v1-6",
      "prompt": "An orange cat running on a sunlit grassy meadow",
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript 이미지-비디오 theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v1-6",
      "image": "https://example.com/first.png",
      "prompt": "The camera pulls back, the character smiles",
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript 다중 이미지 참조 theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v1-6",
      "image_list": ["https://example.com/a.png", "https://example.com/b.png"],
      "prompt": "Two characters meet on the street",
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript OmniVideo 참조 비디오 theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v3-omni",
      "prompt": "Generate the next shot based on the reference video",
      "video_list": [{ "video_url": "https://example.com/in.mp4", "refer_type": "feature" }],
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript OmniVideo 네이티브 오디오 theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v3-omni",
      "prompt": "A man smiles and says hello",
      "sound": "on",
      "aspect_ratio": "16:9",
      "duration": "5"
    }'
  ```
</CodeGroup>

**설명**

* **비동기 3단계**: 제출하여 `video_id` 획득 → `GET /v1/videos/{video_id}`를 폴링하여 `status`가 `completed`가 될 때까지 → `GET /v1/videos/{video_id}/content`로 MP4 다운로드. 상태 값: `in_progress` / `completed` / `failed`.
* 비디오 생성은 일반적으로 1\~3분 소요; 결과 비디오 URL은 **30일 후 정리**되므로 제때 전송 저장하세요.
* **작업 삭제**: Kling에는 삭제 API가 없으며, `DELETE /v1/videos/{video_id}`는 `501 not_supported`를 반환합니다.
* **요금**: 모델 × `mode` × 길이 × 기능(참조 비디오 유무 / 음성 유무)에 따라 과금; **생성 실패 시 과금되지 않으며**, 조회와 다운로드는 과금되지 않습니다.

## **전체 호출 예제**

<CodeGroup>
  ```python Tongyi Wanxiang theme={null}
  import requests
  import time

  API_KEY = "AIHUBMIX_API_KEY"
  BASE_URL = "https://aihubmix.com"
  HEADERS = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  # 1단계: 비디오 생성 작업 생성
  response = requests.post(
      f"{BASE_URL}/v1/videos",
      headers=HEADERS,
      json={
          "model": "wan2.6-t2v",
          "prompt": "A desert under a starry sky, a meteor streaking across the night sky, the glow of a distant campfire flickering in the breeze",
          "seconds": "5",
          "size": "1920x1080"
      }
  )
  result = response.json()
  video_id = result["id"]
  print(f"작업이 생성됨, video_id: {video_id}")

  # 2단계: 상태 폴링 조회
  while True:
      status_response = requests.get(
          f"{BASE_URL}/v1/videos/{video_id}",
          headers=HEADERS
      )
      status_data = status_response.json()
      current_status = status_data["status"]
      print(f"현재 상태: {current_status}")

      if current_status == "completed":
          print("비디오 생성 완료!")
          break
      elif current_status == "failed":
          error_msg = status_data.get("error", {})
          if isinstance(error_msg, dict):
              error_msg = error_msg.get("message", "알 수 없는 오류")
          print(f"생성 실패: {error_msg}")
          break

      time.sleep(15)  # 15초마다 한 번씩 조회

  # 3단계: 비디오 다운로드
  video_response = requests.get(
      f"{BASE_URL}/v1/videos/{video_id}/content",
      headers=HEADERS
  )
  with open("output.mp4", "wb") as f:
      f.write(video_response.content)
  print(f"비디오가 output.mp4로 저장됨({len(video_response.content) / 1024 / 1024:.1f} MB)")
  ```

  ```python Sora theme={null}
  import requests
  import time

  API_KEY = "AIHUBMIX_API_KEY"
  BASE_URL = "https://aihubmix.com"
  HEADERS = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  # 비디오 생성 작업 생성
  response = requests.post(
      f"{BASE_URL}/v1/videos",
      headers=HEADERS,
      json={
          "model": "sora-2",
          "prompt": "A cinematic shot of a futuristic city at sunset, flying cars in the background",
          "seconds": "8",       # 선택 가능 "4"/"8"/"12"
          "size": "1280x720"    # 지원 1280x720, 720x1280, 1024x1792, 1792x1024
      }
  )
  result = response.json()
  video_id = result["id"]
  print(f"작업이 생성됨, video_id: {video_id}")

  # Sora 상태 폴링(queued -> in_progress -> completed 발생 가능)
  while True:
      status_response = requests.get(
          f"{BASE_URL}/v1/videos/{video_id}",
          headers=HEADERS
      )
      status_data = status_response.json()
      current_status = status_data["status"]
      progress = status_data.get("progress", "")
      print(f"상태: {current_status}, 진행률: {progress}%")

      if current_status == "completed":
          print("비디오 생성 완료!")
          break
      elif current_status == "failed":
          print(f"생성 실패: {status_data.get('error')}")
          break

      time.sleep(15)

  # 비디오 다운로드
  video_response = requests.get(
      f"{BASE_URL}/v1/videos/{video_id}/content",
      headers=HEADERS
  )
  with open("sora_output.mp4", "wb") as f:
      f.write(video_response.content)
  print("비디오가 sora_output.mp4로 저장됨")
  ```

  ```javascript Node.js theme={null}
  const API_KEY = "your_aihubmix_api_key";
  const BASE_URL = "https://aihubmix.com";

  async function generateVideo() {
    // 1단계: 작업 생성(Veo 3.1을 예로)
    const createResponse = await fetch(`${BASE_URL}/v1/videos`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        model: "veo-3.1-generate-preview",
        prompt: "A desert under a starry sky, with a meteor streaking across the night.",
        seconds: "8",
        size: "1280x720"
      })
    });
    const { id: videoId } = await createResponse.json();
    console.log(`작업이 생성됨: ${videoId}`);

    // 2단계: 상태 폴링
    let status = "in_progress";
    while (status !== "completed" && status !== "failed") {
      await new Promise(resolve => setTimeout(resolve, 15000));
      const statusResponse = await fetch(`${BASE_URL}/v1/videos/${videoId}`, {
        headers: { "Authorization": `Bearer ${API_KEY}` }
      });
      const result = await statusResponse.json();
      status = result.status;
      console.log(`현재 상태: ${status}`);
    }

    if (status === "completed") {
      // 3단계: 비디오 다운로드
      const videoResponse = await fetch(`${BASE_URL}/v1/videos/${videoId}/content`, {
        headers: { "Authorization": `Bearer ${API_KEY}` }
      });
      const fs = require("fs");
      const buffer = Buffer.from(await videoResponse.arrayBuffer());
      fs.writeFileSync("output.mp4", buffer);
      console.log("비디오가 output.mp4로 저장됨");
    }
  }

  generateVideo();
  ```
</CodeGroup>

## **FAQ**

### **비디오 생성에는 얼마나 걸리나요?**

비디오 생성은 일반적으로 1-5분이 소요되며, 구체적인 시간은 모델, 해상도, 길이에 따라 다릅니다. 15초의 폴링 간격을 설정하는 것을 권장합니다.

### `input_reference` **파라미터는 어떻게 사용하나요?**

`input_reference`는 이미지-비디오 시나리오에 사용되며, 세 가지 전달 방식을 지원합니다.

```json theme={null}
// 방식 1: 이미지 URL 직접 전달
"input_reference": "https://example.com/image.jpg"

// 방식 2: base64로 인코딩된 이미지 전달(객체 형식)
"input_reference": {
  "mime_type": "image/jpeg",
  "data": "<BASE64_ENCODED_IMAGE>"
}

// 방식 3: data URL 전달
"input_reference": "data:image/jpeg;base64,<BASE64_ENCODED_IMAGE>"
```

### **비디오 다운로드 링크의 유효 기간은 얼마나 되나요?**

생성된 비디오 다운로드 링크는 일반적으로 **24시간**의 유효 기간이 있으므로, 제때 다운로드하여 저장하세요.

### **각 모델의** `seconds` **파라미터는 어떤 차이가 있나요?**

| 모델                                                    | 선택 가능 값                      | 기본값   |
| ----------------------------------------------------- | ---------------------------- | ----- |
| Sora (`sora-2` / `sora-2-pro`)                        | `"4"`, `"8"`, `"12"`         | `"4"` |
| Veo 3/3.1 (`veo-3.1-generate-preview` 등)              | `"4"`, `"6"`, `"8"`          | `"8"` |
| Veo 2 (`veo-2.0-generate-001`)                        | `"5"`\~`"8"`                 | `"8"` |
| Tongyi Wanxiang `wan2.6`                              | `"2"`\~`"15"`                | `"5"` |
| Tongyi Wanxiang `wan2.5`                              | `"5"`, `"10"`                | `"5"` |
| Tongyi Wanxiang `wan2.2`                              | `"5"`(고정)                    | `"5"` |
| Jimeng (`jimeng-3.0-pro` 등)                           | `"5"`, `"10"`                | `"5"` |
| Doubao Seedance (`doubao-seedance-2-0-*`)             | 정수 `duration4`\~`15` 또는 `-1` | `5`   |
| Kling 신규 버전 (`kling-v2-x` / `kling-v3` 등)             | `"3"`\~`"15"`                | `"5"` |
| Kling 구 버전 (`kling-v1` / `kling-v1-5` / `kling-v1-6`) | `"5"`, `"10"`                | `"5"` |

\> **팁**: 모든 모델의 `seconds` 파라미터는 통일적으로 문자열 타입으로 전달하며(예: `"8"`), API가 자동으로 처리합니다.

### 모델별 `size` 파라미터 형식은 어떤 차이가 있나요?

| 모델              | 지원하는 size 값                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------------- |
| Sora            | `1280x720`、`720x1280`、`1024x1792`、`1792x1024`                                                       |
| Veo             | 픽셀 형식(`1280x720` 등) 또는 해상도 라벨(`720p`、`1080p`、`4k`)                                                  |
| Tongyi Wanxiang | 픽셀 형식, `x` 와 `*` 모두 가능(예: `1920x1080` 또는 `1920*1080`)                                               |
| Jimeng          | 가로세로 비율 형식(`16:9`、`9:16` 등) 또는 픽셀 형식                                                                |
| Doubao Seedance | 가로세로 비율 형식(`"adaptive"`、`"16:9"`、`"9:16"` 등)                                                        |
| Kling           | `size`를 사용하지 않고 `mode`(`std`/`pro`/`4k`로 화질 제어) + `aspect_ratio`(`16:9`/`9:16`/`1:1`로 화면 비율 제어)를 사용 |

### `seconds` **와** `duration` **은 어떤 차이가 있나요?**

둘은 의미가 동일하며 모두 비디오 길이를 나타냅니다. API는 이 두 파라미터명을 모두 지원합니다(Sora 제외, Sora는 `seconds`만 허용). 통일적으로 `seconds` 사용을 권장합니다.

### 더 나은 prompt를 작성하는 방법은?

* **구체적인 장면 묘사**: 주체, 동작, 환경, 조명, 분위기를 포함
* **카메라 언어 지정**: 예: "클로즈업", "항공 촬영", "푸시 인 샷", "슬로우 모션"
* **스타일 묘사**: 예: "시네마틱", "다큐멘터리 스타일", "애니메이션 스타일"
* **중국어 모델은 중국어 prompt 효과가 더 좋음**: Tongyi Wanxiang은 중국어에 최적화됨
* **Veo는 오디오 묘사 지원**: prompt에 소리를 묘사 가능, 예: "새소리", "피아노 선율"

### 작업이 실패하면 어떻게 처리하나요?

`status`가 `failed`일 때, 응답의 `error` 필드에 오류 정보가 포함됩니다.

```json theme={null}
{
  "status": "failed",
  "error": {
    "message": "Video generation failed due to content policy violation",
    "type": "video_generation_error"
  }
}
```

## 일반적인 실패 원인으로는 콘텐츠 위반, prompt 과다 길이, 이미지 형식 미지원 등이 있습니다. 오류 정보에 따라 조정한 후 재시도하세요.

마지막 업데이트: 2026-06-01