Skip to main content
视频生成、批量图片生成这类请求的耗时通常超过一次 HTTP 连接的合理等待时间;长文本生成过程中客户端一旦断开,已经产生的响应也无法再取回。 异步任务(Async Tasks)把这三类场景统一到同一个任务对象上:图片、视频通过生成接口创建任务并立即返回 task_id,客户端中断的 LLM 请求由平台继续完成并保存最终响应。三者共用相同的任务状态、查询接口和结果下载流程。
请使用创建任务时的同一个 API Key 查询任务和下载结果。任务按 API Key 隔离,即使两个 Key 属于同一账户,也不能互相读取任务。

前往控制台开启异步任务

创建异步图片或视频前,请先为当前账户开启异步任务功能。控制台暂未显示该入口时,请联系 AIHubMix 技术支持。
未开启异步任务功能时,媒体任务创建请求返回 403 async_not_enabled。LLM 请求不会因此报错,但客户端中断后无法找回最终响应。

1. 快速开始

图片和视频异步任务的完整流程分为三步:

2. 同步调用与异步任务的对比

同步调用在一次 HTTP 响应内返回结果,连接中断后结果无法找回。异步任务把结果保存在平台侧,task_id 可以在结果过期前用同一个 API Key 重新查询和下载,适用于耗时较长的生成请求,以及需要在中断后取回最终响应的长文本输出。

3. 接口概览

Base URL:https://aihubmix.com,认证方式为 Bearer Token:
/ai/v1/tasks 是只读的统一查询入口,不提供 POST /ai/v1/tasks。图片和视频分别通过对应的生成接口创建;满足 LLM 中断恢复条件的请求会在客户端中断后自动记录为 llm 任务。

4. 支持的模型

异步任务按任务类型划分支持范围,调用时无需增加额外参数。

4.1 异步图片

4.2 异步视频

4.3 LLM 中断恢复

支持范围会持续扩展,本表随之更新。

5. 如何创建异步任务

5.1 异步图片

图片接口默认同步返回。将 async 设置为 true 后,接口会立即返回任务对象,生成过程在后台继续执行。
async 必须是布尔值。未传或设置为 false 时,图片接口保持同步行为。

5.2 异步视频

视频接口始终异步。创建成功后会返回 pendingin_progress 状态,不支持通过 Prefer: wait 改为同步等待。

5.3 公共参数

示例中的 modelpromptnsecondssize 是常见模型参数,各模型支持的字段与取值以对应模型的 API 文档为准,视频模型可参考视频生成文档。下表只说明所有异步任务共用的参数。
图片任务只有在 async: true 时才能使用 Webhook。省略 webhook_events_filter 时,平台会推送 completedfailedcancelled 三种最终状态;传入时必须与 webhook_url 一起使用,并且不能为空、不能重复。

6. LLM 中断恢复如何生效

LLM 中断恢复用于取回客户端断开连接后的最终响应。该能力复用现有的 LLM 请求方式,流式行为和响应格式保持不变,无需调用额外的创建接口,也不会预先返回 task_id

6.1 生效条件

以下条件必须同时满足: 支持的接口:
调用时无需传入额外字段。支持范围见 4.3 LLM 中断恢复;表中未列出的模型,可在正式接入前使用一条低成本请求完成中断恢复验证,验证请求仍会正常计费。任一条件不满足时,请求仍会正常执行,客户端中断后不会生成 llm 任务。

6.2 中断后的执行流程

正常完成且成功返回给客户端的 LLM 请求不会创建任务,也不会出现在任务列表中。中断请求会在最终响应保存完成后出现在列表中,因此处理期间可能暂时查询不到。

6.3 定位对应的中断请求

LLM 响应头会返回 X-Aihubmix-Request-Id。客户端收到响应头后应立即保存该值;发生中断后,可在 AIHubMix 控制台的异步任务列表中使用该请求 ID 查找对应任务。 公开任务 API 当前不支持按请求 ID 过滤。未保存请求 ID 时,只能使用创建请求时的同一个 API Key,按模型和创建时间查找:
同一个 API Key 并发发起多个相同模型请求时,仅凭模型和创建时间无法保证精确对应。需要可靠恢复时,请保存 X-Aihubmix-Request-Id 并通过控制台查找;未取得响应头时,应避免将列表中的最新任务直接认定为本次请求。
LLM 中断恢复任务当前不发送 Webhook,请通过任务列表查询结果。客户端中断不会停止平台继续处理请求,该次调用仍按原 LLM 接口规则计费。

7. 任务对象与状态

所有任务使用统一响应结构:
output 中的结果字段:

7.1 状态说明

建议每 15 秒查询一次,直到状态变为 completedfailedcancelled
failedcancelled 任务也可能包含已经生成的部分结果。判断是否有结果时,除状态外还应检查 output 是否为空。

8. 如何查询任务

8.1 查询任务详情

该接口返回查询时的最新任务信息。查询操作不会改变任务,任务状态由平台自动更新。

8.2 查询任务列表

创建响应丢失,或者需要批量查看历史任务时,可以通过列表接口找回 task_id
响应示例:
继续请求下一页:

9. 如何获取任务结果

9.1 单产物任务

output 只有一个文件时,可以直接访问:
也可以直接使用 output[0].content_url。下载响应的 Content-Typeoutput[0].content_type 一致。

9.2 多产物任务

output 包含多个文件时,必须指定对应的 result_id
多产物任务未指定 result_id 时,接口返回 400 result_id_required

9.3 LLM 响应任务

满足 LLM 中断恢复条件并保存响应后,任务的 objectllmoutput 项的 typeresponse。内容类型可能是:
  • application/json:普通 JSON 响应
  • text/event-stream:保存的 SSE 流式响应
截断标记位于任务详情的 output[0].truncated。值为 true 时,表示保存的响应因大小限制被截断。GET /ai/v1/tasks/{task_id}/content 返回原始 JSON 或 SSE 内容,内容外不再包装 truncated 字段,因此应先查询任务详情再读取内容。
结果可能过期,并且可能存在下载次数限制。请在 expires_at 之前及时保存。过期返回 410 artifact_expired,超过下载次数限制返回 429 too_many_downloads

10. 如何使用 Webhook

当前支持在创建异步任务时提交任务级 Webhook。需要任务完成后由 AIHubMix 主动通知时,请在异步图片或视频请求体中传入 webhook_url 和可选的 webhook_events_filter
回调地址必须使用 HTTPS,且不能指向本机、私网或其他受限地址。

10.1 回调请求

AIHubMix 会向回调地址发送 POST 请求:
results 中的 URL 仍需携带创建任务时的 API Key 才能访问。

10.2 重试与去重

平台会至少尝试投递一次回调,因此同一个事件可能被重复发送:
  • HTTP 2xx 表示接收成功。
  • HTTP 5xx、网络错误或超时会触发重试。
  • HTTP 3xx4xx 不会重试。
  • 最多投递 6 次,重试间隔依次为 1、4、16、64、256 秒。
接收端应保存 event_id。再次收到相同 event_id 时,跳过业务逻辑并直接返回 2xx
当前任务级 Webhook 不提供可配置的独立签名凭据。收到通知后,应使用创建任务时的 API Key 请求 GET /ai/v1/tasks/{task_id},以查询结果为准。

11. 错误响应与错误码

错误响应使用统一结构:

12. 完整示例

创建视频任务、轮询状态、下载全部结果的完整流程:

常见问题

建议多久查询一次任务状态? 建议每 15 秒查询一次,避免高频轮询。使用 Webhook 时也应保留低频查询作为备用。 创建响应丢失后如何找回任务? 使用创建任务时的同一个 API Key 请求 GET /ai/v1/tasks,可以按 objectmodelstatus 缩小范围。 为什么同一账户的另一个 API Key 查不到任务? 任务按 API Key 隔离。查询、下载和列表请求都必须使用创建任务时的同一个 Key。 为什么任务失败了但 output 不是空数组? 部分模型可能在整体失败或取消前已经生成了可交付结果。只要 output 中存在 content_urlb64_json,就可以按对应方式获取。 Webhook 没收到怎么办? 确认回调地址能公开访问、使用 HTTPS,并在 10 秒内返回 2xx。无论是否使用 Webhook,都可以通过 GET /ai/v1/tasks/{task_id} 查询最终状态。 LLM 中断恢复需要修改现有代码吗? 不需要。请求方式、流式行为和响应格式保持不变。建议保存响应头 X-Aihubmix-Request-Id,以便中断后在控制台精确定位对应任务。
更新时间:2026-07-28