Image Generation API

Quick Start

Authentication

Add Authorization header to all requests:

Authorization: Bearer YOUR_API_KEY

Endpoints

Webhook Callback (callback_url)

Pass callback_url in the create request. When the task reaches the completed or failed terminal state, our server sends a single HTTP POST to that URL with Content-Type: application/json (no signing header). Delivery is retried up to 3 times (exponential backoff 1s/2s/4s, 10s per attempt); if still unsuccessful, a background job keeps retrying for up to 30 minutes until your endpoint returns 2xx.

Payload Structure

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 | "string",
    "failMsg": null | "string",
    "costTime": 12345,                    // duration in ms
    "completeTime": 1705123465000,        // ms epoch
    "createTime": 1705123450000           // ms epoch
  }
}

Note: data.param and data.resultJson are both JSON strings — call JSON.parse once on each to get the underlying object.

Image task: shape after JSON.parse(data.resultJson)

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

resultUrls is an array of Cloudflare R2-hosted image URLs. Multi-image models (SparkPix Image Edit, GPT Image 2 Lite with n>1) return more than one. When state=failed, resultJson is typically null or {"resultUrls":[]} — do not assume a link is present.

Node.js receiver example

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
})

Notes

• - A task stops retrying only after a 2xx response — once delivered it is never pushed again.
• - Callbacks are not signed today. Embed a random token in your callback_url path and verify it on receipt.
• - GPT Image 2 Lite and SparkPix are synchronous — the POST create call usually already returns the result, so callbacks add little value. The async providers (gpt-image-2, gpt-image-2-beta, gemini-image, kling-image, …) are where callbacks matter — prefer them over polling in production.
• - Use a public HTTPS endpoint that responds within 10 seconds (per-attempt timeout).

Task States

Error Codes

Important Notes

• -Image files are stored for 7 days -- download promptly
• -Failed generations are not charged
• -Poll every 2-3 seconds for status updates
• -Use callback_url for production workloads to avoid polling
• -Keep your API key secure