图片生成 API

快速开始

认证方式

所有请求需在 Header 中携带 Bearer Token：

Authorization: Bearer YOUR_API_KEY

接口端点

回调通知 (callback_url)

在创建请求中传入 callback_url 后，任务进入 completed 或 failed 终态时，我们会向该地址发起一次 HTTP POST。请求头仅包含 Content-Type: application/json，无签名头。失败会自动重试 3 次（指数退避 1s/2s/4s，单次超时 10s）；如果仍未成功，后台会在 30 分钟内继续补偿重发，直到接收端返回 2xx。

Payload 结构

POST {your callback_url}
Content-Type: application/json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "model": "<provider>/<model_name>",
    "state": "completed" | "failed",
    "param": "<JSON string>",            // request params, JSON.parse once
    "resultJson": "<JSON string> | null", // result object, JSON.parse once
    "failCode": null | "CONTENT_MODERATION | INVALID_INPUT | INSUFFICIENT_BALANCE | UPSTREAM_BUSY | UPSTREAM_FAILED | TIMEOUT | INTERNAL_ERROR | OTHER",
    "failMsg": null | "string",
    "retryable": true | false,           // present when state=failed: safe to retry/fallback
    "costTime": 12345,                    // duration in ms
    "completeTime": 1705123465000,        // ms epoch
    "createTime": 1705123450000           // ms epoch
  }
}

注意：data.param 与 data.resultJson 都是 JSON 字符串，使用前必须 JSON.parse 一次才能拿到对象。

图片任务：JSON.parse(data.resultJson) 后的结构

{
  "resultUrls": [
    "https://r2.apimodels.app/images/xxx.png"
  ]
}

resultUrls 为已上传至 Cloudflare R2 的图片 URL 数组。多图模型（如 SparkPix Image Edit、n>1 的 GPT Image 2 Lite）会返回多个；state=failed 时通常为 null 或 {"resultUrls":[]}，请不要假设一定有链接。

Node.js 接收示例

app.post('/webhook/image', express.json(), (req, res) => {
  const { taskId, state, param, resultJson, failMsg } = req.body.data
  if (state === 'completed') {
    const { resultUrls } = JSON.parse(resultJson)
    console.log('image ready', taskId, resultUrls[0])
  } else {
    console.warn('image failed', taskId, failMsg)
  }
  res.status(200).end()                 // must be 2xx, otherwise we retry
})

注意事项

• - 每个任务只在送达 2xx 后停止重发，已送达后不会重复推送。
• - 当前不附带签名头。建议在 callback_url 路径中放置一段随机 token，由你在收到回调时自行校验来源。
• - GPT Image 2 Lite 与 SparkPix 是同步模型，POST 创建时通常已直接返回结果，回调对它们意义不大；其它模型（gpt-image-2、gpt-image-2-beta、gemini-image、kling-image 等）才是异步任务，建议生产环境优先使用回调而非轮询。
• - 回调地址建议使用公网 HTTPS 端点，并且能在 10 秒内返回响应（单次超时为 10s）。

任务状态

错误码

注意事项

• -图片文件保存 7 天，请及时下载
• -生成失败不扣费
• -建议每 2-3 秒轮询一次任务状态
• -生产环境建议使用 callback_url 避免轮询
• -请妥善保管 API 密钥