# UniAI Docs Full Markdown
Generated from the UniAI documentation source for AI and LLM consumption.
Website: https://docs.uniai.tv/
Index: https://docs.uniai.tv/llms.txt
---
# 文档概览
Locale: zh-CN
URL: https://docs.uniai.tv/
Source: .generated/cn/site-docs/overview.md
Description: UniAI 中国站 API 接入地址、模型文档与任务调用说明。
UniAI 开发者文档介绍中国站的图像、视频和数字人接口。先在[模型列表](/models)中选择模型，再按对应文档准备参数和请求。
## 接入地址
本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。
| 项目 | 地址或规则 |
| --- | --- |
| API 服务地址 | `https://api.uniai.tv` |
| 模型列表接口 | `GET /v1/models` |
| 认证 | 除非模型页面另有说明，使用 `Authorization: Bearer sk-***`。 |
| 主站 | [UniAI](https://www.uniai.tv) |
| 控制台 | [开发者工作台](https://www.uniai.tv/app) |
| 模型与价格 | [模型广场](https://uniai.tv/models) |
接口路径直接接在服务地址后，例如 `https://api.uniai.tv/v1/models`。模型 ID、JSON 字段和大小写以各模型的调用文档为准。
## 选择能力
| 能力 | 调用说明 |
| --- | --- |
| 图像 | [图像生成概览](/models/image/overview)：Qwen Image、Seedream 5.0 Pro 和 Kling。 |
| 视频 | [视频生成概览](/models/video/overview)：Seedance、Happy Horse、Kling、Vidu、Hailuo 和 MiniMax H3。 |
| 数字人 | [可灵数字人口播](/models/avatar/digital-human)：使用 `kling-v3` 和 `operation: avatar`。 |
完整模型范围见[模型列表](/models)，当前可访问模型还取决于账户与 API Key 的权限。
## 任务结果
同步图像接口直接返回结果。异步视频任务返回任务 ID，保存该 ID 后按模型文档查询状态，在任务完成后获取结果。公共状态与下载说明见[视频任务生命周期](/models/video/overview)。
## AI 可读文档
中国站默认使用简体中文。当前页面支持复制为 Markdown，也提供以下索引供开发工具读取：
- [LLMs.txt](/llms.txt)
- [完整 Markdown](/llms-full.txt)
- [模型文档映射](/model-docs.json)
## 相关页面
- [查询余额](/balance)
- [模型列表](/models)
---
# 查询余额
Locale: zh-CN
URL: https://docs.uniai.tv/balance
Source: .generated/cn/site-docs/balance.md
Description: 查询账户余额和额度使用情况。
## 1. 接口说明
该接口用于通过普通 API Key 查询：
- 当前 API Key 所属的用户 ID
- 用户账户余额
- 用户余额按站点配置换算后的展示金额
- 当前这把 API Key 的额度信息
该接口使用普通 `sk-...` API Key 调用，不需要用户登录态。
---
## 2. 请求信息
| 项目 | 内容 |
| --- | --- |
| 请求方法 | `GET` |
| 请求路径 | `/api/usage/balance` |
| 鉴权方式 | `Authorization: Bearer sk-xxx` |
| Content-Type | 无请求体，可不传 |
---
## 3. 请求示例
```bash
curl -X GET "https://api.uniai.tv/api/usage/balance" \
-H "Authorization: Bearer sk-your-api-key"
```
---
## 4. 成功响应示例
```json
{
"success": true,
"message": "",
"data": {
"object": "api_key_balance",
"user_id": 1,
"balance": {
"quota": 1000000,
"amount": 14.6,
"display_amount": "¥14.60",
"quota_per_unit": 500000,
"quota_display_type": "CNY",
"currency_symbol": "¥",
"exchange_rate": 7.3
},
"token": {
"id": 12,
"name": "my-key",
"remain_quota": 100000,
"used_quota": 5000,
"total_quota": 105000,
"unlimited_quota": false,
"expired_time": -1,
"status": 1,
"model_limits_enabled": false,
"model_limits": {}
}
}
}
```
---
## 5. 响应参数说明
### 5.1 顶层参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `success` | boolean | 请求是否成功 |
| `message` | string | 响应消息，成功时通常为空字符串 |
| `data` | object | 响应数据 |
### 5.2 `data` 参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `data.object` | string | 对象类型，固定为 `api_key_balance` |
| `data.user_id` | number | 当前 API Key 所属的用户 ID |
| `data.balance` | object | 用户账户余额信息 |
| `data.token` | object | 当前 API Key 的额度信息 |
### 5.3 `data.balance` 参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `data.balance.quota` | number | 用户账户原始额度，系统内部额度单位 |
| `data.balance.amount` | number | 按站点展示配置换算后的余额金额 |
| `data.balance.display_amount` | string | 格式化后的展示金额，通常包含货币符号 |
| `data.balance.quota_per_unit` | number | 额度换算单位，例如 `500000` 表示 `500000 quota = 1 USD` |
| `data.balance.quota_display_type` | string | 余额展示类型，可能值：`USD`、`CNY`、`CUSTOM`、`TOKENS` |
| `data.balance.currency_symbol` | string | 当前展示货币符号，例如 `$`、`¥`；当展示类型为 `TOKENS` 时为空字符串 |
| `data.balance.exchange_rate` | number | 当前展示币种使用的汇率；`USD` 通常为 `1`，`CNY` 为人民币汇率，`CUSTOM` 为自定义汇率 |
### 5.4 `data.token` 参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `data.token.id` | number | 当前 API Key 的 ID |
| `data.token.name` | string | 当前 API Key 的名称 |
| `data.token.remain_quota` | number | 当前 API Key 剩余额度 |
| `data.token.used_quota` | number | 当前 API Key 已使用额度 |
| `data.token.total_quota` | number | 当前 API Key 总额度，计算方式为 `remain_quota + used_quota` |
| `data.token.unlimited_quota` | boolean | 当前 API Key 是否为无限额度 |
| `data.token.expired_time` | number | 当前 API Key 过期时间戳；`-1` 表示不过期 |
| `data.token.status` | number | 当前 API Key 状态；`1` 表示启用 |
| `data.token.model_limits_enabled` | boolean | 当前 API Key 是否启用模型限制 |
| `data.token.model_limits` | object | 当前 API Key 的模型限制配置；未限制时通常为空对象 `{}` |
---
---
## 6. 错误响应
### 6.1 未传 API Key
HTTP 状态码：`401`
```json
{
"success": false,
"message": "Token not provided"
}
```
### 6.2 API Key 不存在或无效
HTTP 状态码：`401`
```json
{
"success": false,
"message": "Invalid token"
}
```
### 6.3 API Key 已禁用
HTTP 状态码：`403`
```json
{
"success": false,
"message": "Token invalid"
}
```
---
## 7. 调用注意事项
- 必须使用 `Authorization: Bearer sk-xxx` 传入 API Key。
- 返回的是 API Key 所属用户的账户余额，不是上游渠道余额。
- 接口不会返回原始 API Key 字符串。
- 已禁用的 API Key 不能查询余额。
- API Key 已过期或额度耗尽时，仍可查询余额，只要 Key 未禁用且用户未被封禁。
- `amount` 和 `display_amount` 会根据站点当前余额展示配置动态变化。
---
# 模型列表
Locale: zh-CN
URL: https://docs.uniai.tv/models
Source: .generated/cn/site-docs/models/index.md
Description: UniAI 中国站模型目录、精确模型 ID 和对应调用文档。
本页列出中国站模型目录和调用文档。当前可用范围与价格以[模型广场](https://uniai.tv/models)为准；账户可访问模型可通过模型列表接口查询。
## 查询模型
本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。
| 方法 | 路径 | 认证 |
| --- | --- | --- |
| GET | `/v1/models` | `Authorization: Bearer sk-***` |
请求没有必填查询参数。请使用当前账户的 API Key。
```bash
curl "https://api.uniai.tv/v1/models" \
-H "Authorization: Bearer sk-***"
```
响应结构示例；实际列表取决于账户权限：
```json
{
"object": "list",
"data": [
{
"id": "hailuo-02",
"object": "model"
},
{
"id": "hailuo-2.3",
"object": "model"
},
{
"id": "hailuo-2.3-fast",
"object": "model"
}
]
}
```
## 模型目录
| 模型 ID | 能力 | 调用说明 |
| --- | --- | --- |
| `hailuo-02` | 视频 | [调用文档](/models/video/hailuo) |
| `hailuo-2.3` | 视频 | [调用文档](/models/video/hailuo) |
| `hailuo-2.3-fast` | 视频 | [调用文档](/models/video/hailuo) |
| `happy-horse` | 视频 | [调用文档](/models/video/happy-horse) |
| `kling-image-o1` | 图像 | [调用文档](/models/image/kling) |
| `kling-o1` | 视频 | [调用文档](/models/video/kling) |
| `kling-v3` | 图像 | [调用文档](/models/video/kling) |
| `kling-v3-omni` | 视频 | [调用文档](/models/video/kling) |
| `kling-v3-turbo` | 视频 | [调用文档](/models/video/kling) |
| `minimax-h3` | 视频 | [调用文档](/models/video/minimax-h3) |
| `minimax-h3-max` | 视频 | [调用文档](/models/video/minimax-h3) |
| `qwen-image-2.0` | 图像 | [调用文档](/models/image/qwen-image) |
| `qwen-image-2.0-pro` | 图像 | [调用文档](/models/image/qwen-image) |
| `qwen-image-2.1-pro` | 图像 | [调用文档](/models/image/qwen-image) |
| `qwen-image-2.1-turbo` | 图像 | [调用文档](/models/image/qwen-image) |
| `qwen-image-3.0` | 图像 | [调用文档](/models/image/qwen-image) |
| `qwen-image-3.0-pro` | 图像 | [调用文档](/models/image/qwen-image) |
| `seedance2.0` | 视频 | [调用文档](/models/video/seedance-2-0) |
| `seedance2.0-fast` | 视频 | [调用文档](/models/video/seedance-2-0) |
| `seedance2.0-mini` | 视频 | [调用文档](/models/video/seedance-2-0) |
| `seedance2.5` | 视频 | [调用文档](/models/video/seedance-2-5) |
| `seedream-5.0-pro` | 图像 | [调用文档](/models/image/seedream-5-0-pro) |
| `viduq3p` | 视频 | [调用文档](/models/video/vidu) |
| `viduq3t` | 视频 | [调用文档](/models/video/vidu) |
| `wan2.2-animate-mix` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.2-animate-move` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.6-i2v` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.6-i2v-flash` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.6-r2v` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.6-r2v-flash` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.6-t2v` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.7-i2v` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.7-i2v-2026-04-25` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.7-r2v-2026-06-12` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.7-t2v` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.7-t2v-2026-04-25` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.7-t2v-2026-06-12` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan2.7-videoedit` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan3.0-video` | 视频 | [模型广场详情](https://uniai.tv/models) |
| `wan3.0-video-prime` | 视频 | [模型广场详情](https://uniai.tv/models) |
Wan 模型请按模型广场详情选择当前版本与参数，不要将旧版分辨率档位后缀用作当前模型 ID。
## 调用与计费
模型列表查询不创建生成任务。生成接口的参数、异步任务流程和计费维度见对应模型文档，价格以模型广场和账户用量记录为准。
## 常见问题
- 返回 401：检查 API Key 和认证 Header。
- 找不到模型：核对精确 ID、当前账户权限和模型广场中的可用状态。
- 模型列表返回成功不代表任意参数组合都受支持，请继续阅读对应接口文档。
---
# 数字人口播
Locale: zh-CN
URL: https://docs.uniai.tv/models/avatar/digital-human
Source: .generated/cn/site-docs/models/avatar/digital-human.md
Description: 使用一张图片和音频或 UniAI 音色 ID 创建 Kling V3 数字人视频。
本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。
## 概览
可灵数字人统一使用稳定模型 `kling-v3`，并传入 `operation: avatar`。请求需要一张公开图片，以及音频 URL 或 UniAI `voice_id` 二选一；不要再使用历史 Kling Avatar 档位模型名。
UniAI 当前没有开放可灵主体库的创建和查询接口，因此普通公开请求不要传 `subject_ids`。
## 适用场景
- 已有口播音频时使用 `audio_url`。
- 需要使用 UniAI 音色列表或克隆接口返回的音色时使用 `voice_id`。
- 标准清晰度使用 `resolution: std`，更高清晰度使用 `resolution: pro`。
## 接口
| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建数字人视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` |
| 查询可灵音色 | `GET` | `/v1/audio/voices?model=kling-v3` |
| 克隆可灵音色 | `POST` | `/v1/audio/voices/clone` |
## 鉴权
```http
Authorization: Bearer sk-***
Content-Type: application/json
```
## 请求参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 使用 `kling-v3`。 |
| `operation` | string | 是 | 使用 `avatar`。 |
| `prompt` | string | 是 | UniAI 视频接口要求提供的讲解、表情和镜头提示词。 |
| `image` | string | 是 | 数字人图片的公开 HTTP(S) URL。 |
| `audio_url` | string | 条件必填 | 公开口播音频 URL，与 `voice_id` 二选一。 |
| `voice_id` | string | 条件必填 | UniAI 音色 ID，与 `audio_url` 二选一。 |
| `resolution` | string | 否 | `std` 或 `pro`，默认 `std`。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |
不要传 `sound` 开关。`audio_url` 和 `voice_id` 是口型驱动输入，展示风格由提示词描述；同一个请求不要同时传入两个音色输入。
## 查询可用音色
```bash
curl "{BASE_URL}/v1/audio/voices?model=kling-v3" \
-H "Authorization: Bearer sk-***"
```
使用音色列表响应中的 UniAI `voice_id`，不要传入上游音色 ID。
## 克隆音色
```bash
curl -X POST "{BASE_URL}/v1/audio/voices/clone" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3",
"voice_name": "产品旁白",
"audio_url": "https://example.com/voice-sample.mp3",
"text": "这是克隆音色的试听文本。"
}'
```
克隆成功后保存响应中的 UniAI `voice_id`，再用于数字人任务。
## 请求示例
### 使用音频 URL
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3",
"operation": "avatar",
"prompt": "自然讲解产品，表情友好，正面稳定镜头。",
"image": "https://example.com/presenter.png",
"audio_url": "https://example.com/speech.mp3",
"resolution": "pro",
"watermark": false
}'
```
### 使用 UniAI 音色
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3",
"operation": "avatar",
"prompt": "专业讲解口吻，表情自然，正面稳定镜头。",
"image": "https://example.com/presenter.png",
"voice_id": "voice_xxxxxxxxxxxxx",
"resolution": "std"
}'
```
## 响应示例
```json
{
"id": "task_xxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxx",
"object": "video.generation.job",
"model": "kling-v3",
"status": "queued",
"progress": 0
}
```
## 任务状态与结果
保存 `id` 或 `task_id`，然后按照[视频生成概览](/models/video/overview#视频任务生命周期)中的公共规则，每 3 到 10 秒轮询一次，并处理终态、结果字段、错误和带鉴权下载。
## 计费说明
数字人视频通常结合 `kling-v3`、`operation: avatar`、`resolution` 和输出时长计费。音色克隆可能按照模型广场当前规则单独计费。任务提交时可能预扣，最终以任务结算和消费记录为准。
## 常见错误
- 使用历史数字人档位模型名，而不是 `kling-v3`。
- 缺少 `operation: avatar` 或必填的 `prompt`。
- 同时传入 `audio_url` 和 `voice_id`，或两者都没有传。
- 传入上游音色 ID，而不是 UniAI `voice_id`。
- 在公开主体库接口尚未开放时传入 `subject_ids`。
- 传入 `sound`、`duration`，或媒体 URL 无法由服务端公开访问。
- 一次轮询超时后重新提交付费任务，而不是继续查询原 `task_id`。
公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。
## 相关页面
- [Kling 视频](/models/video/kling)
- [Kling 图片](/models/image/kling)
- [视频生成概览](/models/video/overview)
---
# 数字人概览
Locale: zh-CN
URL: https://docs.uniai.tv/models/avatar/overview
Source: .generated/cn/site-docs/models/avatar/overview.md
Description: UniAI 数字人口播文档入口。
本分类整理来源菜单中的数字人口播流程，以及用户提供的 Kling V3 调用口径。
## 包含页面
- [数字人口播](/models/avatar/digital-human)
## 接入建议
数字人口播使用 `kling-v3` 和 `operation: avatar`。提交一张数字人图片，并在音频 URL 和 UniAI `voice_id` 中二选一，随后轮询返回的 `task_id`，直到输出视频可用。
如果流程需要 `voice_id`，使用[数字人口播](/models/avatar/digital-human)页面中的可灵音色列表或克隆接口。
---
# Kling
Locale: zh-CN
URL: https://docs.uniai.tv/models/image/kling
Source: .generated/cn/site-docs/models/image/kling.md
Description: 通过 UniAI 异步图片任务调用可灵 V3、Omni 和 Image O1 生成及编辑图片。
本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。
## 概览
可灵图片能力统一使用 `POST /v1/images/tasks`。通过 `operation` 选择生成方式，通过请求体顶层的 `resolution` 选择清晰度，通过 `num_images` 选择输出数量。
| 模型 | 图片能力 | 清晰度 |
| --- | --- | --- |
| `kling-v3` | 文生图、单图编辑、扩图、主体图补全 | `1k`、`2k` |
| `kling-v3-omni` | 文生图、单图编辑、多图参考、组图 | `1k`、`2k`、`4k` |
| `kling-image-o1` | 文生图、单图编辑、多图参考、组图 | `1k`、`2k`、`4k` |
模型是否可用取决于模型广场、API Key 的模型权限和当前启用的路由。
## 适用场景
- 文生图、单图编辑、扩图或根据一张正面图补全主体时使用 `kling-v3`。
- 需要最多四张参考图、`4k` 或组图结果时使用 `kling-v3-omni`。
- 需要相同的多图请求结构、且只使用图片模型时使用 `kling-image-o1`。
## 接口
| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建异步图片任务 | `POST` | `/v1/images/tasks` |
| 查询图片任务 | `GET` | `/v1/images/tasks/{task_id}` |
## 鉴权
```http
Authorization: Bearer sk-***
Content-Type: application/json
```
## 清晰度与比例
在请求体顶层传入 `resolution`，不要使用 `size` 代替。默认值为 `1k`；`outpaint` 和 `complete_subject` 不要传 `resolution`。
- V3 支持 `16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`3:2`、`2:3` 和 `21:9`。
- Omni 和 Image O1 除上述比例外还支持 `auto`。
## 生成方式
| `operation` | 支持模型 | 必要输入 |
| --- | --- | --- |
| `text_to_image` | V3、Omni、Image O1 | 无输入图 |
| `image_edit` | V3、Omni、Image O1 | 一张 `image` |
| `reference_to_image` | Omni、Image O1 | `images` 传两到四张参考图 |
| `outpaint` | V3 | 一张 `image` 和 `outpaint` |
| `complete_subject` | V3 | 一张正面 `image` |
`kling-v3` 不接受两张原始图片用于 `reference_to_image`。多图参考应使用 `kling-v3-omni` 或 `kling-image-o1`。
## 请求参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `kling-v3`、`kling-v3-omni` 或 `kling-image-o1`。 |
| `task_type` | string | 是 | 文生图使用 `text2image`；其他图片 operation 使用 `image2image`。 |
| `operation` | string | 是 | 上表中的生成方式。 |
| `prompt` | string | 是 | UniAI 异步图片接口要求提供的提示词。 |
| `image` | string | 条件必填 | 单图 operation 使用的一张公开图片 URL。 |
| `images` | string[] | 条件必填 | 多图参考使用的两到四张公开图片 URL。 |
| `resolution` | string | 否 | `1k`、`2k` 或模型支持的 `4k`；默认 `1k`。扩图和主体补全不要传。 |
| `aspect_ratio` | string | 否 | 输出比例；支持的图片编辑请求可使用 `auto`。 |
| `num_images` | integer | 否 | 输出数量，范围为 `1` 到 `9`。 |
| `negative_prompt` | string | 否 | V3 文生图的反向提示词。 |
| `result_type` | string | 否 | Omni 和 Image O1 可使用 `single` 或 `series`。 |
| `outpaint` | object | 条件必填 | `outpaint` 使用的四方向扩展倍率。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |
## 请求示例
### V3 文生图
```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3",
"task_type": "text2image",
"operation": "text_to_image",
"prompt": "电影感产品摄影，一只银色腕表放在黑色石材展台上。",
"negative_prompt": "模糊，变形，文字，水印",
"resolution": "2k",
"aspect_ratio": "16:9",
"num_images": 1,
"watermark": false
}'
```
### V3 单图编辑
```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3",
"task_type": "image2image",
"operation": "image_edit",
"prompt": "保持人物身份，把背景替换为干净的摄影棚。",
"image": "https://example.com/person.png",
"resolution": "2k",
"aspect_ratio": "3:4",
"num_images": 1
}'
```
### Omni 多图参考 4K
```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-omni",
"task_type": "image2image",
"operation": "reference_to_image",
"prompt": "以第一张图为主体，参考第二张图的服装和色彩，生成统一的电影感肖像。",
"images": [
"https://example.com/person.png",
"https://example.com/style.png"
],
"resolution": "4k",
"aspect_ratio": "16:9",
"num_images": 1,
"result_type": "single"
}'
```
`kling-image-o1` 使用相同的多图参考结构，只需修改 `model`。
### V3 扩图
```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3",
"task_type": "image2image",
"operation": "outpaint",
"prompt": "自然延展海滩和天空，保持原图光线与透视。",
"image": "https://example.com/source.png",
"outpaint": {
"up_expansion_ratio": 0.2,
"down_expansion_ratio": 0,
"left_expansion_ratio": 0.1,
"right_expansion_ratio": 0.1
},
"num_images": 1,
"watermark": false
}'
```
每个扩图倍率必须在 `0` 到 `2` 之间，至少一个方向大于 `0`，扩展后的总面积不能超过原图的三倍。扩图不要传 `resolution`。
### V3 主体图补全
```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3",
"task_type": "image2image",
"operation": "complete_subject",
"prompt": "补全人物主体图。",
"image": "https://example.com/front.png"
}'
```
主体图补全只接受一张正面图，不传 `resolution`、`aspect_ratio` 或 `num_images`。`prompt` 用于满足 UniAI 图片任务的通用请求要求，不会代替图片输入。
## 响应示例
```json
{
"task_id": "task_xxxxxxxxxxxxx",
"status": "queued",
"progress": "0%",
"result_url": "",
"metadata": {
"task_type": "image2image"
},
"error": null
}
```
## 任务状态与结果
每 3 到 10 秒调用 `GET /v1/images/tasks/{task_id}`，直到任务进入 `succeeded` 或 `failed`。查询响应外层为 `code` 和 `data`；成功后读取 `data.result_url`，多图结果同时读取 `data.metadata.result_urls`。
不要因为一次查询超时就重新提交付费任务，应继续查询原 `task_id`。
## 计费说明
图片通常结合公共模型、`operation`、`resolution`、输入图片数和输出图片数计费。任务提交时可能预扣，最终以任务结算记录和模型广场当前价格为准。
## 常见错误
- 使用 `size` 代替 `resolution`。
- 给 `kling-v3` 传入 `4k`。
- 使用 `kling-v3` 和两张原始图片调用 `reference_to_image`。
- 混用 `image`、`images` 和 `reference_image_urls`，重复提交同一输入。
- 给 `outpaint` 或 `complete_subject` 传入 `resolution`。
- 媒体 URL 无法由服务端公开访问。
- 查询超时后重新提交，而不是继续轮询原任务。
公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。
## 相关页面
- [Kling 视频](/models/video/kling)
- [数字人口播](/models/avatar/digital-human)
---
# 图像生成概览
Locale: zh-CN
URL: https://docs.uniai.tv/models/image/overview
Source: .generated/cn/site-docs/models/image/overview.md
Description: UniAI 中国站 Qwen Image、Seedream 5.0 Pro 和 Kling 图像接口。
根据模型选择文生图、参考图生成或编辑接口。不同模型的参考图数量、尺寸、输出格式和同步方式以专属文档为准。
## 模型
- [Qwen Image](/models/image/qwen-image)
- [Seedream 5.0 Pro](/models/image/seedream-5-0-pro)
- [Kling](/models/image/kling)
## 接入
本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。具体接口路径、参数和请求/响应示例见上述模型页面。通常使用 `Authorization: Bearer sk-***`，并使用模型广场中当前开放的精确模型 ID。
图像编辑是否接受 JSON 或 multipart、是否返回 Base64、是否需要查询任务，均按各模型文档执行。
## 相关页面
- [模型列表](/models)
- [查询余额](/balance)
---
# Qwen Image
Locale: zh-CN
URL: https://docs.uniai.tv/models/image/qwen-image
Source: .generated/cn/site-docs/models/image/qwen-image.md
Description: Qwen Image 3.0、2.1、2.0 的 OpenAI Images 和百炼原生同步生图、编辑调用文档。
支持 OpenAI Images 和百炼原生接口，均同步返回图片 URL，无需轮询任务。
## 模型
| 模型 ID | 参考图上限 |
| --- | --- |
| `qwen-image-3.0-pro` | 3 张 |
| `qwen-image-3.0` | 3 张 |
| `qwen-image-2.1-pro` | 10 张 |
| `qwen-image-2.1-turbo` | 10 张 |
| `qwen-image-2.0-pro` | 3 张 |
| `qwen-image-2.0` | 3 张 |
## 接口
服务地址为 `https://api.uniai.tv`，使用 `Authorization: Bearer $UNIAI_API_KEY` 认证。示例中的 Key 和参考图地址请替换为自己的值。
| 格式 | 方法 | 路径 |
| --- | --- | --- |
| OpenAI 生图 | POST | `/v1/images/generations` |
| OpenAI 编辑（JSON 或 multipart） | POST | `/v1/images/edits` |
| 百炼原生生图与编辑 | POST | `/api/v1/services/aigc/multimodal-generation/generation` |
## 参数
OpenAI JSON 将下列字段放在顶层。百炼原生格式中，`model` 放顶层，提示词和图片放在 `input.messages`，生成选项放在 `parameters`。
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 上述六个模型 ID 之一。 |
| `prompt` | string | 是 | 生图或编辑指令。原生格式使用 `input.messages[0].content` 中的一条 `text`。 |
| `image` | string 或 array | 编辑时必填 | 按顺序传入参考图 URL 或图片 data URL。原生格式每张图使用一条 `image` 内容项。 |
| `n` | integer | 否 | 输出图片数，1–6，默认 `1`。 |
| `size` | string | 否 | `WIDTHxHEIGHT`、`WIDTH*HEIGHT` 或 `auto`，范围见下方限制。 |
| `seed` | integer | 否 | 0–2147483647。 |
| `negative_prompt` | string | 否 | 仅 3.0 和 2.0 系列支持。 |
| `prompt_extend` | boolean | 否 | 是否扩写提示词。 |
| `prompt_extend_mode` | string | 否 | `direct` 或 `agent`，仅 3.0 和 2.1 支持；`agent` 仅用于文生图。 |
| `enable_thinking` | boolean | 否 | 仅 3.0 和 2.1 系列支持。 |
| `watermark` | boolean | 否 | 是否添加水印。 |
| `response_format` | string | 否 | 仅 OpenAI 格式使用，只支持 `url`。 |
OpenAI 还支持 `n` 的别名 `num_images`，以及参考图字段 `image_url`、`image_urls`、`images`。参考图字段选用一种；同时传入 `n` 和 `num_images` 时必须一致。生成选项也可放在 `extra_body`，与顶层重复时值必须一致。
## OpenAI Images {/* #openai-images */}
### 文生图
```bash
curl "https://api.uniai.tv/v1/images/generations" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-3.0",
"prompt": "A blue ceramic cup on a wooden table",
"n": 1,
"size": "1024x1024",
"seed": 0,
"prompt_extend": false,
"enable_thinking": false,
"watermark": false
}'
```
### 使用参考图 URL 编辑
```bash
curl "https://api.uniai.tv/v1/images/edits" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-2.1-pro",
"prompt": "Turn the cup blue and keep the rest unchanged",
"image": ["https://images.example.com/reference.png"],
"n": 1,
"size": "1024x1024"
}'
```
同一 JSON 请求也可发送至 `/v1/images/generations`，包含 `image` 时执行编辑。参考图数组顺序保持不变。
### 上传本地图片编辑
```bash
curl "https://api.uniai.tv/v1/images/edits" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-F "model=qwen-image-2.1-pro" \
-F "prompt=Turn the cup blue and keep the rest unchanged" \
-F "image[]=@reference.png" \
-F "n=1" \
-F "size=1024x1024" \
-F "seed=0" \
-F "enable_thinking=false"
```
多张参考图可重复添加 `-F "image[]=@another.png"`。表单中的整数使用数字字符串，布尔值使用 `true` / `false`；multipart 的 Content-Type 由 cURL 自动设置。
### 响应
生图和编辑返回相同结构，从 `data[].url` 获取图片地址。
```json
{
"created": 1792627200,
"data": [
{
"url": "https://images.example.com/result.png"
}
]
}
```
## 百炼原生接口 {/* #bailian-native */}
只传一条 `user` 消息，其中必须包含一条 `text`。编辑时添加 `image` 内容项，文生图时省略图片。
### 文生图
```bash
curl "https://api.uniai.tv/api/v1/services/aigc/multimodal-generation/generation" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-3.0",
"input": {
"messages": [{
"role": "user",
"content": [{"text": "A blue ceramic cup on a wooden table"}]
}]
},
"parameters": {
"n": 1,
"size": "1024*1024",
"seed": 0,
"prompt_extend": false,
"enable_thinking": false,
"watermark": false
}
}'
```
### 图片编辑
```bash
curl "https://api.uniai.tv/api/v1/services/aigc/multimodal-generation/generation" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-2.1-pro",
"input": {
"messages": [{
"role": "user",
"content": [
{"image": "https://images.example.com/reference.png"},
{"text": "Turn the cup blue and keep the rest unchanged"}
]
}]
},
"parameters": {"n": 1, "size": "1024*1024"}
}'
```
### 响应
从 `output.choices[].message.content[].image` 获取图片地址。
```json
{
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://images.example.com/result.png"
}
]
}
}
]
},
"request_id": "req_example"
}
```
## 限制
- 输出总像素为 262,144–4,194,304（512²–2048²），宽高比为 1:8–8:1。这是面积限制，不是单边最多 2048 像素；`3840x2160` 等标准 4K 尺寸超出范围。
- 参考图每张不超过 10 MB，数量上限见模型表。
- 输出格式为 PNG。2.1 系列需要透明背景时，在提示词中描述。
- 不支持流式、蒙版编辑或 Base64 输出；不要传 `quality`、`output_format`、`operation`。
请求可能耗时数十秒。超时后先检查请求记录，再决定是否重发。图片 URL 可能过期，请及时保存结果。
## 请求错误
HTTP 400 时检查必填字段、模型支持的选项、参考图数量和尺寸范围；HTTP 401 时检查 Bearer Key。`/v1/images/edits` 至少需要一张参考图。
---
# Seedream 5.0 Pro
Locale: zh-CN
URL: https://docs.uniai.tv/models/image/seedream-5-0-pro
Source: .generated/cn/site-docs/models/image/seedream-5-0-pro.md
Description: 通过 UniAI.ai 同步图片接口调用 seedream-5.0-pro 生成或编辑图片。
使用 `seedream-5.0-pro` 时，文生图和图片编辑分别调用对应的同步接口。文生图使用 `/v1/images/generations` 且不传 `image`；图生图或图片编辑使用 `/v1/images/edits`，并传入 1 至 10 张参考图。
本文档对应 2026 年 7 月 25 日更新的公开调用契约。
## 概览
- 两个接口都在同一个 HTTP 响应中返回最终图片，不需要创建或轮询异步任务。
- 每次请求固定生成一张图片。
- 可以使用 `1K` 或 `2K` 分辨率档位并指定画幅比例，也可以直接传入精确尺寸。
- 参考图支持公网 URL 和 Base64 Data URL。
- 响应可以返回临时图片 URL 或纯 Base64 数据。
## 接口与鉴权
```http
POST https://api.uniai.tv/v1/images/generations
POST https://api.uniai.tv/v1/images/edits
Authorization: Bearer sk-***
Content-Type: application/json
```
- 文生图：调用 `/v1/images/generations`，不传 `image`。
- 图生图或图片编辑：调用 `/v1/images/edits`，并传入 `image`。
Base URL 为：
```uri
https://api.uniai.tv
```
如果 UniAI.ai 控制台为当前账号提供了专属 API 地址，请以控制台显示的地址为准。
## 快速开始
### 文生图
```bash
curl -X POST "https://api.uniai.tv/v1/images/generations" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5.0-pro",
"prompt": "高端护肤品广告图，玻璃瓶放在浅色石材台面上，柔和自然光，中文品牌文字清晰",
"size": "2K",
"aspect_ratio": "16:9",
"output_format": "jpeg",
"response_format": "url"
}'
```
### 图生图
```bash
curl -X POST "https://api.uniai.tv/v1/images/edits" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5.0-pro",
"prompt": "保留产品外形和标签文字，把背景替换成明亮的摄影棚场景",
"image": "https://example.com/source-product.png",
"size": "1K",
"aspect_ratio": "1:1",
"output_format": "png",
"response_format": "url"
}'
```
### 精确尺寸
需要固定宽高时，直接把精确尺寸传给 `size`。同一个请求中不要再传 `aspect_ratio`。
```bash
curl -X POST "https://api.uniai.tv/v1/images/generations" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5.0-pro",
"prompt": "宽幅科技产品发布会主视觉，主体位于画面中央，背景简洁",
"size": "2048x1024",
"output_format": "jpeg",
"response_format": "url"
}'
```
## 请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | 无 | 固定为 `seedream-5.0-pro`。 |
| `prompt` | string | 是 | 无 | 图片生成或编辑提示词。 |
| `image` | string / string[] | 图生图必填 | 无 | `/v1/images/edits` 的参考图，支持公网 URL 或 Base64 Data URL，最多 10 张。 |
| `size` | string | 否 | `2K` | `1K`、`2K` 或精确尺寸 `WIDTHxHEIGHT`。 |
| `aspect_ratio` | string | 否 | 由模型判断 | 使用 `1K`、`2K` 时可指定画幅比例；精确尺寸模式不能传。 |
| `output_format` | string | 否 | `jpeg` | `jpeg` 或 `png`。 |
| `response_format` | string | 否 | `url` | `url` 或 `b64_json`。 |
| `watermark` | boolean | 否 | `true` | 是否添加“AI 生成”水印。 |
该模型每次固定生成一张图片。
## 尺寸与画幅比例
尺寸有以下两种用法，选择其中一种。
### 分辨率档位与画幅比例
```json
{
"size": "2K",
"aspect_ratio": "16:9"
}
```
`size` 支持 `1K` 和 `2K`。`aspect_ratio` 支持 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3` 和 `21:9`。
常见输出尺寸如下。最终尺寸以响应中的 `data[0].size` 为准。
| 分辨率 | `1:1` | `4:3` | `3:4` | `16:9` | `9:16` | `3:2` | `2:3` | `21:9` |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `1K` | `1024x1024` | `1152x864` | `864x1152` | `1424x800` | `800x1424` | `1248x832` | `832x1248` | `1568x672` |
| `2K` | `2048x2048` | `2368x1776` | `1776x2368` | `2816x1584` | `1584x2816` | `2496x1664` | `1664x2496` | `3136x1344` |
不传 `aspect_ratio` 时，模型会根据提示词和参考图判断画幅。
### 精确尺寸
```json
{
"size": "2048x1024"
}
```
精确尺寸必须同时满足以下条件：
- `width * height` 必须在 `921600` 到 `4624220` 之间，包含边界值。
- 宽高比必须在 `1/16` 到 `16` 之间，包含边界值。
- 没有单独的 4096 最大边限制，例如 `4200x1000` 是合法尺寸。
- 不能同时传 `aspect_ratio`，因为精确尺寸已经确定画幅。
## 参考图输入
图生图和图片编辑统一调用 `/v1/images/edits`。
单张参考图传字符串，多张参考图传数组：
```json
{
"image": [
"https://example.com/product.png",
"data:image/png;base64,..."
]
}
```
同一个请求中可以混合使用公网 URL 和 Base64 Data URL。
### 公网 URL
- 图片必须能被公网直接访问。
- 访问图片不能依赖 Cookie、登录状态或额外请求头。
### Base64 Data URL
必须使用完整的 Data URL 格式：
```uri
data:image/png;base64,...
```
- 图片格式名必须小写，但不要求 Base64 内容本身小写。
- 支持 JPEG、PNG、WEBP、BMP、TIFF、GIF、HEIC 和 HEIF。
- 每张 Data URL 图片最大 `30 MB`。
- 单次请求的参考图总数不能超过 10 张。
## 响应格式
输入形式和输出形式相互独立。URL 输入可以返回 Base64，Base64 输入也可以返回 URL。
### URL 响应
请求参数：
```json
{
"response_format": "url"
}
```
响应示例：
```json
{
"created": 1784900000,
"data": [
{
"url": "https://example.com/generated.jpeg",
"size": "2816x1584",
"output_format": "jpeg"
}
],
"usage": {
"generated_images": 1,
"input_images": 0,
"output_tokens": 17424,
"total_tokens": 17424
}
}
```
返回的 URL 可能在生成后 24 小时失效，请及时下载并保存图片。
### Base64 响应
请求参数：
```json
{
"response_format": "b64_json"
}
```
图片项会返回 `b64_json`，不再返回 `url`：
```json
{
"data": [
{
"b64_json": "...",
"size": "2048x1024",
"output_format": "png"
}
]
}
```
`b64_json` 是纯 Base64 内容，不包含 Data URL 前缀。
### 响应字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `created` | integer | 响应的 Unix 时间戳。 |
| `data` | array | 生成结果数组，固定包含一个图片项。 |
| `data[].url` | string | `response_format` 为 `url` 时返回的临时图片地址。 |
| `data[].b64_json` | string | `response_format` 为 `b64_json` 时返回的纯 Base64 图片数据。 |
| `data[].size` | string | 最终输出尺寸，格式为 `WIDTHxHEIGHT`。 |
| `data[].output_format` | string | 最终图片格式。 |
| `usage.generated_images` | integer | 生成图片数量。 |
| `usage.input_images` | integer | 输入参考图数量。 |
| `usage.output_tokens` | integer | API 返回的输出用量。 |
| `usage.total_tokens` | integer | API 返回的总用量。 |
## 提示词定位与标注
点位、区域、文字替换、箭头、涂鸦和标注框都通过输入图与 `prompt` 表达，不需要增加请求参数。
```markdown
把 100 200 800 900 内的招牌替换为“新品上市”
在 520 380 附近增加一个小型台灯
```
坐标范围为 `0..999`。也可以直接在输入图中绘制箭头、标注框或其他标记，再通过提示词说明编辑意图。
## 计费说明
- 每次请求固定输出一张图片。
- 输入图片张数可能参与计费，具体以当前 UniAI.ai 模型页为准。
- 输出图片按实际像素分档：不超过 `2360000` 像素，或超过 `2360000` 像素。
- `1K`、`2K` 不是直接计费条件，最终根据生成图片的 `width * height` 判断档位。
- 具体单价、分组倍率和最终扣费以 UniAI.ai 模型页及消费日志为准。
## 常见问题
| 问题 | 常见原因 | 处理方式 |
| --- | --- | --- |
| 传入参考图后没有按编辑请求处理 | 请求发送到了 `/v1/images/generations`。 | 所有包含 `image` 的请求都改用 `/v1/images/edits`。 |
| 精确尺寸被拒绝 | 同时传了 `aspect_ratio`，或像素数、宽高比超出限制。 | 删除 `aspect_ratio`，并重新检查精确尺寸约束。 |
| 参考图被拒绝 | 超过 10 张、URL 无法公网直连，或 Data URL 格式不完整。 | 减少图片数量，并检查公网访问或完整 Data URL 格式。 |
| 图片格式被拒绝 | 使用了不支持的格式，或 Data URL 中的图片格式名不是小写。 | 改用支持的格式，并使用 `image/png` 等小写格式名。 |
| 响应中找不到预期字段 | 请求 `b64_json` 后仍读取 `url`，或反之。 | 根据 `response_format` 读取对应字段。 |
| 客户端在返回图片前超时 | 同步生成所需时间超过客户端 HTTP 超时。 | 增加客户端超时时间，继续等待原请求，不要轮询异步任务接口。 |
## 相关页面
- [图像生成概览](/models/image/overview)
- [模型列表](/models)
---
# Hailuo
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/hailuo
Source: .generated/cn/site-docs/models/video/hailuo.md
Description: 通过 UniAI 视频任务接口调用 Hailuo 系列，创建文生、单图和首尾帧视频。
本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。
更新时间：2026-08-04
## 概览
UniAI 通过 OpenAI 兼容的异步视频任务接口提供三个稳定的 Hailuo 公共模型。
| 模型 | 文生视频 | 单图生视频 | 首尾帧生视频 |
| --- | --- | --- | --- |
| `hailuo-02` | 支持 | 支持 | 支持 |
| `hailuo-2.3` | 支持 | 支持 | 不支持 |
| `hailuo-2.3-fast` | 不支持 | 支持 | 不支持 |
三个模型统一使用创建、查询和内容下载接口，请求字段组合决定生成模式。
## 适用场景
Hailuo 系列适合以下任务：
- 根据提示词生成 6 秒或 10 秒视频；
- 让一张可公开访问的图片动起来；
- 使用 `hailuo-02` 生成首尾帧过渡视频；
- 选择 `768p` 或 `1080p` 输出。
Hailuo 公共契约不支持音频、多参考图、参考视频、画幅比例控制或视频编辑。
## 公共限制
- `duration` 必须是 `6` 或 `10` 秒。
- `resolution` 必须是 `768p` 或 `1080p`。
- `1080p` 只支持生成 6 秒视频。
- 输入图片必须是公开可访问的 HTTP(S) URL。
- 提示词最长 2,000 个字符。
## 接口
| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载视频文件 | `GET` | `/v1/videos/{task_id}/content` |
## 鉴权
所有请求均使用 UniAI Bearer Token：
```http
Authorization: Bearer sk-***
```
创建任务时还需发送：
```http
Content-Type: application/json
```
## 请求体参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `hailuo-02`、`hailuo-2.3` 或 `hailuo-2.3-fast`。 |
| `prompt` | string | 是 | 视频内容描述，最长 2,000 个字符。 |
| `image` | string | 条件必填 | 单图生视频的输入图或首尾帧模式的首帧，必须是公开 HTTP(S) URL。 |
| `last_image` | string | 条件必填 | 尾帧图片的公开 HTTP(S) URL；仅 `hailuo-02` 支持，且必须与 `image` 一起传入。 |
| `duration` | integer | 是 | `6` 或 `10`。 |
| `resolution` | string | 是 | `768p` 或 `1080p`；`1080p` 只支持 6 秒。 |
| `prompt_optimizer` | boolean | 否 | 是否在生成前优化提示词。 |
| `fast_pretreatment` | boolean | 否 | 是否使用快速预处理；首尾帧模式不要传 `true`。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |
根据生成模式选择输入字段：
| 模式 | 模型 | 输入字段 |
| --- | --- | --- |
| 文生视频 | `hailuo-02` 或 `hailuo-2.3` | `prompt` |
| 单图生视频 | 任意 Hailuo 模型 | `prompt` + `image` |
| 首尾帧生视频 | `hailuo-02` | `prompt` + `image` + `last_image` |
字段约束：
- 文生视频不要传入 `image` 或 `last_image`。
- `hailuo-2.3-fast` 只支持单图生视频，因此必须传入 `image`。
- `last_image` 不能单独使用，必须与 `image` 一起传入。
- `last_image` 只能与 `hailuo-02` 配合使用。
- 所有支持的公共参数都直接放在请求体顶层。
- 不要传入音频、多参考图数组、参考视频、画幅比例或视频编辑字段。
## 请求示例
### 文生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "hailuo-2.3",
"prompt": "A cinematic train passes through a snowy mountain canyon while morning mist drifts slowly and the camera moves forward.",
"duration": 6,
"resolution": "1080p",
"prompt_optimizer": true,
"watermark": false
}'
```
### 单图生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "hailuo-2.3-fast",
"prompt": "The person naturally raises their head and looks at the camera while face and clothing remain consistent.",
"image": "https://example.com/source.png",
"duration": 6,
"resolution": "768p",
"fast_pretreatment": true,
"watermark": false
}'
```
### 首尾帧生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "hailuo-02",
"prompt": "Transition naturally from day to night while the building structure remains stable and the motion stays smooth.",
"image": "https://example.com/first.png",
"last_image": "https://example.com/last.png",
"duration": 6,
"resolution": "1080p",
"prompt_optimizer": true,
"watermark": false
}'
```
## 响应示例
### 任务创建成功
请保存返回的 `id`，用于后续查询：
```json
{
"id": "task_xxxxxxxxxxxxx",
"object": "video",
"model": "hailuo-2.3",
"status": "queued",
"progress": 0,
"created_at": 1785772800
}
```
## 任务状态与结果
创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/models/video/overview#视频任务生命周期)。
## 计费说明
所选模型、`duration` 和 `resolution` 会影响计费；`1080p` 不支持 10 秒请求。当前价格和最终扣费以 UniAI 模型页与消费日志为准。
## 常见错误
以下请求会被拒绝：
- 模型不支持当前生成模式；
- `duration` 不是 `6` 或 `10`；
- `1080p` 请求了 10 秒视频；
- `hailuo-2.3-fast` 缺少 `image`；
- 单独传入 `last_image`，或对 `hailuo-02` 以外的模型传入 `last_image`；
- 图片 URL 无法由服务端公开访问；
- 请求音频、参考视频、多参考图、画幅比例控制或视频编辑能力。
传入 `watermark: false` 表示请求关闭 AIGC 水印。最终水印行为还可能受平台可用性与模型策略影响；如果完成结果仍出现非预期水印，请联系 UniAI 支持。
## 相关页面
- [视频生成概览](/models/video/overview)
- [模型列表](/models)
---
# Happy Horse
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/happy-horse
Source: .generated/cn/site-docs/models/video/happy-horse.md
Description: 通过 UniAI 使用统一的 Happy Horse 模型创建文生、图生、多参考图和视频编辑任务。
本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。
更新时间：2026-08-10
## 概览
UniAI 只对外提供一个稳定的 Happy Horse 公共模型：`happy-horse`。当前公共契约开放 Happy Horse 1.0 的能力，生成方式和输出档位都通过请求参数选择，不再拆分成多个模型名。
| 能力 | `operation` | 必需素材 | 分辨率 |
| --- | --- | --- | --- |
| 文生视频 | `text_to_video` | 无 | `720p`、`1080p` |
| 图生视频 | `image_to_video` | 恰好 1 张图片 | `720p`、`1080p` |
| 多参考图生视频 | `reference_to_video` | 1 至 9 张图片 | `720p`、`1080p` |
| 视频编辑 | `edit_video` | 恰好 1 个视频，可选 0 至 5 张图片 | `720p`、`1080p` |
历史档位模型名不再兼容。所有请求都必须使用 `model: "happy-horse"`，并同时传入 `operation` 和 `resolution`。
公共 HappyHorse 1.0 契约不开放 `480p`，使用该分辨率的请求会在任务创建前被拒绝。
## 适用场景
使用 `happy-horse` 可以：
- 根据文字提示词生成视频；
- 让一张源图片动起来并尽量保持原始构图；
- 通过多张参考图保持人物、商品或视觉风格一致；
- 编辑已有视频，并选择保留原音频或自动处理音频。
## 接口
新接入统一使用以下接口：
| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 获取完成后的视频 | `GET` | `/v1/videos/{task_id}/content` |
兼容的 `/v1/videos/generations` 和 `/v1/video/generations` 创建、查询路径仍可使用。新客户端建议统一使用 `/v1/videos`。
## 鉴权
```http
Authorization: Bearer sk-***
Content-Type: application/json
```
## 快速请求示例
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "happy-horse",
"operation": "text_to_video",
"resolution": "1080p",
"prompt": "A white horse runs across a misty grassland at sunrise, cinematic camera movement.",
"duration": 7,
"aspect_ratio": "16:9",
"seed": 12345,
"watermark": false
}'
```
创建响应会同时返回 `id` 和兼容字段 `task_id`。保存其中任意一个值，用于后续轮询。
```json
{
"id": "task_xxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxx",
"object": "video.generation.job",
"model": "happy-horse",
"status": "queued",
"progress": 0,
"created_at": 1785801600,
"video_url": null
}
```
## 任务状态与结果
创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/models/video/overview#视频任务生命周期)。
## 计费说明
- 生成任务按操作类型、选择的分辨率档位和生成时长计费。
- 视频编辑根据实际输入和输出视频时长进行最终结算，因此最终费用可能与提交时预估不同。
- `resolution` 选择的是公共服务档位，不保证每种画幅和源图片都对应同一个固定像素尺寸；对像素尺寸有严格要求时应检查成品媒体信息。
- 最终价格以 UniAI 当前价格页和任务结算记录为准。
## 常见错误
- 使用已删除的旧档位模型名，而不是 `happy-horse`。
- 缺少必填的 `operation` 或 `resolution`。
- 传入 `resolution: "480p"`；应使用 `720p` 或 `1080p`。
- 传入 `size`；Happy Horse 只使用 `resolution`，并会拒绝 `size`。
- `edit_video` 请求传入 `duration` 或 `aspect_ratio`。
- `image_to_video` 请求传入 `aspect_ratio`；图生视频画面比例跟随源图片。
- 媒体 URL 是私有地址、已过期或无法从公网访问。
## 相关页面
- [创建 Happy Horse 任务](/models/video/happy-horse/create-task)
- [视频生成概览](/models/video/overview)
---
# 创建 Happy Horse 视频任务
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/happy-horse/create-task
Source: .generated/cn/site-docs/models/video/happy-horse/create-task.md
Description: 使用统一的 happy-horse 模型创建文生、图生、多参考图和视频编辑任务。
本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。
更新时间：2026-08-10
## 概览
所有能力都使用唯一公共模型 `happy-horse`。通过 `operation` 选择文生、图生、多参考图或视频编辑，通过 `resolution` 选择输出档位。
不要使用已删除的旧档位模型名。旧名字与当前公共契约不兼容。
## 接口
```http
POST /v1/videos
```
兼容的创建路径：
```http
POST /v1/videos/generations
POST /v1/video/generations
```
新接入建议使用 `/v1/videos`。
## 鉴权
```http
Authorization: Bearer sk-***
Content-Type: application/json
```
## 能力矩阵
| `operation` | 提示词 | 图片输入 | 视频输入 | 分辨率 | `duration` | `aspect_ratio` |
| --- | --- | --- | --- | --- | --- | --- |
| `text_to_video` | 必填 | 不接受 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 可选，默认 `16:9` |
| `image_to_video` | 可选 | 恰好 1 张 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 不支持 |
| `reference_to_video` | 必填 | 1 至 9 张 | 不接受 | `720p`、`1080p` | 可选，默认 `5` | 可选，默认 `16:9` |
| `edit_video` | 必填 | 0 至 5 张 | 恰好 1 个 | `720p`、`1080p` | 不支持 | 不支持 |
## 请求体参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定为 `happy-horse`。 |
| `operation` | string | 是 | `text_to_video`、`image_to_video`、`reference_to_video` 或 `edit_video`。 |
| `resolution` | string | 是 | 所有操作均支持 `720p` 或 `1080p`。 |
| `prompt` | string | 条件必填 | 除 `image_to_video` 外均必填，最长 `2500` 字符。 |
| `duration` | integer | 否 | 仅生成使用，范围 `3` 至 `15`，默认 `5`；编辑请求不能传。 |
| `aspect_ratio` | string | 否 | 仅文生和多参考图生视频使用；图生和编辑请求不能传。 |
| `image` | string | 条件必填 | `image_to_video` 推荐使用的单张 HTTP(S) 图片字段。 |
| `images` | string[] | 条件必填 | `reference_to_video` 使用的 1 至 9 张 HTTP(S) 图片。 |
| `reference_image_urls` | string[] | 否 | 多参考图的别名；视频编辑也可使用，最多 5 张。 |
| `video` | string | 条件必填 | `edit_video` 使用的单个 HTTP(S) 源视频。 |
| `seed` | integer | 否 | 随机种子，范围 `0` 至 `2147483647`。 |
| `watermark` | boolean | 否 | 是否添加水印，默认 `false`。 |
| `audio_setting` | string | 否 | 仅编辑使用：`auto` 或 `origin`，默认 `auto`。 |
文生和多参考图生视频支持以下 `aspect_ratio`：
- `16:9`
- `9:16`
- `1:1`
- `4:3`
- `3:4`
- `4:5`
- `5:4`
- `9:21`
- `21:9`
`size` 和 `enable_safety_checker` 不属于 Happy Horse 公共参数，传入会被拒绝。
公共 HappyHorse 1.0 契约不开放 `480p`。把 `resolution` 设为 `480p` 的请求会在
任务创建前被拒绝。
## 输入规则
| 模式 | 可用素材字段 |
| --- | --- |
| 文生视频 | 不传图片或视频字段 |
| 图生视频 | 使用 `image`，或通过受支持的图片别名传入恰好 1 张图片 |
| 多参考图生视频 | 使用 `images` 或 `reference_image_urls`，传入 1 至 9 个 URL |
| 视频编辑 | 使用 `video`，并可选传入最多 5 个 `reference_image_urls` |
所有媒体输入都必须是完整、可公开访问的 HTTP 或 HTTPS URL。当前模型契约不接受文件上传、裸 Base64 或 Data URL。
## 请求示例
### 文生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "happy-horse",
"operation": "text_to_video",
"resolution": "1080p",
"prompt": "A white horse runs across a misty grassland at sunrise, realistic movement and soft rim light.",
"duration": 7,
"aspect_ratio": "21:9",
"seed": 12345,
"watermark": false
}'
```
### 图生视频
输出构图跟随源图片，因此不要传 `aspect_ratio`。
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "happy-horse",
"operation": "image_to_video",
"resolution": "720p",
"image": "https://example.com/source-frame.png",
"prompt": "The subject walks forward naturally while the camera slowly pushes in.",
"duration": 5,
"seed": 67890,
"watermark": false
}'
```
`image_to_video` 可以省略提示词。
### 多参考图生视频
提示词可以使用 `character1` 至 `character9`，按数组顺序指代参考图。
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "happy-horse",
"operation": "reference_to_video",
"resolution": "720p",
"prompt": "character1 drives character2 across the lunar surface while both identities remain consistent.",
"reference_image_urls": [
"https://example.com/character.png",
"https://example.com/vehicle.png"
],
"duration": 8,
"aspect_ratio": "16:9",
"seed": 24680,
"watermark": false
}'
```
### 视频编辑
编辑时长跟随源视频，不能传 `duration` 或 `aspect_ratio`。
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "happy-horse",
"operation": "edit_video",
"resolution": "1080p",
"prompt": "Replace the jacket with the referenced red jacket while preserving identity, motion, camera movement, and background.",
"video": "https://example.com/source-video.mp4",
"reference_image_urls": [
"https://example.com/red-jacket.png"
],
"audio_setting": "origin",
"seed": 13579,
"watermark": false
}'
```
使用 `audio_setting: "origin"` 保留原音频；使用 `auto` 让服务自动决定音频处理方式。
## `extra_body` 兼容
推荐把公共参数直接放在请求体顶层。兼容客户端也可以把 `operation`、`resolution`、`seed`、`watermark` 和 `audio_setting` 放入 `extra_body`。不要在顶层和 `extra_body` 中传入互相冲突的值。
```json
{
"model": "happy-horse",
"prompt": "Turn the room into a warm wooden studio.",
"video": "https://example.com/source-video.mp4",
"extra_body": {
"operation": "edit_video",
"resolution": "720p",
"audio_setting": "auto",
"watermark": false
}
}
```
## 响应示例
### 任务已受理
```json
{
"id": "task_xxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxx",
"object": "video.generation.job",
"model": "happy-horse",
"status": "queued",
"progress": 0,
"created_at": 1785801600,
"video_url": null
}
```
## 任务状态与结果
创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/models/video/overview#视频任务生命周期)。
视频编辑等最终结算操作应在任务完成后再次读取 `billing_contract`。
## 素材限制
### 图生视频源图片
- 格式：JPEG、JPG、PNG、BMP 或 WebP。
- 最小尺寸：`300px`。
- 画面比例：`1:2.5` 至 `2.5:1`。
- 最大文件：`10MB`。
### 多参考图
- 格式：JPEG、JPG、PNG 或 WebP。
- 数量：1 至 9 张。
- 最短边至少 `400px`，建议 720p 以上。
- 每张最大 `10MB`。
### 视频编辑源素材
- 格式：MP4 或 MOV，推荐 H.264。
- 输入时长：3 至 60 秒；编辑服务最多处理 15 秒。
- 尺寸：长边不超过 `2160px`，短边不小于 `320px`。
- 画面比例：`1:2.5` 至 `2.5:1`。
- 帧率：大于 `8fps`。
- 最大文件：`100MB`。
编辑参考图支持 JPEG、JPG、PNG 或 WebP，尺寸至少 `300px`，每张最大 `10MB`。
## 计费说明
- 文生、图生和多参考图生成按请求的输出时长与分辨率档位结算。
- 视频编辑根据实际输入和输出视频时长进行最终结算，最终费用可能与提交时预估不同。
- `resolution` 是服务档位，不保证每种画幅或源图片都对应一个固定像素尺寸。
- 最终金额以 UniAI 当前价格页和任务结算记录为准。
## 常见错误
| 错误 | 原因 | 处理方式 |
| --- | --- | --- |
| 模型名无效 | 使用了已删除的旧档位模型名 | 把 `model` 改为 `happy-horse` |
| 缺少参数 | 未传 `operation` 或 `resolution` | 显式传入两个参数 |
| 参数不支持 | 传入了 `size` 或 `enable_safety_checker` | 删除不支持的字段 |
| 素材数量不正确 | 当前操作收到错误数量的图片或视频 | 按能力矩阵调整素材 |
| 分辨率不正确 | `resolution` 为 `480p` 或其他不支持的值 | 使用 `720p` 或 `1080p` |
| 编辑参数不正确 | 编辑请求包含 `duration` 或 `aspect_ratio` | 删除不支持字段 |
| 素材下载失败 | URL 私有、过期、重定向异常或无法访问 | 使用稳定的公开 HTTPS URL |
## 相关页面
- [Happy Horse 视频生成](/models/video/happy-horse)
- [视频生成概览](/models/video/overview)
---
# Kling
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/kling
Source: .generated/cn/site-docs/models/video/kling.md
Description: 通过 UniAI 创建可灵文生、图生、参考、动作控制和视频编辑任务。
本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。
## 概览
可灵视频能力统一使用稳定的版本级模型名。通过请求体顶层的 `resolution` 选择清晰度，通过 `operation` 选择生成方式；不要把清晰度、声音或上游路由写进模型名。
| 模型 | 视频能力 | 清晰度 |
| --- | --- | --- |
| `kling-v3-turbo` | 文生视频、单首帧图生视频 | `720p`、`1080p` |
| `kling-v3` | 文生视频、图生视频、首尾帧、动作控制、数字人 | `std`、`pro` |
| `kling-v3-omni` | 文生视频、图生视频、首尾帧、多模态参考、视频编辑 | `std`、`pro` |
| `kling-o1` | 文生视频、图生视频、首尾帧、多模态参考、视频编辑 | `std`、`pro` |
模型是否可用取决于模型广场、API Key 的模型权限和当前启用的路由。历史清晰度、声音、静音和数字人档位模型名不再接受，也不会自动转换。
## 适用场景
- 需要 `720p` 或 `1080p` 的快速文生、单图视频时使用 `kling-v3-turbo`。
- 需要首尾帧、动作控制或数字人时使用 `kling-v3`。
- 需要最多四张参考图的多模态参考或视频编辑时使用 `kling-v3-omni`。
- 需要相同的参考和编辑请求结构、且生成时长为 `3` 到 `10` 秒时使用 `kling-o1`。
## 接口
| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` |
`POST /v1/videos/generations` 和 `POST /v1/video/generations` 仍是兼容创建路径。新接入统一使用 `POST /v1/videos`。
## 鉴权
```http
Authorization: Bearer sk-***
Content-Type: application/json
```
## 清晰度与声音
在请求体顶层传入 `resolution`，不要使用 `size` 代替。未传时，Turbo 默认 `720p`，其他可灵视频模型默认 `std`。需要明确输出和计费记录时，建议显式传入。
可灵视频请求不接受 `sound` 开关。需要对白、音乐、环境声或静音效果时，直接写入 `prompt`。数字人任务使用的 `audio_url` 和 `voice_id` 是口型驱动输入，不属于声音开关。
## 生成方式
| `operation` | 支持模型 | 必要输入 |
| --- | --- | --- |
| `text_to_video` | Turbo、V3、Omni、O1 | `prompt` |
| `image_to_video` | Turbo、V3、Omni、O1 | `prompt` 和 `image` |
| `first_last_frame` | V3、Omni、O1 | `prompt`、`image` 和 `last_image` |
| `reference_to_video` | Omni、O1 | `prompt` 和图片或视频参考 |
| `edit_video` | Omni、O1 | `prompt` 和 `video_url`；参考图可选 |
| `motion_control` | V3 | `prompt`、`image`、`video` 和 `character_orientation` |
| `avatar` | V3 | 参见[数字人口播](/models/avatar/digital-human) |
时长规则：
- Turbo 和 V3 的生成 operation 支持 `3` 到 `15` 秒。
- Omni 的文生、图生和首尾帧支持 `3` 到 `15` 秒；`reference_to_video` 支持 `3` 到 `10` 秒。
- O1 的生成 operation 支持 `3` 到 `10` 秒。
- 动作控制、数字人和视频编辑按对应 operation 的结果时长规则处理；除非该 operation 明确支持，否则不要传 `duration`。
- Turbo 文生视频接受 `aspect_ratio`；Turbo 图生视频不接受。
## 请求参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 稳定的可灵视频模型 ID。 |
| `prompt` | string | 是 | UniAI 视频任务接口要求提供的提示词。 |
| `operation` | string | 建议显式传入 | 上表中的生成方式。 |
| `resolution` | string | 否 | 模型对应的清晰度；默认值见上文。 |
| `duration` | integer | 条件必填 | 支持时长的 operation 的输出秒数。 |
| `aspect_ratio` | string | 条件必填 | `16:9`、`9:16` 或 `1:1`。 |
| `image` | string | 条件必填 | 图生视频图片或首帧的公开 HTTP(S) URL。 |
| `last_image` | string | 条件必填 | 尾帧图片 URL，需与 `image` 同时使用。 |
| `reference_image_urls` | string[] | 否 | 多模态参考或编辑使用的参考图 URL，最多四张。 |
| `video_url` | string | 条件必填 | 多模态参考或编辑使用的基础视频 URL。 |
| `video` | string | 条件必填 | `motion_control` 使用的动作参考视频 URL。 |
| `keep_original_sound` | string | 否 | 多模态参考和视频编辑可使用 `yes` 或 `no`。 |
| `character_orientation` | string | 条件必填 | `motion_control` 使用 `image` 或 `video`。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |
## 请求示例
### Turbo 文生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-turbo",
"operation": "text_to_video",
"prompt": "一架纸飞机穿过清晨的城市街道，电影感运镜，轻柔环境声。",
"duration": 3,
"resolution": "720p",
"aspect_ratio": "16:9",
"watermark": false
}'
```
### Turbo 图生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-turbo",
"operation": "image_to_video",
"prompt": "纸飞机平稳向前滑翔，镜头缓慢跟随。",
"image": "https://example.com/plane.png",
"duration": 5,
"resolution": "1080p"
}'
```
Turbo 图生视频不要传 `aspect_ratio`。
### V3 首尾帧
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3",
"operation": "first_last_frame",
"prompt": "人物自然转身并看向镜头，过渡连续平滑。",
"image": "https://example.com/first.png",
"last_image": "https://example.com/last.png",
"duration": 5,
"resolution": "pro"
}'
```
### V3 动作控制
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3",
"operation": "motion_control",
"prompt": "保持人物身份和服装，复现参考视频中的动作。",
"image": "https://example.com/person.png",
"video": "https://example.com/motion.mp4",
"resolution": "pro",
"character_orientation": "image"
}'
```
### Omni 多模态参考
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-omni",
"operation": "reference_to_video",
"prompt": "保持人物身份和服装，把参考动作应用到基础视频。",
"reference_image_urls": [
"https://example.com/person.png",
"https://example.com/clothes.png"
],
"video_url": "https://example.com/base.mp4",
"duration": 8,
"resolution": "pro",
"keep_original_sound": "yes"
}'
```
### Omni 视频编辑
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-omni",
"operation": "edit_video",
"prompt": "保持人物动作不变，把背景替换为夜晚城市街道。",
"video_url": "https://example.com/source.mp4",
"reference_image_urls": [
"https://example.com/city-style.png"
],
"resolution": "pro",
"keep_original_sound": "yes"
}'
```
`kling-o1` 使用相同的文生、图生、首尾帧、参考和编辑请求结构，其生成时长范围为 `3` 到 `10` 秒。
## 响应示例
```json
{
"id": "task_xxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxx",
"object": "video.generation.job",
"model": "kling-v3",
"status": "queued",
"progress": 0
}
```
## 任务状态与结果
保存 `id` 或 `task_id`，然后按照[视频生成概览](/models/video/overview#视频任务生命周期)中的公共规则，每 3 到 10 秒轮询一次，并处理终态、结果字段、错误和带鉴权下载。
## 计费说明
视频通常结合公共模型、`operation`、`resolution` 和实际输出秒数计费。任务提交时可能预扣，最终以任务结算记录和模型广场当前价格为准。
## 常见错误
- 使用历史清晰度、声音、静音或数字人档位模型名，而不是上面的版本级模型。
- 使用 `size` 代替 `resolution`，或给视频请求传入 `sound`。
- Turbo 图生视频传入 `aspect_ratio`。
- 请求时长超出所选模型和 operation 的范围。
- 混用 `image`、`reference_image_urls` 和视频输入，重复提交同一个参考素材。
- 图片或视频 URL 无法由服务端公开访问。
- 一次轮询超时后重新提交付费任务，而不是继续查询原 `task_id`。
公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。
## 相关页面
- [Kling 图片](/models/image/kling)
- [数字人口播](/models/avatar/digital-human)
- [视频生成概览](/models/video/overview)
---
# MiniMax H3 / H3 Max
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/minimax-h3
Source: .generated/cn/site-docs/models/video/minimax-h3.md
Description: 使用 MiniMax 原生 JSON 接口创建 H3 与 H3 Max 视频任务，并查询任务、输入素材、处理 Context、再生成和管理任务。
使用 MiniMax 原生视频接口和 UniAI API Key 调用。
- 服务地址：`https://api.uniai.tv`
- 模型：`MiniMax-H3`、`MiniMax-H3-Max`
- Content-Type：`application/json`
## 接口
| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/v2/video_generation` | 创建视频 |
| POST | `/v2/h3_context_ir` | 创建 Context 提示词 |
| POST | `/v2/video_regeneration` | 将 H3 视频再生成至 2K |
| GET | `/v2/query/video_generation/{task_id}` | 查询任务 |
| GET | `/v2/query/video_generation` | 查询任务列表 |
| DELETE | `/v2/video_generation/{task_id}` | 取消或删除任务 |
## 创建视频
帧输入、素材参考、H3 Max、Context 和再生成请求见[调用示例](/models/video/minimax-h3/examples)。
```bash
curl -X POST "https://api.uniai.tv/v2/video_generation" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "A paper boat crosses a quiet pond in warm morning light."
}
],
"duration": 5,
"resolution": "768P",
"ratio": "16:9"
}'
```
响应：
```json
{
"task_id": "task_YOUR_VIDEO"
}
```
## 参数
| 字段 | 必填 | 可用值 |
| --- | --- | --- |
| `model` | 是 | `MiniMax-H3` 或 `MiniMax-H3-Max` |
| `content` | 是 | 一条 `text`，可附加媒体项 |
| `duration` | 是 | H3：整数 4–15；H3 Max：整数 5–15 |
| `resolution` | 否 | H3：`768P` 或 `2K`；H3 Max：`480P` 或 `768P`。默认 `768P` |
| `ratio` | 仅文生必填 | 纯文本请求必须使用具体比例；首尾帧使用 `adaptive`；参考素材默认为 `adaptive`。可选：`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive`。 |
| `aigc_watermark` | 否 | 布尔值，默认 `false` |
| `extra.prompt_expansion_mode` | 仅 H3 Max | `disabled`、`balanced`（默认）或 `quality` |
| `callback_url` | 否 | 公网 HTTP(S) 地址。收到验证请求后 3 秒内原样返回 `challenge`；也可使用查询接口轮询。 |
## 输入图片、视频和音频
媒体放在 `content` 中。每次请求必须有一条 text，最多 7000 个字符。
| 类型 | role |
| --- | --- |
| `image_url` | `first_frame`、`last_frame` 或 `reference_image` |
| `video_url` | `reference_video`；仅再生成时使用 `base_video` |
| `audio_url` | `reference_audio` |
媒体字段使用 `{"url":"https://..."}`。图片未填写 role 时默认为 `first_frame`。首尾帧模式不能与参考素材混用。
首帧示例：
```json
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "A paper boat crosses a quiet pond in warm morning light."
},
{
"type": "image_url",
"image_url": {
"url": "https://YOUR_PUBLIC_URL/first.png"
},
"role": "first_frame"
}
],
"duration": 5,
"resolution": "768P"
}
```
限制：最多 9 张图片、3 段视频、3 段音频，总计 12 个媒体项。图片支持 JPEG、PNG、WEBP、HEIC、HEIF；每张不超过 30 MB，宽高为 256–5,760 px。视频使用 MP4 或 MOV，每段不超过 50 MB，帧率为 23.976–60 fps；每段 2–15 秒，总长不超过 15 秒。音频使用 WAV 或 MP3，每段不超过 15 MB；每段 2–15 秒，总长不超过 15 秒。使用可公开访问的 URL 或对应 MIME 类型的 data URI。此接口不提供素材上传。
## 查询任务
使用创建响应中的 task ID 轮询：
```bash
curl "https://api.uniai.tv/v2/query/video_generation/task_YOUR_VIDEO" \
-H "Authorization: Bearer $UNIAI_API_KEY"
```
视频任务响应：
```json
{
"task": {
"id": "task_YOUR_VIDEO",
"model": "MiniMax-H3",
"status": "succeeded",
"task_type": "generation",
"modality": "video",
"content": {
"url": "https://YOUR_RESULT_URL/video.mp4"
}
}
}
```
状态：`queued`、`running`、`succeeded`、`failed`、`cancelled`。完成后从 `task.content.url` 下载视频。
## Context
Context 返回增强后的提示词，不会生成视频。使用 H3，省略 `resolution`。
```bash
curl -X POST "https://api.uniai.tv/v2/h3_context_ir" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "A paper boat crosses a quiet pond in warm morning light."
}
],
"duration": 5,
"ratio": "16:9"
}'
```
使用相同的任务查询接口；结果提示词位于 `task.content.prompt`。
## 再生成 2K 视频
仅 H3 支持再生成。使用自己账号在最近七天内创建的已完成 H3 768P 任务：
```bash
curl -X POST "https://api.uniai.tv/v2/video_regeneration" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3",
"source_task_id": "task_YOUR_COMPLETED_H3_768P",
"resolution": "2K"
}'
```
也可以在 `content` 中传入唯一 `base_video` 项，并附上原始提示词和全部原始输入。不要传 `duration` 或 `ratio`。
## 列表、取消和删除
```bash
curl "https://api.uniai.tv/v2/query/video_generation?page_num=1&page_size=10" \
-H "Authorization: Bearer $UNIAI_API_KEY"
```
列表响应包含 `items` 和 `total`。可用 `page_num`、`page_size`、`filter.model`、`filter.task_type`、`filter.task_ids` 和 `filter.status` 筛选。原生任务保留七天。
```bash
curl -X DELETE "https://api.uniai.tv/v2/video_generation/task_YOUR_VIDEO" \
-H "Authorization: Bearer $UNIAI_API_KEY"
```
DELETE 会取消排队中的任务，或删除成功／失败的任务；不能取消运行中的任务。
## 错误
HTTP 错误响应格式：
```json
{
"type": "error",
"error": {
"type": "bad_request_error",
"message": "Invalid request parameters.",
"http_code": "400"
},
"request_id": "opaque_request_id"
}
```
任务失败时查询仍返回任务对象，`task.status` 为 `failed`，错误信息在 `task.error` 中。创建请求超时后，先查询任务，不要直接重复提交。
---
# MiniMax H3 / H3 Max 调用示例
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/minimax-h3/examples
Source: .generated/cn/site-docs/models/video/minimax-h3/examples.md
Description: MiniMax H3、H3 Max 视频生成、媒体参考、Context 和 2K 再生成的原生 API 请求示例。
将 `$UNIAI_API_KEY` 和素材地址替换为你自己的值。每次发送一个请求。
## 文生视频
```bash
curl -X POST "https://api.uniai.tv/v2/video_generation" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "A paper boat crosses a quiet pond in warm morning light."
}
],
"duration": 5,
"resolution": "2K",
"ratio": "16:9"
}'
```
## 首尾帧
```bash
curl -X POST "https://api.uniai.tv/v2/video_generation" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "The camera moves from the first frame to the last."
},
{
"type": "image_url",
"image_url": {
"url": "https://YOUR_PUBLIC_URL/first.png"
},
"role": "first_frame"
},
{
"type": "image_url",
"image_url": {
"url": "https://YOUR_PUBLIC_URL/last.png"
},
"role": "last_frame"
}
],
"duration": 5,
"resolution": "768P"
}'
```
## 图片、视频和音频参考
```bash
curl -X POST "https://api.uniai.tv/v2/video_generation" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "A person speaks while walking through the city."
},
{
"type": "image_url",
"image_url": {
"url": "https://YOUR_PUBLIC_URL/person.png"
},
"role": "reference_image"
},
{
"type": "video_url",
"video_url": {
"url": "https://YOUR_PUBLIC_URL/walking.mp4"
},
"role": "reference_video"
},
{
"type": "audio_url",
"audio_url": {
"url": "https://YOUR_PUBLIC_URL/voice.mp3"
},
"role": "reference_audio"
}
],
"duration": 5,
"resolution": "768P",
"ratio": "adaptive"
}'
```
## H3 Max
```bash
curl -X POST "https://api.uniai.tv/v2/video_generation" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3-Max",
"content": [
{
"type": "text",
"text": "A paper boat crosses a quiet pond in warm morning light."
}
],
"duration": 5,
"resolution": "768P",
"ratio": "16:9",
"extra": {
"prompt_expansion_mode": "balanced"
}
}'
```
## Context
返回处理后的提示词，不会创建视频。省略 `resolution`。
```bash
curl -X POST "https://api.uniai.tv/v2/h3_context_ir" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "A paper boat crosses a quiet pond in warm morning light."
}
],
"duration": 5,
"ratio": "16:9"
}'
```
## 再生成 2K
使用自己账号最近七天内创建的已完成 H3 768P 任务。
```bash
curl -X POST "https://api.uniai.tv/v2/video_regeneration" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3",
"source_task_id": "task_YOUR_COMPLETED_H3_768P",
"resolution": "2K"
}'
```
---
# 视频生成概览
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/overview
Source: .generated/cn/site-docs/models/video/overview.md
Description: 使用统一任务生命周期创建、查询并获取 UniAI 视频生成结果。
UniAI 视频模型默认共用一套异步任务生命周期。模型 ID、输入字段和能力限制以各模型页面为准；任务轮询、状态处理、错误和结果获取统一以本页为准。
## 模型
- [Hailuo](/models/video/hailuo)
- [Happy Horse](/models/video/happy-horse)
- [Kling](/models/video/kling)
- [MiniMax H3 / H3 Max](/models/video/minimax-h3)
- [Seedance 2.0](/models/video/seedance-2-0)
- [Seedance 2.5](/models/video/seedance-2-5)
- [Vidu Q3](/models/video/vidu)
- [完整模型目录](/models)
## 默认接口
`{BASE_URL}` 为 `https://api.uniai.tv`。
| 操作 | 方法 | 接口 |
| --- | --- | --- |
| 创建任务 | `POST` | `/v1/videos` |
| 查询状态与结果 | `GET` | `/v1/videos/{task_id}` |
| 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` |
每次请求都要携带 `Authorization: Bearer sk-***`。部分模型页面会注明兼容创建路径或特定协议例外；模型 ID 和请求体仍以对应模型页面为准。
## 视频任务生命周期
### 1. 保存任务 ID
创建成功后会返回公开 `id`。部分响应还会在 `task_id` 中返回同一个值用于兼容。离开创建流程前应保存其中任意一个。
```json
{
"id": "task_xxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxx",
"object": "video.generation.job",
"model": "model-name",
"status": "queued",
"progress": 0,
"created_at": 1785801600
}
```
### 2. 轮询任务
每 3 到 10 秒查询一次任务：
```bash
curl "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx" \
-H "Authorization: Bearer sk-***"
```
仅当 `status` 变为 `completed` 或 `failed` 时停止轮询。任务仍为 `queued` 或 `in_progress` 时，不要重复创建同一任务。
| 状态 | 终态 | 含义 |
| --- | --- | --- |
| `queued` | 否 | 任务已受理，正在等待处理。 |
| `in_progress` | 否 | 正在生成视频或处理结果。 |
| `completed` | 是 | 最终结果已就绪。 |
| `failed` | 是 | 任务未生成结果；检查 `error`。 |
### 3. 读取结果
任务完成后，可从 `video_url`、`result.video_url` 或 `result.outputs[0]` 读取公开结果。这几个字段可能指向同一个视频。
```json
{
"id": "task_xxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxx",
"object": "video.generation.job",
"model": "model-name",
"status": "completed",
"progress": 100,
"video_url": "https://example.com/generated-video.mp4",
"result": {
"video_url": "https://example.com/generated-video.mp4",
"outputs": [
"https://example.com/generated-video.mp4"
]
},
"error": null
}
```
完成后优先使用返回的 `video_url` 下载视频，也可使用带鉴权的内容接口：
```bash
curl -L "{BASE_URL}/v1/videos/task_xxxxxxxxxxxxx/content" \
-H "Authorization: Bearer sk-***" \
-o output.mp4
```
任务完成前不要调用内容接口。生成媒体应及时下载，不要把结果 URL 当作永久存储地址。
### 4. 处理失败
```json
{
"id": "task_xxxxxxxxxxxxx",
"object": "video.generation.job",
"model": "model-name",
"status": "failed",
"progress": 100,
"result": null,
"error": {
"code": "task_failed",
"message": "Video generation failed"
}
}
```
参数错误应先修正输入再创建新任务。临时服务错误可使用退避策略重试，但原任务仍在运行时不要反复提交同一请求。
Seedance 2.5 创建请求失败、客户端超时或结果不确定时，不得自动重试。继续查询已有任务 ID，或先核对原请求结果再重新提交。Draft 转成片也遵守此规则，见[模型专属流程](/models/video/seedance-2-5#draft-to-final)。
## 公共响应字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 用于轮询的公开任务 ID。 |
| `task_id` | string | 存在时为 `id` 的兼容别名。 |
| `object` | string | 任务对象类型，通常为 `video.generation.job`。 |
| `model` | string | 创建任务时使用的公开模型 ID。 |
| `status` | string | `queued`、`in_progress`、`completed` 或 `failed`。 |
| `progress` | integer | 可用时为 `0` 到 `100`；不能代替 `status` 判断终态。 |
| `video_url` | string 或 null | 任务完成后的公开结果 URL。 |
| `result` | object 或 null | 完成后的输出详情，包括 `video_url` 或 `outputs`。 |
| `error` | object 或 null | 失败任务的公开 `code` 和 `message`。 |
| `created_at` | integer | 可用时为 Unix 创建时间戳。 |
| `completed_at` | integer | 可用时为 Unix 完成时间戳。 |
## 模型例外
MiniMax H3 任务详情使用 `task` 对象，状态为 `queued`、`running`、`succeeded`、`failed` 或 `cancelled`。请求与响应示例见 [H3 原生 API](/models/video/minimax-h3)。
---
# Seedance 2.0
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/seedance-2-0
Source: .generated/cn/site-docs/models/video/seedance-2-0.md
Description: 通过 UniAI 视频 API 调用 Seedance 2.0 模型生成视频。
Seedance 2.0 支持文生视频、图生视频、首尾帧、多模态参考、视频编辑和视频延长。新接入请从 [Seedance 2.0 系列调用指南](/models/video/seedance-2-0/series-guide) 开始；复用图片、视频或音频的创建与使用方法见 [Seedance 2.0 素材库](/models/video/seedance-2-0/material-library)。
## 支持模型
| 模型 | 支持分辨率 | 适用场景 |
| --- | --- | --- |
| `seedance2.0` | `480p`、`720p`、`1080p`、`4k` | 综合质量优先，支持完整能力。 |
| `seedance2.0-fast` | `480p`、`720p` | 生成速度优先。 |
| `seedance2.0-mini` | `480p`、`720p` | 轻量、速度优先。 |
## Endpoint
```http
POST /v1/videos
GET /v1/videos/{task_id}
GET /v1/videos/{task_id}/content
```
旧客户端仍可继续使用 `/v1/videos/generations` 和 `/v1/video/generations` 创建接口。
## Authentication
```http
Authorization: Bearer sk-***
Content-Type: application/json
```
## 请求参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `seedance2.0`、`seedance2.0-fast` 或 `seedance2.0-mini`。 |
| `resolution` | string | 是 | 所选模型支持的分辨率。 |
| `prompt` | string | 条件必填 | 视频提示词；使用 `content[]` 时改为 `type=text` 项。 |
| `duration` | integer/string | 是 | 输出时长，支持 `4` 到 `15` 秒。 |
| `aspect_ratio` | string | 否 | 输出宽高比；兼容别名为 `ratio`。 |
| `content` | object[] | 否 | 带明确角色的文本、图片、视频和音频多模态输入。 |
| `operation` | string | 条件必填 | `reference_to_video`、`edit_video` 或 `extend_video`。 |
| `generate_audio` | boolean | 否 | 是否生成带音频的视频。 |
| `return_last_frame` | boolean | 否 | 是否返回生成视频的尾帧。 |
## 请求示例
```bash
curl -X POST "https://api.uniai.tv/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0",
"prompt": "A clean commercial product video with slow camera movement, soft reflections, and realistic lighting.",
"resolution": "720p",
"duration": 8,
"aspect_ratio": "16:9",
"generate_audio": false,
"seed": 42,
"watermark": false
}'
```
## 多参考图示例
```bash
curl -X POST "https://api.uniai.tv/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0-fast",
"resolution": "720p",
"duration": 6,
"aspect_ratio": "9:16",
"operation": "reference_to_video",
"content": [
{
"type": "text",
"text": "制作一段快速时尚 Lookbook 视频，并保持产品外观一致。"
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/model.png"},
"role": "reference_image"
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/outfit.png"},
"role": "reference_image"
}
],
"generate_audio": true
}'
```
## 任务状态与结果
创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/models/video/overview#视频任务生命周期)。
## 常见错误
- 新接入仍使用旧创建任务接口。
- 参考图超过 `9` 张。
- 参考视频超过 `3` 个，或总时长超过 `15` 秒。
- `duration` 不在 `4` 到 `15` 范围内。
- 新输入格式和兼容层 `operation` 混用导致路由不明确。
## 相关页面
- [Seedance 2.0 系列调用指南](/models/video/seedance-2-0/series-guide)
- [Seedance 2.0 素材库](/models/video/seedance-2-0/material-library)
- [视频生成概览](/models/video/overview)
---
# Seedance 2.0 素材库
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/seedance-2-0/material-library
Source: .generated/cn/site-docs/models/video/seedance-2-0/material-library.md
Description: 使用 UniAI API Key 创建素材，等待可用后将返回的 URI 用于 Seedance 视频生成，并查询列表或删除素材。
创建可复用的图片、视频或音频素材，再将返回的 `uri` 用于 Seedance 视频请求。
所有请求使用 `https://api.uniai.tv`，通过 `Authorization: Bearer $UNIAI_API_KEY` 鉴权。
## 1. 创建素材
`POST /v1/materials` 需携带 `Idempotency-Key` 请求头，正文使用 JSON：
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 是 | 公网可访问的 HTTP(S) 媒体 URL，最长 4,096 个字符。 |
| `type` | string | 是 | `image`、`video` 或 `audio`，须与素材类型一致。 |
| `name` | string | 否 | 素材名称，最多 64 个字符。 |
```bash
curl "https://api.uniai.tv/v1/materials" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: product-reference-001" \
-d '{
"url": "https://cdn.example.com/product.png",
"type": "image",
"name": "Product reference"
}'
```
HTTP `202` 响应：
```json
{
"id": "mat_EXAMPLE",
"object": "material",
"name": "Product reference",
"type": "image",
"status": "processing",
"uri": null,
"preview_url": null,
"created_at": "2026-10-29T10:00:00Z",
"available_at": null,
"expires_at": null
}
```
- 幂等键使用 1–200 个不含空格的可见 ASCII 字符。同一请求使用原键重试会返回同一素材；参数不同则返回 HTTP `409`（`material_idempotency_conflict`）。请求超时后使用原键重试。
- URL 在处理期间须保持公网可访问，不依赖登录、Cookie 或自定义请求头。当前网页“创建素材”填写来源 URL；此 API 接收 JSON URL，不接收 multipart 文件或 Base64。本地文件请先准备为可公开访问的 HTTP(S) URL。
真人图片、视频也使用相同创建请求；如接口返回额外验证提示，以接口提示为准。
## 2. 等待素材可用
使用创建响应中的 `id`，每 3–5 秒查询一次，直到 `status` 为 `available`：
```bash
curl "https://api.uniai.tv/v1/materials/mat_EXAMPLE" \
-H "Authorization: Bearer $UNIAI_API_KEY"
```
响应示例，时间仅作示意：
```json
{
"id": "mat_EXAMPLE",
"object": "material",
"name": "Product reference",
"type": "image",
"status": "available",
"uri": "asset://asset-EXAMPLE",
"preview_url": "https://cdn.example.com/preview.png",
"created_at": "2026-10-29T10:00:00Z",
"available_at": "2026-10-29T10:01:00Z",
"expires_at": "2026-10-30T12:00:00Z"
}
```
直接使用接口返回的 `uri`。`mat_*` 是查询和删除素材的 ID，不要用它自行拼接 `asset://` URI。素材有效期以 `expires_at` 为准，请在到期前使用。
| 状态 | 处理方式 |
| --- | --- |
| `creating`、`processing` | 继续查询。 |
| `available` | 可以使用返回的 `uri`。 |
| `failed` | 查看 `error.code` 和 `error.message`；需要重新创建时使用新的幂等键。 |
| `delete_pending`、`deleted` | 停止使用素材。 |
## 3. 使用 URI 生成视频
将下方 `asset://asset-EXAMPLE` 替换为可用图片素材返回的 `uri`：
```bash
curl "https://api.uniai.tv/v1/videos" \
-H "Authorization: Bearer $UNIAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0-fast",
"resolution": "480p",
"duration": 4,
"aspect_ratio": "16:9",
"generate_audio": false,
"content": [
{
"type": "text",
"text": "Keep the product appearance consistent as the camera slowly moves around it."
},
{
"type": "image_url",
"image_url": {"url": "asset://asset-EXAMPLE"},
"role": "reference_image"
}
]
}'
```
URI 放在 `image_url.url` 等结构化媒体字段中，不要写进提示词。视频和音频素材分别使用对应的 `video_url`、`audio_url` 字段。素材须属于同一 UniAI 用户，状态可用且未过期。
创建后使用返回的视频任务 ID [查询视频并获取结果](/models/video/overview#视频任务生命周期)。
## 素材列表
```bash
curl "https://api.uniai.tv/v1/materials?type=image&status=available&limit=20" \
-H "Authorization: Bearer $UNIAI_API_KEY"
```
响应包含 `data`、`has_more` 和 `next_cursor`。可用 `type`、`status` 筛选；`limit` 为 1–100，默认 `50`。下一页将返回的 `next_cursor` 原样放入 `after`。已过期或已删除素材不出现在列表中。
## 删除素材
```bash
curl -X DELETE "https://api.uniai.tv/v1/materials/mat_EXAMPLE" \
-H "Authorization: Bearer $UNIAI_API_KEY"
```
HTTP `200` 且 `status: "deleted"` 表示删除完成；HTTP `202` 且 `status: "delete_pending"` 表示仍在处理中。可以重复 DELETE。删除完成后素材从列表消失，详情接口返回 `404 material_not_found`。
## 请求错误
| 错误码 | 检查方式 |
| --- | --- |
| `invalid_idempotency_key` | 创建时携带有效的 `Idempotency-Key`。 |
| `invalid_material_request` | 检查 URL、素材类型及名称长度。 |
| `material_idempotency_conflict` | 使用原请求和原键重试，或为不同素材换用新键。 |
| `material_not_found` | 检查 ID 和当前用户；素材可能已删除或过期。 |
| `material_not_available` | 等待 `available`，并检查 `expires_at`。 |
| `material_not_managed` | 从素材响应复制 `uri`，不要自行拼接。 |
视频生成参数见 [Seedance 2.0 系列指南](/models/video/seedance-2-0/series-guide)。
---
# Seedance 2.0 系列调用指南
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/seedance-2-0/series-guide
Source: .generated/cn/site-docs/models/video/seedance-2-0/series-guide.md
Description: 通过 UniAI 调用 Seedance 2.0、Seedance 2.0 Fast 和 Seedance 2.0 Mini，涵盖多模态输入、视频编辑、延长和任务查询。
更新时间：2026-07-29
本文介绍如何通过 UniAI 调用 Seedance 2.0 系列。新接入推荐使用三个稳定公共模型名，通过请求参数选择分辨率和生成能力。
## 1. 模型选择
| 公共模型 | 支持分辨率 | 适用场景 |
| --- | --- | --- |
| `seedance2.0` | `480p`、`720p`、`1080p`、`4k` | 综合质量优先，支持完整能力 |
| `seedance2.0-fast` | `480p`、`720p` | 生成速度优先 |
| `seedance2.0-mini` | `480p`、`720p` | 轻量任务和速度优先 |
三个模型均支持：
- 文生视频；
- 单图生视频；
- 首尾帧生视频；
- 图片、视频和音频多模态参考；
- 视频编辑和视频延长；
- 有声视频、水印和随机种子；
- 纯文本联网搜索；
- 返回生成视频的尾帧；
- 使用可用素材响应返回的 `uri`。
## 2. 接口与鉴权
推荐使用 OpenAI 兼容视频任务接口：
```http
POST /v1/videos
GET /v1/videos/{task_id}
GET /v1/videos/{task_id}/content
```
请求头：
```http
Authorization: Bearer sk-***
Content-Type: application/json
```
以下示例中的 `{BASE_URL}` 使用：
```uri
https://api.uniai.tv
```
同时保留以下兼容接口：
```http
POST /v1/videos/generations
GET /v1/videos/generations/{task_id}
POST /v1/video/generations
GET /v1/video/generations/{task_id}
```
新接入建议统一使用 `/v1/videos`。
## 3. 公共参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 三个公共模型之一，或兼容期内的固定分辨率模型名 |
| `prompt` | string | 条件必填 | 视频提示词；使用 `content[]` 时改为至少一个 `type=text` 项 |
| `resolution` | string | 新公共模型必填 | 输出分辨率，取值见模型表 |
| `size` | string | 否 | `resolution` 的兼容别名 |
| `duration` | integer/string | 是 | 输出时长，支持 `4` 到 `15` 秒；兼容值 `auto`，推荐显式传整数 |
| `aspect_ratio` | string | 否 | `auto`、`21:9`、`16:9`、`4:3`、`3:2`、`2:3`、`1:1`、`3:4`、`9:16` |
| `ratio` | string | 否 | `aspect_ratio` 的兼容别名；`adaptive` 等价于 `auto` |
| `content` | object[] | 否 | 推荐的多模态输入格式，详见下一节 |
| `operation` | string | 特定能力必填 | `reference_to_video`、`edit_video` 或 `extend_video` |
| `generate_audio` | boolean | 否 | 是否生成有声视频 |
| `watermark` | boolean | 否 | 是否添加水印 |
| `seed` | integer | 否 | 随机种子 |
| `return_last_frame` | boolean | 否 | 是否在完成结果中返回尾帧 URL |
| `tools` | object[] | 否 | 当前仅支持 `[{"type":"web_search"}]` |
参数兼容规则：
- `resolution` 和 `size` 同时传入时必须相同。
- `aspect_ratio` 和 `ratio` 同时传入时必须表达相同比例。
- `ratio: "adaptive"` 与 `aspect_ratio: "auto"` 视为相同。
- `operation`、`generate_audio`、`watermark`、`seed`、`return_last_frame` 和 `tools` 也兼容放入 `extra_body`；同一参数不要在顶层和 `extra_body` 重复传入。
- `draft`、`frames`、`camera_fixed` 和 `service_tier: "flex"` 不属于当前公共契约。
## 4. `content[]` 多模态格式
复杂输入推荐统一使用 `content[]`：
```json
{
"content": [
{
"type": "text",
"text": "提示词"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.png"
},
"role": "reference_image"
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/video.mp4"
},
"role": "reference_video"
},
{
"type": "audio_url",
"audio_url": {
"url": "https://example.com/audio.mp3"
},
"role": "reference_audio"
}
]
}
```
支持的类型和角色：
| `type` | `role` | 含义 |
| --- | --- | --- |
| `text` | 无 | 提示词，可传多个文本项 |
| `image_url` | `image` | 单图生视频输入图 |
| `image_url` | `reference_image` | 参考图片 |
| `image_url` | `first_frame` | 首帧图片 |
| `image_url` | `last_frame` | 尾帧图片 |
| `video_url` | `source_video` | 编辑或延长的源视频 |
| `video_url` | `reference_video` | 参考视频 |
| `audio_url` | `reference_audio` | 参考音频 |
输入约束：
- `content[]` 至少包含一个非空文本项。
- 图片最多 9 张，视频最多 3 段，音频最多 3 段。
- `first_frame` 和 `last_frame` 必须成对出现，且各只能有 1 张。
- 首尾帧模式不能再混入视频、音频或其他图片。
- `image` 和 `reference_image` 不要在同一请求中混用。
- `source_video` 最多 1 段。
- 参考音频必须同时存在至少一张图片或一段视频；不接受纯音频或“文本 + 音频”。
- 使用多份参考素材时，可在提示词中按顺序使用 `@Image1`、`@Video1`、`@Audio1` 指定素材。
简单请求仍兼容 `image`、`images`、`last_image`、`video`、`videos` 和 `audios` 等字段；新功能和多模态组合建议使用 `content[]`，避免输入角色不明确。
## 5. 请求示例
### 5.1 文生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0",
"prompt": "雨后的未来城市街道，霓虹倒影，电影感镜头缓慢向前推进。",
"resolution": "1080p",
"duration": 5,
"ratio": "16:9",
"generate_audio": true
}'
```
### 5.2 单图生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0-fast",
"resolution": "720p",
"duration": 6,
"content": [
{
"type": "text",
"text": "人物自然转身看向镜头，衣服随风轻微摆动，保持人物身份一致。"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/person.png"
},
"role": "image"
}
]
}'
```
### 5.3 首尾帧生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0",
"resolution": "720p",
"duration": 6,
"content": [
{
"type": "text",
"text": "镜头从白天自然过渡到夜晚，运动连贯，建筑结构保持稳定。"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/first.png"
},
"role": "first_frame"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/last.png"
},
"role": "last_frame"
}
]
}'
```
### 5.4 多模态参考生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0-mini",
"resolution": "720p",
"duration": 8,
"operation": "reference_to_video",
"content": [
{
"type": "text",
"text": "让 @Image1 中的产品按照 @Video1 的镜头运动展示，并参考 @Audio1 的节奏。"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/product.png"
},
"role": "reference_image"
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/motion.mp4"
},
"role": "reference_video"
},
{
"type": "audio_url",
"audio_url": {
"url": "https://example.com/music.mp3"
},
"role": "reference_audio"
}
]
}'
```
### 5.5 视频编辑
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0",
"resolution": "720p",
"duration": 6,
"operation": "edit_video",
"content": [
{
"type": "text",
"text": "把背景替换为雨夜霓虹街道，保留人物动作和主体身份。"
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/source.mp4"
},
"role": "source_video"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/style.png"
},
"role": "reference_image"
}
]
}'
```
### 5.6 视频延长
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0-fast",
"resolution": "720p",
"duration": 5,
"operation": "extend_video",
"content": [
{
"type": "text",
"text": "延续原镜头运动，人物继续向前行走，光线和场景保持一致。"
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/source.mp4"
},
"role": "source_video"
}
]
}'
```
### 5.7 纯文本联网搜索
联网搜索只能用于纯文本请求，不能同时传图片、视频或音频。
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0-mini",
"prompt": "根据今天公开的科技新闻制作一段简洁的资讯视频，不要显示品牌商标。",
"resolution": "720p",
"duration": 5,
"tools": [
{
"type": "web_search"
}
]
}'
```
`web_search` 表示允许模型检索公开信息，不保证每次生成都会实际产生搜索调用。
### 5.8 返回尾帧
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0",
"prompt": "一艘纸船缓慢停在石桥旁，最后画面保持稳定。",
"resolution": "720p",
"duration": 5,
"return_last_frame": true
}'
```
任务完成后，尾帧通过 `result.last_frame_url` 返回，不会混入视频 `outputs`。
### 5.9 使用素材库 URI
通过 [Seedance 2.0 素材库](/models/video/seedance-2-0/material-library) 创建并查询可复用输入。素材达到 `status=available` 后，把普通媒体 URL 替换为接口返回的 `uri`：
```json
{
"model": "seedance2.0-fast",
"resolution": "480p",
"duration": 4,
"content": [
{
"type": "text",
"text": "Keep the product appearance consistent as the camera slowly moves around it."
},
{
"type": "image_url",
"image_url": {
"url": "asset://asset-EXAMPLE"
},
"role": "reference_image"
}
]
}
```
复制自己的素材响应中的 `uri`，不要用 `mat_*` 自行拼接。URI 只能放入对应的结构化媒体字段，不要写入提示词，并须在 `expires_at` 前使用。
## 6. 任务状态与结果
创建成功后返回异步任务：
```json
{
"id": "task_xxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxx",
"object": "video.generation.job",
"model": "seedance2.0",
"status": "queued",
"progress": 0,
"created_at": 1784640000
}
```
创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/models/video/overview#视频任务生命周期)。
Seedance 请求生成尾帧时，完成响应还可能包含 `result.last_frame_url`。
## 7. 固定分辨率模型兼容
已有客户端可以继续使用固定分辨率模型名：
| 模型系列 | 兼容模型名 |
| --- | --- |
| Standard | `seedance2.0-480p`、`seedance2.0-720p`、`seedance2.0-1080p`、`seedance2.0-4k` |
| Fast | `seedance2.0-fast-480p`、`seedance2.0-fast-720p` |
| Mini | `seedance2.0-mini-480p`、`seedance2.0-mini-720p` |
更早的以下名称也继续兼容：
- `seedance2.0-video-480p`
- `seedance2.0-video-720p`
- `seedance2.0-fast-video-480p`
- `seedance2.0-fast-video-720p`
固定分辨率模型从模型名确定分辨率，不要求额外传 `resolution`。它们与对应的新公共模型使用相同参数和能力；如仍传 `resolution` 或 `size`，值必须与模型名中的分辨率一致。
新项目建议迁移到三个公共模型名，便于只修改请求参数即可切换输出分辨率。
## 8. 常见错误
| 场景 | 结果 | 修正方式 |
| --- | --- | --- |
| 新公共模型缺少 `resolution`/`size` | HTTP `400` | 显式传入支持的分辨率 |
| `resolution` 与 `size` 不同 | HTTP `400` | 只传一个，或保证值相同 |
| `aspect_ratio` 与 `ratio` 冲突 | HTTP `400` | 只传一个，或保证语义相同 |
| 缺少 `duration` | HTTP `400` | 传 `4` 到 `15` 的整数 |
| `content[]` 没有文本项 | HTTP `400` | 增加非空 `type=text` 项 |
| 首帧和尾帧没有成对传入 | HTTP `400` | 同时传 `first_frame` 和 `last_frame` |
| 纯音频或“文本 + 音频” | HTTP `400` | 至少增加一张图片或一段视频 |
| 联网搜索请求包含媒体 | HTTP `400` | 搜索请求只保留文本输入 |
| 图片、视频或音频数量超限 | HTTP `400` | 分别控制在 9、3、3 个以内 |
| 使用 `draft`、`frames`、`camera_fixed` 或 `service_tier=flex` | HTTP `400` | 删除这些参数 |
遇到安全审核、素材格式或参数错误时，应修改输入后创建新任务，不要对同一无效请求进行高频重复提交。
## 9. 相关页面
- [Seedance 2.0](/models/video/seedance-2-0)
- [Seedance 2.0 素材库](/models/video/seedance-2-0/material-library)
- [视频生成概览](/models/video/overview#视频任务生命周期)
---
# Seedance 2.5
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/seedance-2-5
Source: .generated/cn/site-docs/models/video/seedance-2-5.md
Description: 使用 Seedance 2.5 创建 480p/720p/1080p 视频、音频参考、Draft 样片及 1080p 成片，支持编辑、延长和高级控制。
本页中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。
更新时间：2026-10-19
## 概览
UniAI 对外提供一个稳定的 Seedance 2.5 公共模型：`seedance2.5`。该模型支持文生视频、单首帧和首尾帧生视频、多模态参考生成、视频编辑、视频延长、可复用 `asset://` 素材、可选的联网搜索，以及 480p Draft 样片转 1080p 成片。
| 能力 | 必需输入 | 核心规则 |
| --- | --- | --- |
| 文生视频 | 提示词 | 默认 `720p`、自动时长，也可显式选择。 |
| 单首帧生视频 | 1 张首帧图 | 省略 `aspect_ratio` 或设为 `auto`。 |
| 首尾帧生视频 | 1 张首帧图和 1 张尾帧图 | 省略 `aspect_ratio` 或设为 `auto`。 |
| 多模态参考生成 | 图片、视频或音频 | 文本可省略，也允许仅音频参考。 |
| 视频编辑 | 提示词和 1 个视频 | 显式传 `omni_reference_task_type: "edit"`，使用自动时长。 |
| 视频延长 | 提示词和 1 个视频 | 显式传 `omni_reference_task_type: "extend"`。 |
| Draft 转成片 | 当前用户已完成的 Draft 任务 ID | 样片为 `480p`，七天内可转为继承原设置的 `1080p` 成片。 |
## 接口与鉴权
| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建任务 | `POST` | `/v1/videos` |
| 查询任务 | `GET` | `/v1/videos/{task_id}` |
已有客户端可继续使用以下兼容创建和查询路径：
```http
POST /v1/videos/generations
POST /v1/video/generations
GET /v1/videos/generations/{task_id}
GET /v1/video/generations/{task_id}
```
新接入统一使用 `/v1/videos` 和 `/v1/videos/{task_id}`。
```http
Authorization: Bearer
Content-Type: application/json
```
## 请求参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `seedance2.5`。 |
| `prompt` | string | 条件必填 | 文本指令。纯文生、编辑和延长必填；有图片、视频或音频参考时可省略，Draft 转成片时必须省略。 |
| `resolution` | string | 否 | `480p`、`720p` 或 `1080p`。普通请求默认 `720p`；Draft 默认且只能为 `480p`；Draft 转成片默认且只能为 `1080p`。 |
| `duration` | integer/string | 否 | `"auto"`、`-1` 或 `4` 到 `30` 的整数，默认自动时长。编辑只能使用自动时长；Draft 转成片时省略。 |
| `aspect_ratio` | string | 否 | `auto`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4` 或 `9:16`。帧输入、编辑和延长需省略或使用 `auto`；Draft 转成片时省略。 |
| `content` | object[] | 否 | 文字、图片、视频或音频内容。文字项使用 `{"type":"text","text":"..."}`，媒体角色见下文。 |
| `omni_reference_task_type` | string | 否 | `auto`、`reference`、`edit` 或 `extend`。编辑或延长需显式设置对应值；Draft 转成片时省略。 |
| `draft` | boolean | 否 | `true` 创建 480p 样片，默认 `false`；Draft 转成片时不能为 `true`。 |
| `draft_task_id` | string | 条件必填 | 同一用户创建、已完成且创建未满七天的 UniAI Draft 任务 ID，用于生成 1080p 成片。 |
| `output_format` | string | 否 | `mp4` 或 `mov`，默认 `mp4`。 |
| `generate_audio` | boolean | 否 | 是否生成音频，显式 `false` 会保留。Draft 转成片时继承，必须省略。 |
| `watermark` | boolean | 否 | 是否添加水印，显式 `false` 会保留。 |
| `return_last_frame` | boolean | 否 | 是否在可用时返回生成视频的尾帧，显式 `false` 会保留。 |
| `seed` | integer | 否 | `-1` 到 `2147483647`；Draft 转成片时省略。 |
| `priority` | integer | 否 | `0` 到 `9`，显式 `0` 会保留。 |
| `execution_expires_after` | integer | 否 | 执行过期时间，单位为秒，范围 `3600` 到 `259200`。 |
| `safety_identifier` | string | 否 | `1` 到 `64` 个可见 ASCII 字符，不含空格或控制字符；使用非敏感标识。 |
| `tools` | object[] | 否 | 联网搜索使用 `[{"type":"web_search"}]`；Draft 转成片时省略。 |
| `service_tier` | string | 否 | 仅支持 `default`，不支持 `flex`。 |
| `size` | string | 否 | `resolution` 的兼容别名；两者同时存在时必须描述同一分辨率，推荐使用 `resolution`。 |
| `seconds` | integer/string | 否 | `duration` 的兼容别名，推荐使用 `duration`；Draft 转成片时省略。 |
| `ratio` | string | 否 | `aspect_ratio` 的兼容别名，`adaptive` 归一为 `auto`；Draft 转成片时省略。 |
| `operation` | string | 否 | 兼容操作选择：`reference_to_video`、`edit_video` 或 `extend_video`。新示例优先使用 `omni_reference_task_type`，不要传入冲突选择；Draft 转成片时省略。 |
参数放在顶层。兼容客户端也可把控制参数放在 `extra_body` 中；同一字段在两处同时出现时，值必须一致。显式 `false` 和 `0` 是有效值，不等同于省略。
不支持 4K、`frames`、`camera_fixed` 或 `flex` 服务档位。
## 最小文生请求
```bash
curl -X POST "https://api.uniai.tv/v1/videos" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.5",
"prompt": "A mechanical bird unfolds its wings on a wooden table."
}'
```
省略 `resolution` 和 `duration` 时，普通生成使用 `720p` 和自动时长。需要明确规格和高级控制时可使用：
```json
{
"model": "seedance2.5",
"prompt": "A mechanical bird unfolds its wings on a wooden table.",
"resolution": "1080p",
"duration": 4,
"aspect_ratio": "16:9",
"output_format": "mp4",
"generate_audio": true,
"watermark": false,
"return_last_frame": true,
"seed": 250628,
"priority": 0,
"execution_expires_after": 86400,
"safety_identifier": "video-demo-01"
}
```
## 媒体输入
新接入建议使用 `content[]` 表达多模态输入。每一项包含一个媒体类型和明确角色。
| 项目类型 | URL 字段 | 支持角色 |
| --- | --- | --- |
| `text` | `text` | 生成或编辑指令 |
| `image_url` | `image_url.url` | `first_frame`、`last_frame`、`reference_image` |
| `video_url` | `video_url.url` | `reference_video` |
| `audio_url` | `audio_url.url` | `reference_audio` |
媒体地址可以是公开 HTTP(S) URL，也可以是有效的 `asset://` 素材地址。HTTP(S) 素材必须能由 UniAI 服务直接访问，不能依赖 Cookie 或自定义请求头。创建可复用 `asset://` 输入的方法见 [Seedance 素材库](/models/video/seedance-2-0/material-library)。素材可用后直接复制响应返回的 `uri`，不要用 `mat_*` 自行拼接，并须在 `expires_at` 前使用。
图片和音频兼容字段 `image`、`images`、`audios` 和 `last_image` 仍可使用。不要同时通过 `content[]` 和兼容字段传入冲突内容。
视频参考请使用 `content[]` 中 `type: "video_url"`、`role: "reference_video"` 的写法。顶层 `video` / `video_url` 字段使用编辑或延长入口的语义，不能直接替代参考视频内容项。编辑或延长时需显式设置 `omni_reference_task_type` 为 `edit` 或 `extend`。
### 媒体数量限制
- 图片最多 `30` 张。
- 视频最多 `10` 个。
- 音频最多 `10` 个。
- 所有媒体合计最多 `50` 个。
- 多模态请求可以不包含文本。
- 允许仅音频参考请求。
## 操作规则
| 模式 | `omni_reference_task_type` | `duration` | `aspect_ratio` |
| --- | --- | --- | --- |
| 文生视频 | 省略或 `auto` | 省略、`"auto"`、`-1` 或整数 `4..30` | 任意支持值 |
| 单首帧 / 首尾帧生视频 | 省略或 `auto` | 省略、`"auto"`、`-1` 或整数 `4..30` | 省略或 `auto` |
| 多模态参考生成 | 显式指定时使用 `reference` | 省略、`"auto"`、`-1` 或整数 `4..30` | 由媒体模式决定；帧输入需使用 `auto` |
| 视频编辑 | 必须为 `edit` | 省略、`"auto"` 或 `-1` | 省略或 `auto` |
| 视频延长 | 必须为 `extend` | 省略、`"auto"`、`-1` 或整数 `4..30` | 省略或 `auto` |
| Draft 转成片 | 省略，自动继承 | 省略，自动继承 | 省略，自动继承 |
编辑和延长都需要提示词和源视频，不要通过提示词关键词推断操作。原有 `operation` 选择仍兼容，新示例使用 `omni_reference_task_type`。
## 请求示例
### 首尾帧生视频
```json
{
"model": "seedance2.5",
"prompt": "Move naturally from the first composition to the last while preserving the subject.",
"resolution": "720p",
"duration": 10,
"aspect_ratio": "auto",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://example.com/first.png"
},
"role": "first_frame"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/last.png"
},
"role": "last_frame"
}
]
}
```
单首帧模式只传 `first_frame` 项。两种帧模式都不能使用固定画幅，因为画面构图由源图片决定。
### 多模态参考生成
```json
{
"model": "seedance2.5",
"omni_reference_task_type": "reference",
"resolution": "720p",
"duration": 12,
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://example.com/product.png"
},
"role": "reference_image"
},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/motion.mp4"
},
"role": "reference_video"
},
{
"type": "audio_url",
"audio_url": {
"url": "https://example.com/music.mp3"
},
"role": "reference_audio"
}
]
}
```
### 仅音频参考，无提示词
```json
{
"model": "seedance2.5",
"resolution": "480p",
"duration": 4,
"content": [
{
"type": "audio_url",
"audio_url": {
"url": "https://example.com/reference.wav"
},
"role": "reference_audio"
}
]
}
```
### 视频编辑
```json
{
"model": "seedance2.5",
"prompt": "Replace the sky and preserve the subject",
"video": "https://example.com/source.mp4",
"omni_reference_task_type": "edit",
"resolution": "720p",
"duration": "auto",
"aspect_ratio": "auto"
}
```
### 视频延长
```json
{
"model": "seedance2.5",
"prompt": "Continue the camera movement into the illuminated square.",
"video": "asset://asset-EXAMPLE",
"omni_reference_task_type": "extend",
"resolution": "720p",
"duration": 8,
"aspect_ratio": "auto",
"output_format": "mov"
}
```
### 联网搜索
```json
{
"model": "seedance2.5",
"prompt": "Create a concise visual recap of the latest public spaceflight milestone.",
"resolution": "720p",
"duration": 8,
"tools": [
{
"type": "web_search"
}
]
}
```
联网搜索可以与媒体输入组合。其他 `tools` 结构不受支持。
## Draft 样片转 1080p 成片 {/* #draft-to-final */}
### 1. 创建 480p Draft
设置 `draft: true`。省略 `resolution` 时使用 `480p`；显式指定其他档位会拒绝。Draft 也可使用本页的媒体参考输入。
```bash
curl -X POST "https://api.uniai.tv/v1/videos" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.5",
"prompt": "A mechanical bird unfolds its wings on a wooden table.",
"draft": true,
"duration": 4,
"aspect_ratio": "16:9",
"generate_audio": true,
"seed": 250628
}'
```
### 2. 保存 UniAI 任务 ID 并等待完成
使用创建响应中的 `id` 或 `task_id` 查询，直到 `status` 为 `completed`。下方 `task_YOUR_COMPLETED_DRAFT` 是占位符，必须替换为你实际收到的 UniAI 任务 ID。
```bash
curl "https://api.uniai.tv/v1/videos/task_YOUR_COMPLETED_DRAFT" \
-H "Authorization: Bearer "
```
### 3. 提交成片请求
父任务必须是同一 UniAI 用户创建、已完成的 Seedance 2.5 Draft，且自创建起未满七天。未完成、失败、过期、非 Draft 或其他用户的任务不能复用。
```bash
curl -X POST "https://api.uniai.tv/v1/videos" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.5",
"draft_task_id": "task_YOUR_COMPLETED_DRAFT",
"output_format": "mov",
"watermark": false,
"return_last_frame": true,
"priority": 0
}'
```
成片默认使用 `1080p`，也可显式指定 `resolution: "1080p"`；其他分辨率会拒绝。成功提交后会返回新的成片任务 ID，按同样方式轮询。
成片继承原 Draft 的提示词、所有素材、时长、画幅、`seed`、`generate_audio` 及任务类型。请省略这些继承字段，不要重复发送相同值或尝试覆盖；`tools`、`operation` 和 `omni_reference_task_type` 也必须省略。原始 `content` 不可重复传入，即使 `generate_audio` 为 `false` 也不要重传。
可以单独设置 `output_format`、`watermark`、`return_last_frame`、`priority`、`execution_expires_after` 和 `safety_identifier`，但不能设置 `draft: true`。
也兼容仅包含一条 Draft 引用的 `content` 写法：
```json
{
"model": "seedance2.5",
"content": [
{
"type": "draft_task",
"draft_task": {
"id": "task_YOUR_COMPLETED_DRAFT"
}
}
]
}
```
该 `id` 同样必须使用 UniAI 返回的公开任务 ID。不要与其他文本或媒体 part 混合；若同时传入 `draft_task_id`，两处 ID 必须一致。
## 创建响应与任务生命周期
```json
{
"id": "task_xxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxx",
"object": "video.generation.job",
"model": "seedance2.5",
"status": "queued",
"progress": 0,
"created_at": 1792368000
}
```
保存公开 `id` 或 `task_id`，建议每 2 到 5 秒调用 `GET /v1/videos/{task_id}`，直到 `status` 变为 `completed` 或 `failed`。完成后优先使用响应中的 `video_url` 下载视频；兼容响应也可能在 `result.video_url` 或 `result.outputs` 中提供结果。不要把结果 URL 当成永久存储。
普通任务也可按下方方式查询：
```bash
curl "https://api.uniai.tv/v1/videos/task_YOUR_VIDEO" \
-H "Authorization: Bearer "
```
如请求了 `return_last_frame: true`，完成时可读取返回的尾帧结果。1080p 视频使用 HEVC/10bit，需要兼容的播放器；MP4 和 MOV 是输出容器格式。
Seedance 2.5 请求失败、客户端超时或结果不确定时，不得自动重试创建请求。已拿到任务 ID 时继续查询原任务；没有任务 ID 时先核对原请求结果。Draft 转成片也遵守此规则。
公共状态字段、完成/失败响应和错误处理见[视频生成概览](/models/video/overview#视频任务生命周期)。本模型的禁止自动重试规则优先于通用重试建议。
## 计费说明
以各任务返回的实际 Token 用量和最终结算记录为准，预扣仅为估算。Draft 和成片是两个独立计费的任务，样片不抵扣成片，也不会被重复计为成片的输入视频。当前价格以账号可见的 UniAI 价格为准。
## 常见错误
| 错误 | 原因 | 处理方式 |
| --- | --- | --- |
| 缺少输入 | 既没有提示词，也没有媒体或有效 Draft 引用 | 提供对应工作流的必需输入。 |
| 分辨率无效 | 4K，或 Draft/成片档位不匹配 | 普通请求使用 `480p`/`720p`/`1080p`，Draft 仅 `480p`，成片仅 `1080p`。 |
| 兼容别名冲突 | `resolution` 和 `size` 的值不同 | 删除 `size` 或确保两者完全一致。 |
| 编辑时长无效 | 编辑使用整数时长 | 省略 `duration` 或设为 `"auto"`/`-1`。 |
| 画幅无效 | 首帧、首尾帧、编辑或延长请求使用固定比例 | 省略 `aspect_ratio` 或设为 `auto`。 |
| 媒体数量超限 | 单类型或媒体总数超过限制 | 按文档限制减少媒体数量。 |
| 素材不可访问 | URL 私有、过期或无法从公网访问 | 使用稳定公开 URL 或可用的 `asset://` 素材。 |
| 联网工具无效 | `tools` 不是唯一支持的联网搜索结构 | 传 `[{"type":"web_search"}]` 或省略 `tools`。 |
| 字段不支持 | 传入 `frames`、`camera_fixed` 或 `service_tier: "flex"` | 删除不支持字段。 |
| Draft 引用无效 | 不存在、未完成、非 Draft、过期或属于其他用户 | 使用同用户未满七天的已完成 Draft 的 UniAI 任务 ID。 |
| 成片继承字段重复 | 成片请求再次传入 prompt、素材、时长、比例、seed、音频或任务类型 | 省略所有继承字段，只发送 Draft ID 和允许的输出控制。 |
| 参数类型或范围错误 | 布尔值写成字符串，或 priority、seed、过期时间超出范围 | 使用 JSON 布尔值和参数表规定的整数范围。 |
## 相关页面
- [视频生成概览](/models/video/overview)
- [Seedance 2.0](/models/video/seedance-2-0)
- [Seedance 素材库](/models/video/seedance-2-0/material-library)
- [模型列表](/models)
---
# Vidu Q3
Locale: zh-CN
URL: https://docs.uniai.tv/models/video/vidu
Source: .generated/cn/site-docs/models/video/vidu.md
Description: 通过 UniAI 调用 Vidu Q3 系列，创建文生、单图、首尾帧和多参考图视频。
本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。
更新时间：2026-08-04
## 概览
Vidu Q3 系列只使用两个稳定公共模型名，通过请求体顶层的 `resolution` 参数选择输出分辨率，不再把分辨率写进模型名。
| 公共模型 | 系列 | 文生视频 | 单图生视频 | 首尾帧 | 多参考图 |
| --- | --- | --- | --- | --- | --- |
| `viduq3p` | Q3 Pro | 支持 | 支持 | 支持 | 支持 1 至 4 张 |
| `viduq3t` | Q3 Turbo | 支持 | 支持 | 支持 | 支持 1 至 4 张 |
两个模型均支持 `540p`、`720p` 和 `1080p`，这两个 ID 是 Vidu Q3 对外唯一保留的公共模型名。
## 适用场景
Vidu Q3 适合以下任务：
- 根据文字提示词生成视频；
- 让一张可公开访问的图片动起来；
- 根据首帧和尾帧生成连续视频；
- 使用 1 至 4 张参考图约束人物、主体或视觉风格。
客户端只需选择公共模型并传入请求参数。不要传入渠道名、上游模型名、上游任务字段或路由控制参数。
## 接口
新接入统一使用以下接口：
| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载视频文件 | `GET` | `/v1/videos/{task_id}/content` |
以下兼容接口仍可使用：
| 用途 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos/generations` |
| 查询视频任务 | `GET` | `/v1/videos/generations/{task_id}` |
| 创建视频任务 | `POST` | `/v1/video/generations` |
| 查询视频任务 | `GET` | `/v1/video/generations/{task_id}` |
新接入建议统一使用 `/v1/videos`。
## 鉴权
所有请求均使用 UniAI Bearer Token：
```http
Authorization: Bearer sk-***
```
创建任务时还需发送：
```http
Content-Type: application/json
```
## 请求体参数
| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `viduq3p` 或 `viduq3t`。 |
| `prompt` | string | 是 | 视频生成提示词。 |
| `duration` | integer | 是 | 输出时长，范围为 `1` 至 `16` 秒。 |
| `aspect_ratio` | string | 否 | `16:9`、`9:16`、`3:4`、`4:3` 或 `1:1`。 |
| `image` | string | 条件必填 | 单图模式的输入图或首尾帧模式的首帧，必须是公开可访问的 HTTP(S) URL。 |
| `last_image` | string | 条件必填 | 尾帧图片的公开 HTTP(S) URL，必须与 `image` 一起传入。 |
| `reference_image_urls` | string[] | 条件必填 | 多参考图模式的 1 至 4 个公开 HTTP(S) 图片 URL。 |
| `resolution` | string | 是 | `540p`、`720p` 或 `1080p`。 |
| `audio` | boolean | 否 | 是否生成声音。 |
| `bgm` | boolean | 否 | 文生视频的背景音乐控制。 |
| `seed` | integer | 否 | 随机种子。 |
根据生成模式选择输入字段：
| 模式 | 输入字段 |
| --- | --- |
| 文生视频 | `prompt` |
| 单图生视频 | `prompt` + `image` |
| 首尾帧生视频 | `prompt` + `image` + `last_image` |
| 多参考图生视频 | `prompt` + `reference_image_urls` |
字段约束：
- 每次请求都必须传入顶层 `resolution`。
- `image` 与 `reference_image_urls` 不能同时传入。
- `last_image` 不能单独使用，必须与 `image` 组成首尾帧。
- 首尾帧和多参考图模式不要使用 `images` 或 `image_urls`。
- `resolution`、`audio`、`bgm` 和 `seed` 都直接放在请求体顶层，不要包在 `extra_body` 中。
- `size` 不是 `resolution` 的兼容别名。
## 请求示例
### 文生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "viduq3p",
"prompt": "A cinematic aerial shot over a futuristic coastal city at sunrise, soft light, slow camera push-in.",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p",
"audio": false,
"bgm": false,
"seed": 42
}'
```
### 单图生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "viduq3t",
"prompt": "The person slowly raises their head and looks at the camera while the camera gently moves forward.",
"image": "https://example.com/source.png",
"duration": 5,
"aspect_ratio": "9:16",
"resolution": "540p",
"audio": false,
"seed": 42
}'
```
### 首尾帧生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "viduq3p",
"prompt": "The person turns naturally from a front view to a side view while identity and motion remain consistent.",
"image": "https://example.com/head.png",
"last_image": "https://example.com/tail.png",
"duration": 6,
"aspect_ratio": "16:9",
"resolution": "720p",
"audio": false,
"seed": 42
}'
```
### 多参考图生视频
```bash
curl -X POST "{BASE_URL}/v1/videos" \
-H "Authorization: Bearer sk-***" \
-H "Content-Type: application/json" \
-d '{
"model": "viduq3p",
"prompt": "A @Image1 walking through a beach in the visual style of @Image2",
"reference_image_urls": [
"https://example.com/ref-1.png",
"https://example.com/ref-2.png"
],
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "1080p",
"audio": false,
"seed": 42
}'
```
两个公共模型都支持 `reference_image_urls`。参考图提示词可以按数组顺序使用 `@Image1`、`@Image2` 等标记。
## 响应示例
### 任务创建成功
请保存 `id` 或兼容字段 `task_id`，用于后续查询：
```json
{
"id": "task_xxxxxxxxxxxxx",
"task_id": "task_xxxxxxxxxxxxx",
"object": "video.generation.job",
"model": "viduq3p",
"status": "queued",
"progress": 0,
"created_at": 1785772800
}
```
公共响应不会返回渠道标识、上游任务 ID、凭证信息或上游原始响应。
## 任务状态与结果
创建成功后保存 `id` 或 `task_id`，随后调用 `GET /v1/videos/{task_id}`，直到任务进入 `completed` 或 `failed`。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见[视频生成概览](/models/video/overview#视频任务生命周期)。
## 计费说明
计费取决于公共模型、请求的 `resolution` 和实际输出视频秒数。模型名本身不承载分辨率或时段计费档位。
百度 VOD/BV 渠道当前正常时段的参考消耗如下，适用于文生视频、单图生视频和首尾帧视频：
| 公共模型 | `540p` | `720p` | `1080p` |
| --- | ---: | ---: | ---: |
| `viduq3p`（Q3 Pro） | 0.28125 元/秒 | 0.625 元/秒 | 0.75 元/秒 |
| `viduq3t`（Q3 Turbo） | 0.21875 元/秒 | 0.375 元/秒 | 0.40625 元/秒 |
渠道消耗 = 单价 × 实际输出时长。多参考图请求可能选择其他符合条件的渠道，不能直接套用这张百度 VOD 表。最终对外价格和结算以 UniAI 模型页及消费日志为准。
## 常见错误
以下情况会在任务创建前被拒绝：
- 使用 `viduq3p` 或 `viduq3t` 之外的模型名；
- 缺少 `resolution`，或传入 `540p`、`720p`、`1080p` 以外的值；
- 使用 `size` 代替 `resolution`；
- 缺少 `duration`，或传入 `1` 至 `16` 之外的值；
- 使用 `21:9`、`1920x1080` 等不支持的画幅比例；
- `reference_image_urls` 为空或超过 4 张；
- 同时传入 `image` 与 `reference_image_urls`，或单独传入 `last_image`；
- 图片 URL 无法由服务端公开访问；
- 把支持的顶层参数放进 `extra_body`。
## 相关页面
- [视频生成概览](/models/video/overview)
- [模型列表](/models)