task_id,客户端中断的 LLM 请求由平台继续完成并保存最终响应。三者共用相同的任务状态、查询接口和结果下载流程。
请使用创建任务时的同一个 API Key 查询任务和下载结果。任务按 API Key 隔离,即使两个 Key 属于同一账户,也不能互相读取任务。
前往控制台开启异步任务
创建异步图片或视频前,请先为当前账户开启异步任务功能。控制台暂未显示该入口时,请联系 AIHubMix 技术支持。
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 异步视频
视频接口始终异步。创建成功后会返回pending 或 in_progress 状态,不支持通过 Prefer: wait 改为同步等待。
5.3 公共参数
示例中的model、prompt、n、seconds 和 size 是常见模型参数,各模型支持的字段与取值以对应模型的 API 文档为准,视频模型可参考视频生成文档。下表只说明所有异步任务共用的参数。
图片任务只有在
async: true 时才能使用 Webhook。省略 webhook_events_filter 时,平台会推送 completed、failed 和 cancelled 三种最终状态;传入时必须与 webhook_url 一起使用,并且不能为空、不能重复。6. LLM 中断恢复如何生效
LLM 中断恢复用于取回客户端断开连接后的最终响应。该能力复用现有的 LLM 请求方式,流式行为和响应格式保持不变,无需调用额外的创建接口,也不会预先返回task_id。
6.1 生效条件
以下条件必须同时满足:
支持的接口:
调用时无需传入额外字段。支持范围见 4.3 LLM 中断恢复;表中未列出的模型,可在正式接入前使用一条低成本请求完成中断恢复验证,验证请求仍会正常计费。任一条件不满足时,请求仍会正常执行,客户端中断后不会生成
llm 任务。6.2 中断后的执行流程
6.3 定位对应的中断请求
LLM 响应头会返回X-Aihubmix-Request-Id。客户端收到响应头后应立即保存该值;发生中断后,可在 AIHubMix 控制台的异步任务列表中使用该请求 ID 查找对应任务。
公开任务 API 当前不支持按请求 ID 过滤。未保存请求 ID 时,只能使用创建请求时的同一个 API Key,按模型和创建时间查找:
7. 任务对象与状态
所有任务使用统一响应结构:output 中的结果字段:
7.1 状态说明
建议每 15 秒查询一次,直到状态变为
completed、failed 或 cancelled。
failed 或 cancelled 任务也可能包含已经生成的部分结果。判断是否有结果时,除状态外还应检查 output 是否为空。8. 如何查询任务
8.1 查询任务详情
8.2 查询任务列表
创建响应丢失,或者需要批量查看历史任务时,可以通过列表接口找回task_id:
响应示例:
继续请求下一页:
9. 如何获取任务结果
9.1 单产物任务
output 只有一个文件时,可以直接访问:
output[0].content_url。下载响应的 Content-Type 与 output[0].content_type 一致。
9.2 多产物任务
output 包含多个文件时,必须指定对应的 result_id:
result_id 时,接口返回 400 result_id_required。
9.3 LLM 响应任务
满足 LLM 中断恢复条件并保存响应后,任务的object 为 llm,output 项的 type 为 response。内容类型可能是:
application/json:普通 JSON 响应text/event-stream:保存的 SSE 流式响应
output[0].truncated。值为 true 时,表示保存的响应因大小限制被截断。GET /ai/v1/tasks/{task_id}/content 返回原始 JSON 或 SSE 内容,内容外不再包装 truncated 字段,因此应先查询任务详情再读取内容。
10. 如何使用 Webhook
当前支持在创建异步任务时提交任务级 Webhook。需要任务完成后由 AIHubMix 主动通知时,请在异步图片或视频请求体中传入webhook_url 和可选的 webhook_events_filter:
10.1 回调请求
AIHubMix 会向回调地址发送POST 请求:
results 中的 URL 仍需携带创建任务时的 API Key 才能访问。
10.2 重试与去重
平台会至少尝试投递一次回调,因此同一个事件可能被重复发送:- HTTP
2xx表示接收成功。 - HTTP
5xx、网络错误或超时会触发重试。 - HTTP
3xx和4xx不会重试。 - 最多投递 6 次,重试间隔依次为 1、4、16、64、256 秒。
event_id。再次收到相同 event_id 时,跳过业务逻辑并直接返回 2xx。
11. 错误响应与错误码
错误响应使用统一结构:12. 完整示例
创建视频任务、轮询状态、下载全部结果的完整流程:常见问题
建议多久查询一次任务状态? 建议每 15 秒查询一次,避免高频轮询。使用 Webhook 时也应保留低频查询作为备用。 创建响应丢失后如何找回任务? 使用创建任务时的同一个 API Key 请求GET /ai/v1/tasks,可以按 object、model 和 status 缩小范围。
为什么同一账户的另一个 API Key 查不到任务?
任务按 API Key 隔离。查询、下载和列表请求都必须使用创建任务时的同一个 Key。
为什么任务失败了但 output 不是空数组?
部分模型可能在整体失败或取消前已经生成了可交付结果。只要 output 中存在 content_url 或 b64_json,就可以按对应方式获取。
Webhook 没收到怎么办?
确认回调地址能公开访问、使用 HTTPS,并在 10 秒内返回 2xx。无论是否使用 Webhook,都可以通过 GET /ai/v1/tasks/{task_id} 查询最终状态。
LLM 中断恢复需要修改现有代码吗?
不需要。请求方式、流式行为和响应格式保持不变。建议保存响应头 X-Aihubmix-Request-Id,以便中断后在控制台精确定位对应任务。
更新时间:2026-07-28