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

# 视频生成

> 使用 AIHubMix 原生视频协议创建异步任务、查询状态并下载视频。

AIHubMix 原生视频协议使用 `/ai/v1/videos` 系列端点。视频生成固定异步，请求提交后返回
任务 ID，客户端轮询详情或接收 Webhook，完成后下载视频。

使用豆包 Seedance 引用本人已确认的素材时，请先阅读[豆包真人素材使用指南](https://docs.aihubmix.com/cn/api/doubao-real-person-assets.md)。

> [!WARNING]
>
> 使用原生视频任务接口前，需要为当前账户开启异步任务功能。未开启时，任务创建请求返回
> `403 async_not_enabled`。

## 快速开始

下面使用 `wan2.6-t2v` 创建一个 5 秒视频。

```bash 创建任务 theme={null}
curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "Ocean waves crashing on rocky cliffs at sunset",
    "duration": 5,
    "size": "1280x720"
  }'
```

```json 创建响应 theme={null}
{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}
```

```bash 查询任务 theme={null}
curl https://aihubmix.com/ai/v1/videos/{id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

```bash 下载视频 theme={null}
curl https://aihubmix.com/ai/v1/videos/{id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4
```

## 接口概览

| 场景 | 方法 | 路径 | 说明 |
| - | - | - | - |
| 创建视频 | POST | `/ai/v1/videos` | 提交固定异步的视频生成任务 |
| 查询视频详情 | GET | `/ai/v1/videos/{id}` | 返回任务最新状态 |
| 查询视频列表 | GET | `/ai/v1/videos` | 返回当前账户创建的视频任务快照 |
| 下载视频 | GET | `/ai/v1/videos/{id}/content` | 下载任务的主视频结果 |

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

认证方式：

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

## 查询模型 Schema

模型目录可以筛选已经提供请求 Schema 的文生视频模型：

```bash theme={null}
curl "https://aihubmix.com/api/v1/models?type=video&schema_checked=true&sort_by=order"
```

取得 `model_id` 后，查询该模型实际支持的端点：

```bash theme={null}
curl "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints"
```

同一模型可能同时返回 AIHubMix 原生与 OpenAI 兼容端点。应按 `path` 选择原生视频接口，
再读取对应的 `request.schema`：

```bash theme={null}
curl -s "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'
```

不要依赖 `endpoints` 数组位置。完整响应字段和失败情况参阅
[模型 Schema 接口](https://docs.aihubmix.com/cn/api/async-tasks.md#model-schema)。

## 创建视频

视频请求始终异步，不支持通过 `Prefer: wait` 改为同步等待。原生协议使用整数
`duration` 表示秒数；不要沿用 `/v1/videos` 兼容协议中的字符串 `seconds`。

### 标准字段

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 模型 ID |
| `prompt` | string | 是 | 视频描述，不能为空 |
| `duration` | integer/null | 否 | 视频时长，单位为秒 |
| `aspect_ratio` | string/null | 否 | 宽高比，协议默认值为 `16:9` |
| `resolution` | string/null | 否 | `480p`、`720p`、`1080p`、`1K`、`2K` 或 `4K` |
| `size` | string/null | 否 | `{width}x{height}`，可代替 `resolution` 与 `aspect_ratio` |
| `seed` | integer/null | 否 | 随机种子 |
| `input_references` | array/null | 否 | 图片、视频或音频参考素材 |
| `frame_images` | array/null | 否 | 首帧或尾帧图片 |
| `generate_audio` | boolean/null | 否 | 是否生成音轨 |
| `webhook_url` | string | 否 | HTTPS 回调地址，最长 512 字符 |
| `webhook_events_filter` | string\[] | 否 | `completed`、`failed`、`cancelled` 的非空子集 |
| `extra` | object/null | 否 | 模型专属扩展参数 |

参考媒体项示例：

```json theme={null}
{
  "type": "image_url",
  "url": "https://example.com/reference.png"
}
```

`input_references[].type` 可以是 `image_url`、`video_url` 或 `audio_url`。首尾帧使用
`frame_images`：

```json theme={null}
{
  "frame_type": "first_frame",
  "image_url": {
    "url": "https://example.com/first-frame.png"
  }
}
```

> [!WARNING]
>
> 标准字段集合不表示所有模型支持全部字段。`duration`、分辨率、参考媒体结构和枚举范围
> 必须以该模型 `/ai/v1/videos` 端点的 `request.schema` 为准。

## 视频任务对象

创建接口先返回任务对象。任务完成后，详情接口返回以下结构：

```json theme={null}
{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/videos/task_01K0ABCDEF/content"
    }
  ],
  "error": null,
  "created_at": 1784707200,
  "completed_at": 1784707320,
  "expires_at": 1784714520
}
```

| 字段 | 类型 | 说明 |
| - | - | - |
| `id` | string | 平台任务 ID |
| `object` | string | 视频任务固定为 `video` |
| `model` | string | 实际使用的模型 ID |
| `status` | string | 当前任务状态 |
| `output` | array | 已生成的结果；尚无结果时为空数组 |
| `error` | object/null | 失败信息，可含 `code`、`message` 和 `upstream_detail` |
| `created_at` | integer | 创建时间，Unix 秒 |
| `completed_at` | integer/null | 进入结束态的时间，Unix 秒 |
| `expires_at` | integer/null | 结果过期时间，Unix 秒；任务完成前可能为空 |

视频媒体接口的 `output` 项包含 `index`、固定值 `type: "file"`、`content_url`，以及通常
为空的 `b64_json`。视频结果一般通过二进制内容端点下载。

### 状态说明

| 状态 | 是否结束 | 说明 |
| - | - | - |
| `pending` | 否 | 已接收，等待执行 |
| `in_progress` | 否 | 正在生成 |
| `completed` | 是 | 已完成，可下载视频 |
| `failed` | 是 | 已失败，原因见 `error` |
| `cancelled` | 是 | 已取消 |

客户端可以每 15 秒查询一次，直到状态变为 `completed`、`failed` 或 `cancelled`。
15 秒是客户端轮询建议，不是服务端协议限制。

## 查询视频任务

### 查询详情

```bash theme={null}
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

视频详情接口会返回任务最新状态。轮询必须使用该接口，不要使用统一任务详情代替。

### 查询列表

创建响应丢失时，可以通过视频列表找回任务 ID：

```bash theme={null}
curl "https://aihubmix.com/ai/v1/videos?limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

| 参数 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `after` | string | - | 分页游标，使用上一页的 `next_after` |
| `limit` | integer | `20` | 每页数量，最大 `100` |
| `order` | string | `desc` | `asc` 为升序，其他值按 `desc` 处理 |

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "task_01K0ABCDEF",
      "object": "video",
      "model": "wan2.6-t2v",
      "status": "in_progress",
      "output": [],
      "error": null,
      "created_at": 1784707200,
      "completed_at": null,
      "expires_at": null
    }
  ],
  "has_more": true,
  "next_after": "task_01K0ABCDEF"
}
```

列表返回查询时的任务快照，不会主动更新活动任务状态。

## 统一任务接口

`/ai/v1/tasks` 提供图片、视频和 LLM 任务的统一只读视图。可以只查询视频任务：

```bash theme={null}
curl "https://aihubmix.com/ai/v1/tasks?object=video&status=completed&limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

统一任务列表支持 `object`、`status`、`model`、`after`、`limit` 和 `order`。统一任务详情：

```bash theme={null}
curl https://aihubmix.com/ai/v1/tasks/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

统一任务中的视频结果会额外提供 `result_id` 和 `content_type`：

```json theme={null}
{
  "index": 0,
  "result_id": "result_01K0XYZ",
  "type": "file",
  "content_type": "video/mp4",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
}
```

单产物可以请求 `/ai/v1/tasks/{id}/content`。若统一任务包含多个结果，则请求
`/ai/v1/tasks/{id}/content/{result_id}`；未指定结果 ID 时返回 `400 result_id_required`。

> [!NOTE]
>
> 媒体详情接口可能在查询时更新活动任务状态，统一任务接口只返回当前快照。因此轮询使用
> `/ai/v1/videos/{id}`；统一筛选和读取结果元数据时使用 `/ai/v1/tasks`。
> 任务及内容按创建任务时的 Bearer Token 隔离。

## 下载视频结果

任务进入 `completed` 后，请求视频内容端点：

```bash theme={null}
curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4
```

响应为视频二进制，不是 JSON。也可以直接请求任务对象返回的 `output[].content_url`；
两种方式都需要携带创建任务时的 Bearer Token。

> [!WARNING]
>
> 结果可能过期，也可能存在下载次数限制。过期返回 `410 artifact_expired`；超过下载
> 次数限制返回 `429 too_many_downloads`。客户端应在任务完成后及时保存视频。

## Webhook

创建视频任务时可以同时设置任务级 Webhook：

```bash theme={null}
curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A tranquil garden at sunrise",
    "duration": 5,
    "size": "1280x720",
    "webhook_url": "https://example.com/webhooks/aihubmix"
  }'
```

`webhook_url` 最长 512 字符，不能指向本机、私网或其他受限地址。`wan2.6-t2v`
当前 Schema 未列出 `webhook_events_filter`，因此本例不传事件过滤器，平台默认推送
`completed`、`failed` 和 `cancelled`。只有模型 Schema 明确包含该字段时才可以设置；
显式传入时，数组不能为空、不能重复，并且必须与 `webhook_url` 一起使用。

### 回调请求

```json theme={null}
{
  "event_id": "evt_01K0ABCDEF",
  "event_type": "completed",
  "created_at": "2026-08-12T12:00:00Z",
  "data": {
    "task_id": "task_01K0ABCDEF",
    "status": "completed",
    "model": "wan2.6-t2v",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
      }
    ]
  }
}
```

`event_id` 用于去重；`data.error` 在失败时可能出现；`data.results` 只在结果已存档时出现，
下载仍需 Bearer Token。

### 重试与去重

平台采用至少一次投递，同一个事件可能重复送达：

* HTTP `2xx` 表示接收成功。
* HTTP `5xx`、网络错误或超时会触发重试。
* HTTP `3xx` 和 `4xx` 不会重试。
* 最多投递 6 次，重试间隔依次为 1、4、16、64、256 秒。

接收端应保存 `event_id`，重复收到相同事件时直接返回 `2xx`。任务级 Webhook 本身不
携带独立签名密钥；需要签名验证时，请配置账户级 Webhook，并保留详情查询作为结果确认方式。

## 错误响应与错误码

本节适用于 `/ai/v1/videos/*` 和视频任务。图片错误见 [图片接口](https://docs.aihubmix.com/cn/api/aihubmix-image-generation.md#error-codes)。

* **当前请求失败**：HTTP 非 2xx，表示本次创建、查询或下载请求失败，见 [HTTP 请求失败](#http-errors)。
* **任务执行失败**：查询返回 HTTP 200，但任务的 `status=failed`，原因记录在任务内的 `error`，见 [任务执行失败](#task-errors)。
* **列表单条结果读取失败**：列表返回 HTTP 200，但某条任务带有 `output_error`，见 [列表单条结果读取失败](#output-read-errors)。

下表 `message` 列列出英文返回文案，说明列解释含义及处理方式。参数校验错误列出通用文案，实际响应可能进一步指出具体字段和约束。客户端应使用 `code` 判断错误类型，不应依赖完整 `message` 匹配。

```json theme={null}
{
  "error": {
    "message": "The task was not found.",
    "type": "invalid_request_error",
    "code": "task_not_found",
    "tid": "req_01K0ABCDEF"
  }
}
```

> [card] [提交 HTTP 5xx 错误反馈](https://console.aihubmix.com/support)
>
> 请求返回 HTTP `5xx` 时，请提交反馈并附上 `error.tid`。

### HTTP 请求失败

视频创建后通过任务状态返回生成结果。下表中的 HTTP 状态用于当前请求直接失败的情况。

#### 请求参数与媒体输入

| HTTP | `code` | `message` | 说明 |
| - | - | - | - |
| 400 | `invalid_request` | `Invalid request. Check the request body and parameters.` | 请求体、查询参数或参数类型不正确。按错误信息检查请求格式、参数类型和取值。 |
| 404 | `model_not_found` | `The requested model was not found. Check the model name.` | 请求的模型不存在。检查模型名称。 |
| 400 | `schema_violation` | `One or more model parameters are invalid. Check the model schema and request values.` | 参数不符合所选模型的输入要求。查阅该模型的 schema，修正错误信息指出的字段。 |
| 400 | `unsupported_input_combination` | `This model does not support this operation or media input combination. Change the inputs or choose another model.` | 当前模型不支持该操作与媒体输入组合。更换输入组合或选择支持该组合的模型。 |
| 400 | `capability_not_supported` | `One or more requested parameters are not supported by this model. Change the parameters or choose another model.` | 请求参数超出模型能力范围。按错误信息调整参数，或选择其他模型。 |
| 400 | `unsupported_media_format` | `The {media_kind} format is not supported for this model.` | 该模型不支持当前媒体格式。使用错误信息或 `error.details.allowed_mime_types` 中列出的格式；未提供列表时，查阅该模型的输入要求。 |
| 400 | `invalid_media_data` | `The media data is invalid. Provide valid media data.` | 已确认媒体数据无效，例如 base64 损坏或 data URI 结构错误。检查数据完整性和编码，重新提供有效媒体。 |
| 400 | `media_url_unreachable` | `The media URL could not be accessed. Make sure it is publicly accessible and returns valid media data.` | 媒体链接无法访问或读取。检查链接是否有效、是否允许公网访问，以及是否返回有效媒体内容。 |
| 400 | `invalid_media` | `The media input could not be processed. Check that its data or URL is valid and uses a supported format.` | 媒体输入无法处理，当前无法确认更具体原因。检查媒体数据或链接是否有效，以及格式是否受模型支持。 |
| 413 | `media_too_large` | `The {media_kind} exceeds the allowed size of {max_bytes} bytes. Reduce its size and try again.` | 其他媒体任务的媒体内容超过当前处理上限。按 `error.details.max_bytes` 或错误信息中的上限缩小媒体后再试。 |
| 413 | `request_too_large` | `The request body exceeds the 32 MiB limit. Reduce the request size and try again.` | 整个 HTTP 请求体超过 32 MiB。缩小实际发送的请求体，包括文本、参数和内联媒体编码。 |

**大小限制**

* **媒体大小**：视频任务超限返回 `media_too_large`，上传参考图片时也使用此码。具体上限见错误信息或 `error.details.max_bytes`。
* **整个请求大小**：`request_too_large` 表示 HTTP 请求体超过 **32 MiB**，包括文本、参数和内联媒体编码。只传 URL 时，链接本身计入请求体，链接指向的文件仍需满足模型的媒体限制。
* **实际大小**：`error.details.actual_bytes` 仅在完整大小已确认时提供。通过 URL 读取媒体时，若达到读取上限后停止，可能不返回该字段。

**支持格式**

以所选模型为准。先查看 `error.details.allowed_mime_types` 或错误信息中的格式列表；未提供列表时，查阅该模型的 Schema。

**文案中的占位符**

* `{media_kind}`：实际媒体类型。类型已确认时，`invalid_media_data` 和 `media_url_unreachable` 的文案也会使用 `image` 或 `video`。
* `{max_bytes}`：字节上限。
* `{allowed_formats}`：允许的格式列表。格式错误文案可能追加 `Use one of: {allowed_formats}.`

#### 生成请求与返回结果

| HTTP | `code` | `message` | 说明 |
| - | - | - | - |
| 400 | `upstream_rejected` | `The model provider rejected the request. Check the request parameters and content.` | 模型推理厂商拒绝了请求，但仅凭此码不能确定是内容违规。检查请求参数和输入内容，修改后再试。 |
| 502 | `upstream_bad_response` | `The model provider response could not be processed. Contact support with the request ID.` | 模型推理厂商已返回响应，但平台无法处理；不表示已确认没有生成结果。提供请求 ID 联系支持，不要把它当成参数错误或空结果自行判断。 |
| 400 | `doubao_real_person_required` | `This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.` | 豆包返回了特定的真人图片隐私拒绝码。先完成真人认证，再使用已激活的 `asset://` 素材；详见 [真人素材文档](https://docs.aihubmix.com/cn/api/doubao-real-person-assets.md)。 |
| 502 | `task_status_unavailable` | `The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID or request ID.` | 任务已提交给模型推理厂商，后续状态无法确认。请勿重复提交；提供请求 ID 联系支持，有任务 ID 时一并提供。 |

#### 账户与权限

| HTTP | `code` | `message` | 说明 |
| - | - | - | - |
| 401 | `authentication_failed` | `Authentication failed: invalid or missing API key.` | API Key 缺失或无效。检查 `Authorization` 请求头和 API Key。 |
| 402 | `insufficient_quota` | `Your account has insufficient quota. Add credits and try again.` | 账户额度不足。补充账户额度后再试。 |
| 403 | `permission_denied` | `You do not have permission to access this resource. Check the account, API key permissions, and IP restrictions.` | 账户或 API Key 无权访问。检查账户权限、API Key 权限和 IP 限制。 |
| 403 | `async_not_enabled` | `Asynchronous tasks are not enabled. Please go to https://console.aihubmix.com/async-tasks to activate.` | 账户未开启异步任务功能。按响应中的控制台链接开通后再试。 |

#### 服务可用性与限流

| HTTP | `code` | `message` | 说明 |
| - | - | - | - |
| 429 | `rate_limited` | `Too many requests. Reduce the request rate and try again later.` | 请求过于频繁。降低请求频率后再试。 |
| 429 | `upstream_rate_limited` | `Upstream service is rate limiting. Please retry later.` | 模型推理厂商限流。稍后再试，避免立即反复提交。 |
| 500 | `internal_error` | `An internal error occurred. Contact support with the request ID.` | 平台发生内部错误。提供请求 ID 联系支持，不需要反复修改正常输入。 |
| 502 | `upstream_unreachable` | `Upstream service is temporarily unavailable. Please retry.` | 模型推理厂商暂时不可用，可能是连接失败、厂商服务错误或响应读取失败。仅凭此码无法确认是否已产生结果；持续失败时，提供请求 ID 联系支持。 |
| 502 | `provider_unavailable` | `The model provider is unavailable. Contact support with the request or task ID.` | 模型推理厂商不可用。表中为默认文案，实际响应可能提供更具体的提示；错误类型以 `code` 为准。提供请求 ID 联系支持。 |
| 503 | `model_unavailable` | `The requested model is temporarily unavailable. Try again later or choose another model. If the problem persists, contact support with the request ID.` | 当前模型暂时不可用。稍后再试或选择其他模型；持续失败时，提供请求 ID 联系支持。 |
| 503 | `service_unavailable` | `The service is temporarily unavailable. Try again later. If the problem persists, contact support with the request ID.` | 当前服务暂时不可用。稍后重试当前操作；下载失败时重试下载，不必重新生成。 |

`provider_unavailable` 表示已明确识别的模型推理厂商故障。仅凭普通 429 或 4xx 无法确认账户额度、内容审核或参数问题。

#### 任务查询与结果下载

| HTTP | `code` | `message` | 说明 |
| - | - | - | - |
| 404 | `task_not_found` | `The task was not found.` | 任务不存在，或不属于当前账户。请检查任务 ID，并确认 API Key 属于创建任务的账户。 |
| 404 | `result_not_found` | `The result was not found.` | 结果不存在或无权读取。检查任务 ID、结果 ID 和 API Key；已知无效结果 ID 不会因为任务仍在执行而变成 409。 |
| 400 | `invalid_cursor` | `The cursor is invalid or expired. Start a new list request.` | 分页游标无效或已失效。去掉 `after`，从第一页重新查询，再使用该列表返回的新游标。 |
| 400 | `result_id_required` | `This task has multiple results. Specify result_id.` | 任务有多个结果，但未指定 `result_id`。从任务输出中选择结果，并指定对应的 `result_id`。 |
| 409 | `result_not_ready` | `The result is not available yet. Check the task status before downloading.` | 任务仍在排队或执行，结果尚未准备好。继续查询任务状态，结果就绪后再下载；不需要重新生成。 |
| 410 | `artifact_expired` | `The result has expired and is no longer available. Submit a new generation request.` | 结果已过保留期。已过期结果无法继续下载，需要时提交新的生成请求。 |
| 429 | `too_many_downloads` | `Download limit exceeded for this result.` | 下载次数达到限制。检查已保存的结果；单纯等待不保证恢复下载次数。 |

### 任务执行失败

任务创建成功后，生成失败通过 `status=failed` 和任务内的 `error` 表达。查询成功仍返回 HTTP 200。

```json theme={null}
{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "status": "failed",
  "output": [],
  "error": {
    "code": "provider_empty_output",
    "message": "The model provider completed the task without a usable result. Adjust the request or choose another model, then submit a new task."
  }
}
```

| Task `code` | `message` | 说明 |
| - | - | - |
| `provider_empty_output` | `The model provider completed the task without a usable result. Adjust the request or choose another model, then submit a new task.` | 已确认视频或其他媒体生成完成，但没有可用结果。调整请求或选择其他模型后提交新任务。 |
| `output_policy_violation` | `Generated content was rejected by the content policy.` | 生成内容未通过审核。修改提示词或输入内容后提交新任务；按现有内容审核收费规则处理，历史费用以计费记录为准。 |
| `upstream_rejected` | `The model provider rejected the request. Check the request parameters and content.` | 模型推理厂商拒绝了请求，但仅凭此码不能确定是内容违规。检查请求参数和输入内容，修改后提交新任务。 |
| `upstream_bad_response` | `The model provider response could not be processed. Contact support with the task ID.` | 平台无法处理模型推理厂商返回的响应；不表示已确认没有生成结果。提供任务 ID 联系支持。 |
| `task_status_unavailable` | `The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID.` | 任务已提交给模型推理厂商，后续状态无法确认。请勿重复提交；提供任务 ID 联系支持。 |
| `result_delivery_failed` | `The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID.` | 已有生成结果，但平台未能完成保存或交付。请勿自动重新生成；提供任务 ID 联系支持，先排查已有结果。 |
| `upstream_rate_limited` | `Upstream service is rate limiting. Please retry later.` | 模型推理厂商限流。稍后再试，避免立即反复提交。 |
| `upstream_unreachable` | `Upstream service is temporarily unavailable. Please retry.` | 任务执行期间遇到模型推理厂商连接失败、厂商服务错误或响应读取失败。仅凭此码无法确认是否已产生结果；持续失败时，提供任务 ID 联系支持。 |
| `provider_unavailable` | `The model provider is unavailable. Contact support with the request or task ID.` | 模型推理厂商不可用。表中为默认文案，实际响应可能提供更具体的提示；错误类型以 `code` 为准。提供任务 ID 联系支持。 |
| `doubao_real_person_required` | `This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.` | 豆包返回了特定的真人图片隐私拒绝码。先完成真人认证，再使用已激活的 `asset://` 素材；详见 [真人素材文档](https://docs.aihubmix.com/cn/api/doubao-real-person-assets.md)。 |
| `internal_error` | `An internal error occurred. Contact support with the task ID.` | 平台发生内部错误。提供任务 ID 联系支持，不需要反复修改正常输入。 |

媒体输入错误也可能出现在失败 Task 中，错误码含义与上方媒体输入表一致；此时查询成功的 HTTP 状态仍为 200。 媒体大小错误的 `message` 结尾使用 `submit a new task.`，提示缩小媒体后提交新任务。

`provider_empty_output` 表示已确认没有可用视频结果；`result_delivery_failed` 表示已有生成结果、保存或交付失败，遇到后者请先联系支持排查已有结果。

### 列表单条结果读取失败

图片、视频任务列表中的个别行可能附带 `output_error`：

```json theme={null}
{
  "output_error": {
    "code": "internal_error",
    "type": "server_error",
    "message": "The task output could not be read. Contact support with the request ID.",
    "tid": "req_01K0ABCDEF"
  }
}
```

该字段表示本次无法读取该行的结果。列表仍返回 HTTP 200，该行 `output=[]`，原 `id`、`status`、`error` 和分页保持不变，其他可正常读取的任务不受影响。即使 `status=completed`，也应检查 `output_error`，再判断结果是否可读取。

请提供 `output_error.tid` 联系支持；该字段未带 `tid` 时，可提供本次响应头中的请求 ID。此错误不改变任务状态或费用，也不触发 Webhook。

图片、视频列表保留已取得的 `expires_at`。统一 `/ai/v1/tasks` 列表的读取失败行可能返回 `expires_at=null`，结果仍受原保留期限制。

上述处理仅适用于单行结果无法读取且没有可用回退的情况。统一 tasks 接口整批查询失败仍返回 HTTP 错误，详情读取同类故障仍返回 HTTP 500。

相关文档：[图片接口](https://docs.aihubmix.com/cn/api/aihubmix-image-generation.md#error-codes) · [视频接口](https://docs.aihubmix.com/cn/api/aihubmix-video-generation.md#error-codes) · [异步任务](https://docs.aihubmix.com/cn/api/async-tasks.md#error-codes)

## 完整示例

以下示例完成创建、轮询和 MP4 下载。

```python Python theme={null}
import os
import time

import requests

base_url = "https://aihubmix.com"
headers = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/ai/v1/videos",
    headers=headers,
    json={
        "model": "wan2.6-t2v",
        "prompt": "A cat playing jazz on a piano",
        "duration": 5,
        "size": "1280x720",
    },
    timeout=60,
)
response.raise_for_status()
task = response.json()

while task["status"] not in {"completed", "failed", "cancelled"}:
    time.sleep(15)
    response = requests.get(
        f"{base_url}/ai/v1/videos/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] == "completed":
    result = requests.get(
        f"{base_url}/ai/v1/videos/{task['id']}/content",
        headers=headers,
        timeout=120,
    )
    result.raise_for_status()
    with open("result.mp4", "wb") as file:
        file.write(result.content)
else:
    raise RuntimeError(task.get("error") or task["status"])
```

```typescript TypeScript theme={null}
import { writeFile } from "node:fs/promises";

const baseUrl = "https://aihubmix.com";
const headers = {
  Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch(`${baseUrl}/ai/v1/videos`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "wan2.6-t2v",
    prompt: "A cat playing jazz on a piano",
    duration: 5,
    size: "1280x720",
  }),
});
if (!created.ok) throw new Error(await created.text());
let task = await created.json();

const finished = new Set(["completed", "failed", "cancelled"]);
while (!finished.has(task.status)) {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  const polled = await fetch(`${baseUrl}/ai/v1/videos/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status === "completed") {
  const result = await fetch(`${baseUrl}/ai/v1/videos/${task.id}/content`, {
    headers,
  });
  if (!result.ok) throw new Error(await result.text());
  await writeFile("result.mp4", Buffer.from(await result.arrayBuffer()));
} else {
  throw new Error(JSON.stringify(task.error ?? task.status));
}
```

## 常见问题

**视频任务应该查询 `/ai/v1/tasks/{id}` 还是视频详情接口？**

轮询使用 `/ai/v1/videos/{id}`；统一筛选任务或读取 `result_id`、`content_type` 时使用
`/ai/v1/tasks`。

**为什么 `seconds` 报参数错误？**

`/ai/v1/videos` 标准协议使用整数 `duration`，单位为秒，具体允许值由模型 Schema 决定。

**为什么 `resolution` 在部分模型中报参数错误？**

标准协议包含 `resolution` 和 `size`，具体模型会收窄字段。例如 `wan2.6-t2v` 使用
`size`，不接受 `resolution`。

**创建响应丢失后如何找回任务？**

请求 `GET /ai/v1/videos?limit=20&order=desc`，再用返回的任务 ID 查询视频详情。

**Webhook 没收到怎么办？**

确认回调地址可以公开访问并及时返回 `2xx`，然后使用视频详情接口确认最终状态。

更多跨媒体背景参阅 [异步任务](https://docs.aihubmix.com/cn/api/async-tasks.md)、
[Webhook 说明](https://docs.aihubmix.com/cn/api/async-tasks.md#webhooks) 和
[完整错误码](https://docs.aihubmix.com/cn/api/async-tasks.md#error-codes)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.