异步任务 - 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/*。LLM 任务保持原有错误合同；未指定媒体类型且尚未取得 Task 的查询继续使用通用错误合同。

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

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

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

提交 HTTP 5xx 错误反馈

请求返回 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	`image_too_large`	`The image is too large. Reduce the image size to {max_bytes} bytes or less and try again.`	图片任务的媒体内容超过当前处理上限。按 `error.details.max_bytes` 或错误信息中的上限缩小媒体后再试。
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。缩小实际发送的请求体，包括文本、参数和内联媒体编码。

大小限制

媒体大小：图片任务超限返回 image_too_large，其他媒体任务返回 media_too_large。视频任务上传参考图片时也使用 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}：字节上限。图片上限未知时，返回 The image is too large. Reduce the image size and try again.
{allowed_formats}：允许的格式列表。格式错误文案可能追加 Use one of: {allowed_formats}.

生成请求与返回结果

HTTP	`code`	`message`	说明
502	`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then try again. If the problem persists, contact support with the request ID.`	模型推理厂商已完成请求，但没有返回可用图片。调整请求或选择其他模型后再试；持续失败时，提供请求 ID 联系支持。不要仅因 HTTP 502 就无条件自动重复生成。
422	`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	模型推理厂商拦截了生成内容，且未返回可用图片。请修改提示词或输入内容后再试。本次不收取生成费用。
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://` 素材；详见真人素材文档。
504	`sync_timeout`	`Generation did not complete within the waiting period. Contact support with the request ID.`	生成未能在等待时间内完成；超时不证明请求没有执行。提供请求 ID 联系支持；不要查询未向你返回的任务 ID。
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.`	任务不存在或无权查看。图片、视频专属接口按账户检查归属；统一 `/ai/v1/tasks` 接口须使用创建任务时的 API Key。请检查任务 ID 和所用凭证。
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。

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "status": "failed",
  "output": [],
  "error": {
    "code": "result_delivery_failed",
    "message": "The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID."
  }
}

Task `code`	`message`	说明
`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task.`	模型推理厂商已完成请求，但没有返回可用图片。调整请求或选择其他模型后提交新任务；不要无条件自动重复生成。
`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_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	模型推理厂商拦截了生成内容，且未返回可用图片。请修改提示词或输入内容后提交新任务。本次不收取生成费用。
`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://` 素材；详见真人素材文档。
`sync_timeout`	`Generation timed out. Contact support with the task ID.`	生成任务超时。提供任务 ID 联系支持。
`internal_error`	`An internal error occurred. Contact support with the task ID.`	平台发生内部错误。提供任务 ID 联系支持，不需要反复修改正常输入。

媒体输入错误也可能出现在失败 Task 中，错误码含义与上方媒体输入表一致；此时查询成功的 HTTP 状态仍为 200。媒体大小错误的 message 结尾使用 submit a new task.，提示缩小媒体后提交新任务。 output_blocked 表示明确拦截且未返回可用图片，本次不收取生成费用。output_policy_violation 按现有内容审核收费规则处理。历史费用请以计费记录为准。

列表单条结果读取失败

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

{
  "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。统一 /ai/v1/tasks 列表的读取失败行可能返回 expires_at=null，结果仍受原保留期限制。图片、视频专属列表保留已取得的过期时间。上述处理仅适用于单行结果无法读取且没有可用回退的情况。统一 tasks 接口整批查询失败仍返回 HTTP 错误，详情读取同类故障仍返回 HTTP 500。相关文档：图片接口 · 视频接口 · 异步任务

完整视频示例

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 请求失败

​请求参数与媒体输入

​生成请求与返回结果

​账户与权限

​服务可用性与限流

​任务查询与结果下载

​任务执行失败

​列表单条结果读取失败

​完整视频示例

​常见问题

快速开始

三组接口如何选择

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

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

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

获取单个模型的请求 Schema

支持的模型和字段

LLM 中断恢复模型

如何创建图片任务

同步图片

异步图片

图片标准字段

如何创建视频任务

视频标准字段

媒体任务对象

状态说明

如何查询媒体任务

查询媒体详情

查询媒体列表

如何使用统一任务接口

如何下载媒体结果

下载图片

下载视频

如何使用 Webhook

回调请求

重试与去重

LLM 中断恢复如何生效

错误响应与错误码

HTTP 请求失败

请求参数与媒体输入

生成请求与返回结果

账户与权限

服务可用性与限流

任务查询与结果下载

任务执行失败

列表单条结果读取失败

完整视频示例

常见问题