API de generación de imágenes

Inicio rápido

Autenticación

Añade el encabezado Authorization a todas las solicitudes:

Authorization: Bearer YOUR_API_KEY

Endpoints

Callback de webhook (callback_url)

Incluye callback_url en la solicitud de creación. Cuando la tarea alcanza el estado terminal completed o failed, nuestro servidor envía un único HTTP POST a esa URL con Content-Type: application/json (sin encabezado de firma). La entrega se reintenta hasta 3 veces (retroceso exponencial 1s/2s/4s, 10s por intento); si aún no tiene éxito, un trabajo en segundo plano sigue reintentando durante hasta 30 minutos hasta que tu endpoint devuelva 2xx.

Estructura del 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
  }
}

Nota: data.param y data.resultJson son ambas cadenas JSON; llama a JSON.parse una vez en cada una para obtener el objeto subyacente.

Tarea de imagen: estructura tras JSON.parse(data.resultJson)

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

resultUrls es un array de URLs de imágenes alojadas en Cloudflare R2. Los modelos de varias imágenes (SparkPix Image Edit, GPT Image 2 Lite con n>1) devuelven más de una. Cuando state=failed, resultJson suele ser null o {"resultUrls":[]}; no asumas que hay un enlace presente.

Ejemplo de receptor en 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
})

Notas

• - Una tarea deja de reintentar solo tras una respuesta 2xx; una vez entregada, nunca se vuelve a enviar.
• - Los callbacks no están firmados actualmente. Incrusta un token aleatorio en la ruta de tu callback_url y verifícalo al recibirlo.
• - GPT Image 2 Lite y SparkPix son síncronos: la llamada POST de creación normalmente ya devuelve el resultado, por lo que los callbacks aportan poco valor. Los proveedores asíncronos (gpt-image-2, gpt-image-2-beta, gemini-image, kling-image, …) son donde los callbacks importan; en producción, prefiérelos al polling.
• - Usa un endpoint HTTPS público que responda en menos de 10 segundos (tiempo de espera por intento).

Estados de la tarea

Códigos de error

Notas importantes

• -Los archivos de imagen se almacenan durante 7 días -- descárgalos cuanto antes
• -Las generaciones fallidas no se cobran
• -Consulta el estado cada 2-3 segundos para obtener actualizaciones
• -Usa callback_url en cargas de producción para evitar el sondeo
• -Mantén tu API key segura