# 创建视频生成任务

提交视频生成任务，立即返回任务 ID。视频生成为异步操作，需通过
`GET /v1/videos/generations/{taskId}` 轮询任务状态。

计费方式：提交时按预估时长冻结费用，视频生成成功后按实际用量结算；生成失败则退还冻结金额。

支持多种输入模式（通过 `content` 数组指定）：
- **文生视频**：仅传入 `type: text` 的提示词
- **图生视频（首帧/首尾帧）**：传入图片，`role` 设为 `first_frame` / `last_frame`
- **多模态参考生视频**（Seedance 2.0）：传入参考图片（1-9 张）、参考视频（1-3 个）、参考音频（1-3 段）的任意组合
- **有声视频**（Seedance 2.0、1.5 pro）：设置 `generate_audio: true`，模型自动生成同步音频
- **MiniMax-H3**（国内站 / 国际站）：同一接口，分辨率 / 时长 / 参考素材填法见 [MiniMax H3 请求参数](/docs/minimax-h3)
- **wan3.0-video / wan3.0-video-prime**（国内站 / 国际站）：万相 3.0 全能参考视频，见 [万相 3.0 请求参数](/docs/wan3-video)

**图片 / 媒体引用规范（重要）：**
- **普通图片**：`image_url.url` 请传 **公网可访问的 https URL**（如对象存储 / CDN）。上游引擎按 URL 直接拉取，不经过本服务内存。
- **含真人的参考图**：必须用 `asset://<asset_id>` 引用一个经过验证的真人素材（先调 `POST /v1/asset-groups/validate-session` 完成 H5 真人活体验证，拿到 `group_id`/`asset_id`）。直接传真人图 URL 或 base64 都会被上游 `InputImageSensitiveContentDetected.PrivacyInformation` 拒绝。
- **不要 inline base64**：`data:image/...;base64,...` 这种内联编码会让请求体迅速膨胀到 MB 级。**请求体硬上限 5 MB，超过返回 `413 payload_too_large`**。需要传图请上传到对象存储后传 URL，或用 `asset://` 引用素材库。

## POST /v1/videos/generations

> 创建视频生成任务

提交视频生成任务，立即返回任务 ID。视频生成为异步操作，需通过
`GET /v1/videos/generations/{taskId}` 轮询任务状态。

计费方式：提交时按预估时长冻结费用，视频生成成功后按实际用量结算；生成失败则退还冻结金额。

支持多种输入模式（通过 `content` 数组指定）：
- **文生视频**：仅传入 `type: text` 的提示词
- **图生视频（首帧/首尾帧）**：传入图片，`role` 设为 `first_frame` / `last_frame`
- **多模态参考生视频**（Seedance 2.0 / MiniMax-H3）：传入参考图片、参考视频、参考音频
- **有声视频**（Seedance 2.0、1.5 pro）：设置 `generate_audio: true`，模型自动生成同步音频。MiniMax-H3 不支持此字段。

MiniMax-H3（国内站 / 国际站）参数标准见文档「MiniMax H3 请求参数」：`resolution` 为 `768P` 或 `2K`，`duration` 为 4–15 的整数，文生必须给具体 `ratio`，首尾帧不能和参考素材混用。

**图片 / 媒体引用规范（重要）：**
- **普通图片**：`image_url.url` 请传 **公网可访问的 https URL**（如对象存储 / CDN）。上游引擎按 URL 直接拉取，不经过本服务内存。
- **含真人的参考图**：必须用 `asset://<asset_id>` 引用一个经过验证的真人素材（先调 `POST /v1/asset-groups/validate-session` 完成 H5 真人活体验证，拿到 `group_id`/`asset_id`）。直接传真人图 URL 或 base64 都会被上游 `InputImageSensitiveContentDetected.PrivacyInformation` 拒绝。
- **不要 inline base64**：`data:image/...;base64,...` 这种内联编码会让请求体迅速膨胀到 MB 级。**请求体硬上限 5 MB，超过返回 `413 payload_too_large`**。需要传图请上传到对象存储后传 URL，或用 `asset://` 引用素材库。

### Authentication

`Authorization: Bearer tr-xxx`

### Request Body

Content-Type: `application/json`

- **model** `string` **(required)**  
  视频生成模型 ID，可通过 `GET /v1/models` 过滤 `type: video` 获取。
- **content** `object[]` **(required)**  
  输入给模型的信息，支持文本、图片、视频、音频。支持以下组合：
- **content[].type** ``text` | `image_url` | `video_url` | `audio_url`` **(required)**  
  输入内容的类型：
- **content[].text** `string`  
  文本提示词（当 `type: text` 时使用）。支持中英文，建议中文不超过 500 字
- **content[].image_url** `object`  
  图片对象（当 `type: image_url` 时使用）
- **content[].role** ``first_frame` | `last_frame` | `reference_image` | `reference_video` | `reference_audio``  
  图片/视频/音频的位置或用途：
- **content[].video_url** `object`  
  视频对象（当 `type: video_url` 时使用，仅 Seedance 2.0）
- **content[].audio_url** `object`  
  音频对象（当 `type: audio_url` 时使用，仅 Seedance 2.0）
- **resolution** ``480p` | `720p` | `1080p` | `768P` | `2K`` (default: `720p`)  
  输出视频分辨率。
- **ratio** ``16:9` | `4:3` | `1:1` | `3:4` | `9:16` | `21:9` | `adaptive`` (default: `adaptive`)  
  输出视频宽高比。
- **duration** `integer` (default: `5`)  
  输出视频时长（秒），整数。设为 `-1` 由模型自主选择合适时长（注意时长与计费相关）。
- **seed** `integer` (default: `-1`)  
  随机种子，用于控制生成的随机性。取值范围 [-1, 2^32-1]。
- **generate_audio** `boolean` (default: `true`)  
  是否生成有声视频。模型会基于提示词与视觉内容，自动生成匹配的人声、音效及背景音乐。
- **return_last_frame** `boolean` (default: `false`)  
  是否返回视频尾帧图像（png 格式，无水印，与视频同分辨率）。
- **camera_fixed** `boolean` (default: `false`)  
  是否固定摄像头。
- **watermark** `boolean` (default: `false`)  
  生成视频是否包含水印
- **service_tier** ``default` | `flex`` (default: `default`)  
  服务等级（不支持修改已提交任务的服务等级）：
- **callback_url** `string`  
  任务终态回调地址。任务进入 `succeeded` / `failed` 时，XRToken 会向此 URL 发送一次 `POST` 请求。
- **safety_identifier** `string`  
  终端用户唯一标识符，用于安全审计。建议传入用户 ID 的哈希值，长度不超过 64 字符。

### Response

- **id** `string` **(required)**  
  平台内部任务 ID（用于轮询状态）
- **upstream_id** `string`  
  上游服务商的任务 ID（仅供参考）
- **model** `string` **(required)**  
  使用的模型 ID
- **status** ``queued`` **(required)**  
  初始任务状态，固定为 `queued`
- **created_at** `string` **(required)**  
  任务创建时间（ISO 8601 格式）

### Error Codes

- `400`: 
- `401`: 
- `402`: 
- `429`: 
- `502`: