/ai/v1/images 系列端点。生成接口默认同步,传入布尔值
async: true 后在后台生成,并使用同一套任务状态、Webhook 和错误结构。
快速开始
下面使用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 后,查询该模型实际支持的端点:
path 选择原生图片接口,再读取
对应的 request.schema:
endpoints 数组位置。完整响应字段和失败情况参阅
模型 Schema 接口。
创建图片
同步生成
省略async 或设置为 false 时,请求等待生成完成后返回任务对象:
异步生成
async 必须是布尔值 true,不能写成字符串。异步请求立即返回任务对象,生成在后台继续。
webhook_url 和 webhook_events_filter 只能与 async: true 一起使用。
标准字段
图片任务对象
同步生成完成后,或异步任务进入结束态后,接口返回以下结构:output 项包含顺序 index、固定值 type: "file"、可选的 b64_json 和
content_url。多图请求会按 index 返回多个结果。
状态说明
客户端可以每 15 秒查询一次,直到状态变为
completed、failed 或 cancelled。
15 秒是客户端轮询建议,不是服务端协议限制。
查询图片任务
查询详情
查询列表
创建响应丢失时,可以通过图片列表找回任务 ID:统一任务接口
/ai/v1/tasks 提供图片、视频和 LLM 任务的统一只读视图。可以只查询图片任务:
object、status、model、after、limit 和 order。统一任务详情:
result_id 和 content_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 即可。
Webhook
Webhook 仅用于async: true 的图片请求:
webhook_url 最长 512 字符,不能指向本机、私网或其他受限地址。省略事件过滤器时,
平台推送 completed、failed 和 cancelled;显式传入时,数组不能为空、不能重复,
并且必须与 webhook_url 一起使用。
回调请求
event_id 用于去重;data.error 在失败时可能出现;data.results 只在结果已存档时出现,
下载仍需 Bearer Token。
重试与去重
平台采用至少一次投递,同一事件可能重复送达:- HTTP
2xx表示接收成功。 - HTTP
5xx、网络错误或超时会触发重试。 - HTTP
3xx和4xx不会重试。 - 最多投递 6 次,重试间隔依次为 1、4、16、64、256 秒。
event_id,重复收到相同事件时直接返回 2xx。任务级 Webhook 本身不
携带独立签名密钥;需要签名验证时,请配置账户级 Webhook,并保留详情查询作为结果确认方式。
错误响应与错误码
error.tid 是请求追踪 ID,联系技术支持排查时请一并提供。
完整示例
以下示例完成异步创建、轮询和多图片保存。常见问题
图片任务应该查询/ai/v1/tasks/{id} 还是图片详情接口?
轮询使用 /ai/v1/images/{id};统一筛选任务或读取 result_id、content_type 时使用
/ai/v1/tasks。
创建响应丢失后如何找回任务?
请求 GET /ai/v1/images?limit=20&order=desc,再用返回的任务 ID 查询图片详情。
Webhook 没收到怎么办?
确认回调地址可以公开访问并及时返回 2xx,然后使用图片详情接口确认最终状态。
更多跨媒体背景参阅 异步任务、
Webhook 说明 和
完整错误码。