异步任务 - AIHubMix

AIHubMix 提供三组任务接口：图片使用 /ai/v1/images，视频使用 /ai/v1/videos，统一任务记录使用 /ai/v1/tasks。

图片生成默认同步，传入 async: true 后异步执行。
视频生成固定异步。
图片和视频详情接口用于获取媒体任务的最新状态。
/ai/v1/tasks 提供图片、视频和 LLM 任务的统一只读视图。

豆包 Seedance 视频需要引用真人素材时，先按豆包真人素材使用指南完成本人确认和素材准备，再创建视频任务。

视频教程：异步任务

讲解异步任务的整体机制，并以异步生图为例演示完整调用流程。

前往控制台开启异步任务

使用 /ai/v1 媒体任务接口前，请先为当前账户开启异步任务功能。

未开启异步任务功能时，图片和视频任务创建请求返回 403 async_not_enabled。

快速开始

以下示例使用 wan2.6-t2v 创建视频。该模型接受 duration 和 size；不同模型的有效字段可能不同。

# 1. 创建视频任务，保存响应中的 id
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 cat playing jazz on a piano, warm lighting, cinematic shot",
    "duration": 5,
    "size": "1280x720"
  }'

# 2. 每 15 秒查询一次媒体详情
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 3. completed 后下载视频
curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

三组接口如何选择

场景	方法	路径	行为
生成图片	POST	`/ai/v1/images/generations`	默认同步，可通过 `async: true` 改为异步
查询图片详情	GET	`/ai/v1/images/{id}`	返回图片任务状态；活动任务可能在查询时更新状态
查询图片列表	GET	`/ai/v1/images`	返回图片任务快照
下载指定图片	GET	`/ai/v1/images/{id}/content/{result_id}`	下载多图任务中的指定结果
创建视频	POST	`/ai/v1/videos`	固定异步
查询视频详情	GET	`/ai/v1/videos/{id}`	返回视频任务状态；活动任务可能在查询时更新状态
查询视频列表	GET	`/ai/v1/videos`	返回视频任务快照
下载视频	GET	`/ai/v1/videos/{id}/content`	下载任务的主视频结果
获取异步媒体模型列表	GET	`/api/v1/models?type={type}&schema_checked=true`	返回已提供请求 Schema 的文生图或文生视频模型
获取模型请求 Schema	GET	`/call/schema/models/{model}/endpoints`	返回文生图或文生视频端点及其 JSON Schema
查询统一任务列表	GET	`/ai/v1/tasks`	只读查询图片、视频和 LLM 任务
查询统一任务详情	GET	`/ai/v1/tasks/{id}`	返回查询时的只读任务快照
获取统一任务结果	GET	`/ai/v1/tasks/{id}/content`	下载单产物或读取 LLM 存档
获取指定统一任务结果	GET	`/ai/v1/tasks/{id}/content/{result_id}`	下载多产物任务中的指定结果

Base URL 为 https://aihubmix.com，认证方式为 Bearer Token：

Authorization: Bearer $AIHUBMIX_API_KEY

模型列表和模型 Schema 都是公开发现接口，无需 Bearer Token。其余接口均需认证。

/ai/v1/tasks 不提供创建接口。图片和视频必须通过对应的媒体生成接口创建；LLM 恢复任务由平台在客户端中断后自动保存。

媒体接口和统一任务接口的区别

媒体详情接口与统一任务接口返回相同的任务顶层字段，但 output 项和查询行为不同：

对比项	媒体详情 `/images/{id}`、`/videos/{id}`	统一任务详情 `/tasks/{id}`
任务类型	图片或视频	图片、视频或 LLM
查询行为	活动任务可能在查询时更新状态	返回查询时的只读任务快照
媒体输出字段	`index`、`type`、`content_url`、`b64_json`	`index`、`result_id`、`type`、`content_type`、`content_url`
LLM 输出字段	不适用	`index`、`type=response`、`content_type`、`content_url`、`truncated`
访问范围	当前账户创建的对应媒体任务	当前 Bearer Token 创建的任务

因此，轮询媒体生成状态时应使用图片或视频详情接口；需要统一筛选任务、读取结果元数据或恢复 LLM 响应时使用 /ai/v1/tasks。

如何发现异步媒体模型并获取 Schema

调用流程分为两步。先从公共模型目录取得支持异步接口的文生图或文生视频模型，再用模型的 model_id 获取对应端点的请求 Schema。

获取支持异步接口的模型列表

模型目录与 Playground 使用同一数据源。type=image_generation 返回文生图模型，type=video 返回文生视频模型。增加 schema_checked=true 后，列表只包含已经提供并核对请求 Schema 的模型。

# 文生图模型
curl "https://aihubmix.com/api/v1/models?type=image_generation&schema_checked=true&sort_by=order"

# 文生视频模型
curl "https://aihubmix.com/api/v1/models?type=video&schema_checked=true&sort_by=order"

两个请求使用同一个接口。type 当前为单值筛选，获取两类模型时需要分别请求。响应为 {success, message, data}。data 中与异步媒体接入相关的字段如下。

字段	说明
`data[].model_id`	模型 ID，用于生成请求和后续 Schema 查询
`data[].model_name`	模型显示名称
`data[].types`	逗号分隔的模型类型，可能同时包含 `image_generation` 和 `llm`
`data[].input_modalities`	逗号分隔的输入模态
`data[].schema_checked`	`true` 表示该模型已经提供并核对请求 Schema

{
  "success": true,
  "message": "",
  "data": [
    {
      "model_id": "qwen-image-2.0",
      "model_name": "Qwen Image 2.0",
      "types": "image_generation",
      "input_modalities": "text,image",
      "schema_checked": true
    }
  ]
}

获取单个模型的请求 Schema

不同模型支持的字段、枚举和数值范围可能不同。提交图片或视频请求前，可以通过同一个公开接口获取指定模型当前可用的端点和请求 JSON Schema。

# 文生图模型
curl "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints"

# 文生视频模型
curl "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints"

响应中的 modality 为 image 或 video。endpoints 数组中的每一项描述一个可用调用协议。

字段	说明
`default_endpoint`	当前模型的默认端点标识
`endpoints[].endpoint`	端点标识
`endpoints[].method`	请求方法，例如 `POST`
`endpoints[].path`	实际提交路径
`endpoints[].content_types`	端点接受的内容类型
`endpoints[].lifecycle`	同步或异步模式、轮询路径和状态值
`endpoints[].request.schema`	该模型在对应端点下的完整请求 JSON Schema，包括必填字段和取值约束

同一个模型可能同时返回 /ai/v1 与 OpenAI 兼容 /v1 端点。OpenAI 兼容接口可能暂不支持最新模型，请优先使用 /ai/v1 端点。异步任务接口应按 path 选择 /ai/v1/images/generations 或 /ai/v1/videos，再读取该项的 request.schema。不要依赖 endpoints 数组位置。下面的命令可直接提取两个异步任务端点的请求 Schema。

# 文生图
curl -s "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/images/generations") | .request.schema'

# 文生视频
curl -s "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

模型不存在或尚未提供可发现端点时，接口返回 404 model_not_found。端点数据暂时不可用时返回 500 endpoints_unavailable。

支持的模型和字段

图片和视频协议都定义了跨模型标准字段，但每个模型会基于实际能力收窄字段、枚举和数值范围。调用前应通过模型 Schema 接口获取对应模型的当前参数约束。例如：

wan2.6-t2v 支持 duration、size 和 seed，不接受 resolution、aspect_ratio、frame_images、input_references 或 generate_audio。
qwen-image-2.0 支持 n、size、seed、negative_prompt、image 和 images，不接受 aspect_ratio 或 mask。

标准字段集合不代表所有模型支持全部字段。传入当前模型不支持的字段会返回参数错误。

LLM 中断恢复模型

当前支持以下模型：

gpt-5.6-sol
gpt-5.5-pro
gpt-5.4-pro
gpt-5.2-pro
claude-fable-5
claude-opus-5

支持范围可能调整，请以本页清单为准。使用中断恢复还需要当前账户已开启异步任务功能。任一条件不满足时，原 LLM 请求仍会正常执行，但客户端断开后不会保存恢复任务。

如何创建图片任务

同步图片

省略 async 或设置为 false 时，接口会等待生成完成并返回任务对象：

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

同步图片任务也会保存任务记录。客户端连接中断或创建响应丢失时，可以通过 GET /ai/v1/images 查找对应任务。

异步图片

将 async 设置为布尔值 true 后，接口会立即返回任务对象，生成在后台继续：

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 2,
    "size": "1024x1024",
    "async": true
  }'

使用 GET /ai/v1/images/{id} 查询异步图片任务。完成后，直接请求每个 output 项中的 content_url；该 URL 已包含对应图片的 result_id。

图片请求中的 async 必须是布尔值。webhook_url 和 webhook_events_filter 仅能与 async: true 一起使用。

图片标准字段

字段	类型	必填	说明
`model`	string	是	模型名称
`prompt`	string	是	图片描述，不能为空
`n`	integer/null	否	图片数量，最小值 `1`，默认 `1`
`size`	string/null	否	`{width}x{height}`，例如 `1024x1024`
`aspect_ratio`	string/null	否	宽高比；与 `size` 二选一
`seed`	integer/null	否	随机种子
`negative_prompt`	string/null	否	负向提示词
`image`	string/object	否	单张输入图片，可以是 URL、Data URI、Base64 或 `{url}` 对象
`images`	array/null	否	多张输入图片
`mask`	string/object	否	图片编辑蒙版
`output_format`	string/null	否	`png`、`jpeg` 或 `webp`，默认 `png`
`response_format`	string/null	否	`url` 或 `b64_json`，默认 `url`
`async`	boolean	否	设为 `true` 时异步执行
`webhook_url`	string	否	HTTPS 回调地址，最长 512 字符
`webhook_events_filter`	string[]	否	`completed`、`failed`、`cancelled` 的非空子集
`extra`	object/null	否	具体模型的扩展参数

如何创建视频任务

视频请求始终异步，不支持通过 Prefer: wait 改为同步等待。标准协议使用整数 duration 表示秒数：

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"
  }'

视频标准字段

字段	类型	必填	说明
`model`	string	是	模型名称
`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	否	具体模型的扩展参数

input_references 项的结构：

{
  "type": "image_url",
  "url": "https://example.com/reference.png"
}

type 可为 image_url、video_url 或 audio_url。 frame_images 项的结构：

{
  "frame_type": "first_frame",
  "image_url": {
    "url": "https://example.com/first-frame.png"
  }
}

frame_type 可为 first_frame 或 last_frame。

媒体任务对象

图片和视频专属接口返回以下结构：

{
  "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": null
}

字段	类型	说明
`id`	string	平台任务 ID
`object`	string	`image` 或 `video`
`model`	string	模型名称
`status`	string	当前任务状态
`output`	array	已生成的结果；尚无结果时为空数组
`error`	object/null	失败信息，可含 `code`、`message` 和 `upstream_detail`
`created_at`	integer	创建时间，Unix 秒
`completed_at`	integer/null	最终状态时间，Unix 秒
`expires_at`	null	媒体专属接口当前返回 `null`

媒体 output 项：

字段	类型	说明
`index`	integer	结果顺序，从 `0` 开始
`type`	string	当前为 `file`
`content_url`	string/null	结果下载地址
`b64_json`	string/null	Base64 编码的图片结果

状态说明

状态	是否结束	说明
`pending`	否	平台已接收任务，等待执行
`in_progress`	否	任务正在执行
`completed`	是	任务完成，可读取 `output`
`failed`	是	任务失败，原因见 `error`
`cancelled`	是	任务已取消

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

如何查询媒体任务

查询媒体详情

# 图片
curl https://aihubmix.com/ai/v1/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 视频
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

媒体详情接口可返回更新后的任务状态，因此媒体轮询应使用对应的图片或视频详情接口。

查询媒体列表

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

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` 处理

{
  "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"
}

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

如何使用统一任务接口

统一任务接口支持以下筛选条件：

curl "https://aihubmix.com/ai/v1/tasks?object=video&status=in_progress&limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

参数	类型	默认值	说明
`object`	string	-	`llm`、`image` 或 `video`
`status`	string	-	`pending`、`in_progress`、`completed`、`failed` 或 `cancelled`
`model`	string	-	按模型名称精确筛选
`after`	string	-	分页游标
`limit`	integer	`20`	范围 `1` 到 `100`
`order`	string	`desc`	`asc` 或 `desc`

统一任务详情：

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

媒体任务的统一 output 项：

{
  "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。

统一任务列表、详情和内容接口按创建任务时的 Bearer Token 隔离。同一账户下的其他 API Key 不能读取该任务。

如何下载媒体结果

下载图片

图片完成后，逐项请求媒体任务对象中的 output[].content_url：

curl "{content_url}" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.png

图片的媒体下载路径为 /ai/v1/images/{id}/content/{result_id}。媒体任务对象不单独公开 result_id，客户端直接使用 content_url 即可。当 b64_json 非空时，可以直接对该字段进行 Base64 解码。

下载视频

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

结果可能过期，并且可能存在下载次数限制。过期返回 410 artifact_expired，超过下载次数限制返回 429 too_many_downloads。

如何使用 Webhook

异步图片和视频支持任务级 Webhook：

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_events_filter": ["completed", "failed"]
  }'

webhook_url 最长 512 字符，并且不能指向本机、私网或其他受限地址。省略 webhook_events_filter 时，平台推送 completed、failed 和 cancelled；显式传入时，数组不能为空、不能重复，并且必须与 webhook_url 一起使用。未在请求中传入 webhook_url 时，异步图片和视频会尝试使用账户中配置的默认回调地址。无效的账户默认地址会被忽略，不会阻止任务创建。

回调请求

{
  "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`	回调事件 ID，用于去重
`event_type`	`completed`、`failed` 或 `cancelled`
`created_at`	RFC 3339 格式的事件时间
`data.task_id`	平台任务 ID
`data.status`	当前最终状态
`data.model`	模型名称
`data.results[].url`	完成时可能返回的结果下载地址
`data.error`	失败时可能返回的错误信息

results 仅在结果已存档时出现，下载仍需 Bearer Token。

重试与去重

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

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

接收端应保存 event_id，重复收到相同事件时直接返回 2xx。

任务级 Webhook 本身不携带独立签名密钥。需要签名验证时，请配置账户级 Webhook 订阅，并保留任务详情查询作为结果确认方式。

LLM 中断恢复如何生效

LLM 中断恢复用于取回客户端断开连接后的最终响应。请求方式、流式行为和响应格式保持不变，也不会在请求开始时预先返回任务 ID。以下条件需要同时满足：

条件	说明
账户已开启异步任务功能	在 AIHubMix 控制台为当前账户开启
模型支持中断恢复	当前模型在 LLM 中断恢复模型清单中
接口受支持	Chat Completions、Anthropic Messages、Responses API 或 Gemini `generateContent` / `streamGenerateContent`
客户端中断	客户端取消、网络断开或调用方取消请求

平台仅在检测到响应未完整交付且客户端已经断开时创建恢复任务，并保存最终 JSON 或 SSE。正常完成并完整交付给客户端的 LLM 请求不会创建恢复任务。 LLM 响应头包含 X-Aihubmix-Request-Id。客户端应尽早保存该值，以便在控制台中定位对应请求。公开任务 API 当前不能按请求 ID 过滤；可以按模型和创建时间查询最近的 LLM 任务：

curl "https://aihubmix.com/ai/v1/tasks?object=llm&model={model}&order=desc&limit=20" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

curl https://aihubmix.com/ai/v1/tasks/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

LLM 任务的统一 output 项包含 type=response、content_type、content_url 和 truncated。GET /ai/v1/tasks/{id}/content 返回保存的原始 JSON 或 SSE。

LLM 中断恢复任务当前不发送任务级 Webhook。客户端中断不会停止平台继续处理请求，该次调用仍按原接口规则计费。

错误响应与错误码

本节适用于 /ai/v1/images/*、/ai/v1/videos/*，以及 /ai/v1/tasks/* 中 object=image 或 object=video 的媒体任务。客户端需要同时处理 HTTP 非 2xx 响应和 HTTP 200、status=failed 的任务终态。

{
  "error": {
    "message": "Task not found.",
    "type": "invalid_request_error",
    "code": "task_not_found",
    "tid": "req_01K0ABCDEF"
  }
}

提交 HTTP 5xx 错误反馈

请求返回 HTTP 5xx 时，请提交反馈并附上 error.tid。

HTTP 非 2xx 错误

invalid_request 和 schema_violation 行展示的是兜底 message。服务能够定位具体字段或参数约束时会返回动态 message；客户端应以 code 判断错误类型，不要依赖 message 固定匹配。

HTTP	`code`	`message`	说明
400	`invalid_request`	`Invalid request. Check the request body and parameters.`（兜底模板；实际可能返回动态 message）	公共请求体、字段类型或列表参数不正确；此 code 的 message 不是固定值，能够定位字段时会返回更具体的动态 message
400	`model_not_found`	`The requested model is not available. Check the model name and your account access.`	模型不存在、不可用，或当前账户无权访问
400	`schema_violation`	`Invalid request: one or more parameters are invalid.`（兜底模板；实际可能返回动态 message）	请求不符合当前模型的参数 Schema；此 code 的 message 不是固定值，能够定位字段或约束时会返回字段级动态 message
400	`capability_not_supported`	`The requested parameters are not supported for this model.`	当前模型不支持请求中的字段、数量或参数上限
400	`media_form_unsupported`	动态媒体提示，见下文	图片、视频、参考图或首尾帧的格式、数据、URL 或大小无法处理
400	`result_id_required`	`This task has multiple results. Specify result_id.`	任务包含多个结果，下载时未指定 `result_id`
400	`upstream_rejected`	`Upstream service rejected the request.`	模型推理厂商拒绝了创建请求
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	API Key 缺失或无效
402	`insufficient_quota`	`Insufficient quota.`	AIHubMix 账户可用额度不足
403	`permission_denied`	`You do not have permission to access this resource.`	当前账户、API Key 或访问来源无权使用该资源
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to <console-url>/async-tasks to activate.`	当前账户未开通异步任务功能；控制台地址会按请求站点生成
404	`task_not_found`	`Task not found.`	任务不存在、分页游标无效，或当前账户无权查看
404	`result_not_found`	`Result not found.`	结果不存在、尚未就绪、结果 ID 不匹配，或当前账户无权下载
410	`artifact_expired`	`The result has expired.`	结果已超过保留期
413	`request_too_large`	`Request body is too large. Reduce the request size and try again.`	整体请求体超过 32 MiB
413	`image_too_large`	`Image is too large. Reduce the image size and try again.`	图片接口解码后的单张图片超过模型处理上限
422	`image_not_generated`	`The expected image was not generated.`	模型推理厂商完成请求，但没有返回可交付图片
429	`rate_limited`	`Too many requests. Please slow down and retry.`	AIHubMix 对当前账户或 API Key 限流
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	模型推理厂商返回限流错误
429	`too_many_downloads`	`Download limit exceeded for this result.`	单个结果达到下载次数上限
500	`internal_error`	`Internal error. Please retry.`	服务发生调用方无法修复的内部错误
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	无法连接模型推理厂商，或无法完整读取其响应
502	`upstream_bad_response`	`Upstream service returned an invalid response.`	模型推理厂商返回了平台无法处理的响应
502	`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	模型推理厂商返回服务错误
503	`model_unavailable`	`The requested model is temporarily unavailable.`	所选模型暂时不可用
503	`service_unavailable`	`Service is temporarily unavailable. Please retry.`	查询、下载或结果服务暂时不可用
504	`sync_timeout`	`Generation timed out. Please retry.`	同步生成没有在等待时间内完成

media_form_unsupported 的 message 会根据已确认的原因生成，常见模板如下：

场景	`message`
格式不支持	`Unsupported <media-kind> format: <detected-format>. Supported formats for this model: <allowed-formats>.`
图片或视频数据无效	`The <media-kind> data is invalid. Provide a valid <media-kind>.`
媒体类型无法确定时的数据无效	`The media data is invalid. Provide valid media data.`
媒体 URL 无法访问	`The <media-kind> URL could not be accessed. Make sure it is publicly accessible and returns a valid <media-kind>.`
媒体无法解码	`Unable to process the <media-kind>. Check that the <media-kind> data or URL is valid and supported.`
非图片任务的媒体超过限制	`The <media-kind> is too large. Reduce the <media-kind> size and try again.`
无法安全确定具体原因	`Unable to process the media. Check that the media data or URL is valid and supported.`

例如，模型允许 PNG、JPEG、WebP、HEIC 和 HEIF 时，GIF 图片返回：

Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF.

HTTP 200 + Task `status=failed`

查询请求成功不代表生成成功。任务为 failed 时，客户端从任务对象的 error.code 和 error.message 读取失败原因：

{
  "id": "task_01K0ABCDEF",
  "status": "failed",
  "error": {
    "code": "media_form_unsupported",
    "message": "Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF."
  }
}

Task `code`	`message`	说明
`media_form_unsupported`	动态媒体提示，同上	异步任务中的媒体格式、数据、URL、解码或大小错误
`image_too_large`	`Image is too large. Reduce the image size and try again.`	异步图片任务的输入图片超过限制
`image_not_generated`	`The expected image was not generated.`	模型推理厂商没有返回可交付图片
`upstream_rejected`	`Upstream service rejected the request.`	模型推理厂商拒绝创建请求
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	模型推理厂商返回限流错误
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	创建任务时无法连接模型推理厂商，或无法完整读取其响应
`upstream_bad_response`	`Upstream service returned an invalid response.`	模型推理厂商响应无法处理
`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	模型推理厂商创建或执行任务失败
`upstream_empty_output`	`The upstream service completed without producing a usable result. Please retry.`	模型推理厂商完成任务，但没有产生可交付结果
`output_policy_violation`	`Generated content was rejected by the content policy.`	生成内容未通过内容安全策略
`sync_timeout`	`Generation timed out. Please retry.`	等待生成结果超时
`internal_error`	`Internal error. Please retry.`	异步任务处理发生内部错误

完整视频示例

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"])

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/images/{id}，视频查询 /ai/v1/videos/{id}。/ai/v1/tasks/{id} 返回只读快照。 为什么视频请求中的 seconds 报参数错误？ /ai/v1/videos 标准协议使用整数 duration，单位为秒。具体允许值由对应模型支持的参数决定。 为什么 resolution 在部分视频模型中报参数错误？ 标准视频协议包含 resolution 和 size，但具体模型会收窄字段。例如 wan2.6-t2v 使用 size，不接受 resolution。 创建响应丢失后如何找回媒体任务？ 图片请求 GET /ai/v1/images，视频请求 GET /ai/v1/videos。列表支持 after、limit 和 order 分页参数。 为什么两种详情接口的 output 字段不同？ 媒体详情接口提供直接下载所需的简化字段；统一任务接口额外提供 result_id 和 content_type，并为 LLM 存档提供 truncated。 Webhook 没收到怎么办？ 确认回调地址可以公开访问并及时返回 2xx，然后使用媒体详情接口查询最终状态。

更新时间：2026-08-12

视频教程：异步任务

前往控制台开启异步任务

​快速开始

​三组接口如何选择

​媒体接口和统一任务接口的区别

​如何发现异步媒体模型并获取 Schema

​获取支持异步接口的模型列表

​获取单个模型的请求 Schema

​支持的模型和字段

​LLM 中断恢复模型

​如何创建图片任务

​同步图片

​异步图片

​图片标准字段

​如何创建视频任务

​视频标准字段

​媒体任务对象

​状态说明

​如何查询媒体任务

​查询媒体详情

​查询媒体列表

​如何使用统一任务接口

​如何下载媒体结果

​下载图片

​下载视频

​如何使用 Webhook

​回调请求

​重试与去重

​LLM 中断恢复如何生效

​错误响应与错误码

提交 HTTP 5xx 错误反馈

​HTTP 非 2xx 错误

​HTTP 200 + Task status=failed

​完整视频示例

​常见问题

快速开始

三组接口如何选择

媒体接口和统一任务接口的区别

如何发现异步媒体模型并获取 Schema

获取支持异步接口的模型列表

获取单个模型的请求 Schema

支持的模型和字段

LLM 中断恢复模型

如何创建图片任务

同步图片

异步图片

图片标准字段

如何创建视频任务

视频标准字段

媒体任务对象

状态说明

如何查询媒体任务

查询媒体详情

查询媒体列表

如何使用统一任务接口

如何下载媒体结果

下载图片

下载视频

如何使用 Webhook

回调请求

重试与去重

LLM 中断恢复如何生效

错误响应与错误码

HTTP 非 2xx 错误

HTTP 200 + Task `status=failed`

完整视频示例

常见问题