Skip to main content
AIHubMix 原生图片协议使用 /ai/v1/images 系列端点。生成接口默认同步,传入布尔值 async: true 后在后台生成,并使用同一套任务状态、Webhook 和错误结构。
使用异步图片、任务查询或 Webhook 前,需要为当前账户开启异步任务功能。未开启时, 异步任务创建请求返回 403 async_not_enabled

快速开始

下面使用 qwen-image-2.0 异步生成一张图片。
任务进入 completed 后,逐项读取 output[].content_url。该地址对应 GET /ai/v1/images/{id}/content/{result_id},客户端不需要自行拼接 result_id

接口概览

Base URL:https://aihubmix.com 认证方式:

查询模型 Schema

模型目录可以筛选已经提供请求 Schema 的文生图模型:
取得 model_id 后,查询该模型实际支持的端点:
同一模型可能同时返回 AIHubMix 原生与兼容端点。应按 path 选择原生图片接口,再读取 对应的 request.schema
不要依赖 endpoints 数组位置。完整响应字段和失败情况参阅 模型 Schema 接口

创建图片

同步生成

省略 async 或设置为 false 时,请求等待生成完成后返回任务对象:
同步请求也会保存任务记录。创建响应丢失时,可以通过图片列表找回任务。

异步生成

async 必须是布尔值 true,不能写成字符串。异步请求立即返回任务对象,生成在后台继续。 webhook_urlwebhook_events_filter 只能与 async: true 一起使用。

标准字段

标准字段集合不表示所有模型支持全部字段。字段、枚举和取值范围以该模型 /ai/v1/images/generations 端点的 request.schema 为准。

图片任务对象

同步生成完成后,或异步任务进入结束态后,接口返回以下结构:
output 项包含顺序 index、固定值 type: "file"、可选的 b64_jsoncontent_url。多图请求会按 index 返回多个结果。

状态说明

客户端可以每 15 秒查询一次,直到状态变为 completedfailedcancelled。 15 秒是客户端轮询建议,不是服务端协议限制。

查询图片任务

查询详情

图片详情接口会返回任务最新状态。异步图片轮询必须使用该接口,不要使用统一任务详情代替。

查询列表

创建响应丢失时,可以通过图片列表找回任务 ID:
列表返回查询时的任务快照,不会主动刷新活动任务状态。

统一任务接口

/ai/v1/tasks 提供图片、视频和 LLM 任务的统一只读视图。可以只查询图片任务:
统一任务列表支持 objectstatusmodelafterlimitorder。统一任务详情:
统一任务中的图片结果会额外提供 result_idcontent_type
多结果统一任务通过 /ai/v1/tasks/{id}/content/{result_id} 下载。未指定结果 ID 时返回 400 result_id_required
媒体详情接口可能在查询时更新活动任务状态,统一任务接口只返回当前快照。因此轮询使用 /ai/v1/images/{id};统一筛选和读取结果元数据时使用 /ai/v1/tasks。 任务及内容按创建任务时的 Bearer Token 隔离。

下载图片结果

任务进入 completed 后,优先直接使用媒体任务对象返回的结果字段:
  • output[].b64_json 非空:直接进行 Base64 解码。
  • output[].content_url 非空:携带创建任务时的 Bearer Token 请求该地址。
图片媒体下载路径是 /ai/v1/images/{id}/content/{result_id}。媒体任务对象不单独公开 result_id,客户端不需要自行解析或拼接,逐项使用 output[].content_url 即可。
结果可能过期,也可能存在下载次数限制。过期返回 410 artifact_expired;超过下载 次数限制返回 429 too_many_downloads。客户端应在任务完成后及时保存结果。

Webhook

Webhook 仅用于 async: true 的图片请求:
webhook_url 最长 512 字符,不能指向本机、私网或其他受限地址。省略事件过滤器时, 平台推送 completedfailedcancelled;显式传入时,数组不能为空、不能重复, 并且必须与 webhook_url 一起使用。

回调请求

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

重试与去重

平台采用至少一次投递,同一事件可能重复送达:
  • HTTP 2xx 表示接收成功。
  • HTTP 5xx、网络错误或超时会触发重试。
  • HTTP 3xx4xx 不会重试。
  • 最多投递 6 次,重试间隔依次为 1、4、16、64、256 秒。
接收端应保存 event_id,重复收到相同事件时直接返回 2xx。任务级 Webhook 本身不 携带独立签名密钥;需要签名验证时,请配置账户级 Webhook,并保留详情查询作为结果确认方式。

错误响应与错误码

error.tid 是请求追踪 ID,联系技术支持排查时请一并提供。

完整示例

以下示例完成异步创建、轮询和多图片保存。

常见问题

图片任务应该查询 /ai/v1/tasks/{id} 还是图片详情接口? 轮询使用 /ai/v1/images/{id};统一筛选任务或读取 result_idcontent_type 时使用 /ai/v1/tasks 创建响应丢失后如何找回任务? 请求 GET /ai/v1/images?limit=20&order=desc,再用返回的任务 ID 查询图片详情。 Webhook 没收到怎么办? 确认回调地址可以公开访问并及时返回 2xx,然后使用图片详情接口确认最终状态。 更多跨媒体背景参阅 异步任务Webhook 说明完整错误码