API de geração de imagens

Início rápido

Autenticação

Adicione o cabeçalho Authorization a todas as solicitações:

Authorization: Bearer YOUR_API_KEY

Endpoints

Callback de webhook (callback_url)

Inclua callback_url na solicitação de criação. Quando a tarefa atinge o estado terminal completed ou failed, nosso servidor envia um único HTTP POST para essa URL com Content-Type: application/json (sem cabeçalho de assinatura). A entrega é repetida até 3 vezes (recuo exponencial 1s/2s/4s, 10s por tentativa); se ainda não tiver êxito, um job em segundo plano continua tentando por até 30 minutos até que seu endpoint retorne 2xx.

Estrutura do 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
  }
}

Observação: data.param e data.resultJson são ambas strings JSON; chame JSON.parse uma vez em cada uma para obter o objeto subjacente.

Tarefa de imagem: estrutura após JSON.parse(data.resultJson)

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

resultUrls é um array de URLs de imagens hospedadas no Cloudflare R2. Os modelos de várias imagens (SparkPix Image Edit, GPT Image 2 Lite com n>1) retornam mais de uma. Quando state=failed, resultJson normalmente é null ou {"resultUrls":[]}; não presuma que há um link presente.

Exemplo de receptor em 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

• - Uma tarefa para de tentar novamente apenas após uma resposta 2xx; uma vez entregue, nunca é enviada de novo.
• - Os callbacks não são assinados atualmente. Incorpore um token aleatório no caminho da sua callback_url e verifique-o no recebimento.
• - GPT Image 2 Lite e SparkPix são síncronos: a chamada POST de criação geralmente já retorna o resultado, então os callbacks agregam pouco valor. Os provedores assíncronos (gpt-image-2, gpt-image-2-beta, gemini-image, kling-image, …) são onde os callbacks importam; em produção, prefira-os ao polling.
• - Use um endpoint HTTPS público que responda em até 10 segundos (tempo limite por tentativa).

Estados da tarefa

Códigos de erro

Notas importantes

• -Os arquivos de imagem ficam armazenados por 7 dias -- baixe sem demora
• -As gerações com falha não são cobradas
• -Consulte o status a cada 2-3 segundos para obter atualizações
• -Use callback_url em cargas de produção para evitar o polling
• -Mantenha sua API key em segurança