> ## 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.

# 视频生成接口

>  AiHubMix 提供统一的视频生成 API，兼容 OpenAI Sora 接口格式，后端支持多家厂商模型

## 快速开始

视频生成是异步操作，整个流程分为三步：

```text theme={null}
1. 提交任务 → 获得 video_id
2. 轮询状态 → 等待 status 变为 completed
3. 下载视频 → 获取 MP4 文件
```

**最简示例**

```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 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,
#   ...
# }

# 第二步：轮询查询状态（每 15 秒查询一次，直到 status 为 completed）
curl https://aihubmix.com/v1/videos/{video_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 第三步：下载视频
curl https://aihubmix.com/v1/videos/{video_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output video.mp4
```

## 接口概览

| 接口   | 方法     | 路径                              | 说明           |
| :--- | :----- | :------------------------------ | :----------- |
| 创建视频 | 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，稳定版                      |
| 阿里     | `wan2.6-t2v`                                            | 通义万相最新版，音画同步                     |
| 阿里     | `wan2.5-t2v-preview`                                    | 通义万相 2.5，中文优化                    |
| 阿里     | `wan2.2-t2v-plus`                                       | 通义万相 2.2                         |
| 字节     | `jimeng-3.0-pro`                                        | 即梦 3.0 Pro，1080P 高清              |
| 字节     | `jimeng-3.0-1080p`                                      | 即梦 3.0 1080P                     |
| 字节     | `doubao-seedance-2-0-260128`                            | 专业级多模态创作视频模型 Seedance 2.0        |
| 字节     | `doubao-seedance-2-0-fast-260128`                       | Seedance 2.0 快速版                 |
| 快手     | `kling-v3`、`kling-v2-6`、`kling-v2-5-turbo`、`kling-v2-1` | 可灵 Kling 文生/图生，新版支持 3\~15 秒      |
| 快手     | `kling-v3-omni`、`kling-video-o1`                        | 可灵 OmniVideo 多模态，支持参考视频、原生音频、多镜头 |

### 图生视频（Image-to-Video）

| 厂商 | 模型名称                              | 特点                       |
| -- | --------------------------------- | ------------------------ |
| 阿里 | `wan2.6-i2v`                      | 通义万相最新版图生视频              |
| 阿里 | `wan2.5-i2v-preview`              | 通义万相 2.5 图生视频            |
| 阿里 | `wan2.2-i2v-plus`                 | 通义万相 2.2 图生视频            |
| 字节 | `doubao-seedance-2-0-260128`      | 多模态参考输入，支持图片/视频/音频       |
| 字节 | `doubao-seedance-2-0-fast-260128` | Seedance 2.0 快速版         |
| 快手 | `kling-v1-6` 等                    | 可灵图生视频，支持尾帧、多图参考（最多 4 张） |

<Note>
  图生视频需通过 `input_reference` 参数传入参考图片（阿里通义万相）；豆包 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` 判断任务进度即可。

#### 响应示例（**通义万相/Veo/即梦AI**）

```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}
```

轮询此接口检查任务是否完成。建议每 **15 秒** 查询一次。

#### **响应示例（生成完成 - 通义万相）**

```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` 接口下载。

### 下载视频内容

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

当状态为 `completed` 后，调用此接口下载 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 小时有效期，请及时下载保存。

### 删除视频任务

该接口用于删除已创建的视频任务。

```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 dataURL、`{"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 dataURL（`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 中描述音效，如"背景传来鸟鸣声"、"钢琴旋律"。

### 通义万相

| 参数           | 支持值                                                     |
| ------------ | ------------------------------------------------------- |
| 文生视频模型       | `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 效果更佳。

### 即梦 AI

| 参数           | 支持值                                       |
| ------------ | ----------------------------------------- |
| 模型           | `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 即梦 AI 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"
    }'
  ```

  ```即梦 AI 竖屏版 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>

### 豆包 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` 接口调用，网关按「模型名 + 输入形态」自动路由到可灵对应端点，无需调用方区分。

| 能力            | 模型                                                                                           |
| ------------- | -------------------------------------------------------------------------------------------- |
| 文生 / 图生       | `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>
  不支持或未映射的关键参数会显式报错，不会静默丢弃。其余可灵原生参数可放进 `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 smiling and waving hello",
      "sound": "on",
      "aspect_ratio": "16:9",
      "duration": "5"
    }'
  ```
</CodeGroup>

**说明**

* **异步三步**：提交获 `video_id` → 轮询 `GET /v1/videos/{video_id}` 至 `status` 为 `completed` → `GET /v1/videos/{video_id}/content` 下载 MP4。状态值：`in_progress` / `completed` / `failed`。
* 出片通常 1\~3 分钟；结果视频 URL **30 天后清理**，请及时转存。
* **删除任务**：可灵无删除接口，`DELETE /v1/videos/{video_id}` 返回 `501 not_supported`。
* **计费**：按 模型 × `mode` × 时长 × 能力（有无参考视频 / 有声）扣费；**生成失败不扣费**，查询与下载不计费。

## **完整调用示例**

<CodeGroup>
  ```python 通义万相 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": "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}")

  # 第二步：轮询查询状态
  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 秒查询一次

  # 第三步：下载视频
  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() {
    // 第一步：创建任务（以 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}`);

    // 第二步：轮询状态
    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") {
      // 第三步：下载视频
      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}
// 方式一：直接传入图片 URL
"input_reference": "https://example.com/image.jpg"

// 方式二：传入 base64 编码的图片（对象格式）
"input_reference": {
  "mime_type": "image/jpeg",
  "data": "<BASE64_ENCODED_IMAGE>"
}

// 方式三：传入 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"` |
| 通义万相 `wan2.6`                                          | `"2"`\~`"15"`               | `"5"` |
| 通义万相 `wan2.5`                                          | `"5"`, `"10"`               | `"5"` |
| 通义万相 `wan2.2`                                          | `"5"`（固定）                   | `"5"` |
| 即梦AI (`jimeng-3.0-pro` 等)                              | `"5"`, `"10"`               | `"5"` |
| 豆包 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        | `1280x720720x12801024x17921792x1024`                                                   |
| Veo         | 像素格式`1280x720` 等）或分辨率标签`720p1080p4k`）                                                  |
| 通义万相        | 像素格式`x` 和 `*` 均可（如 `1920x1080` 或 `1920*1080`）                                          |
| 即梦 AI       | 宽高比格式`16:99:16` 等）或像素格式                                                                |
| 豆包 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 效果更好**：通义万相针对中文优化
* **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