Creovox API

Início rápido

1. 01

   Crie uma chave de API

   Entre e abra API Keys no painel. Crie uma chave separada para cada app, assim você pode desativar uma sem quebrar as outras.

2. 02

   Compre créditos

   A API gasta apenas créditos comprados. Créditos grátis e de bônus continuam funcionando no site, mas não podem ser usados pela API.

3. 03

   Crie uma tarefa e consulte

   Envie seu prompt com POST para /api/v1/tasks, guarde o task_id e depois faça GET /api/v1/tasks/ a cada poucos segundos até o status ser succeeded ou failed.

Autenticação

Envie sua chave no cabeçalho Authorization em toda requisição. As chaves estão vinculadas à sua conta Creovox; chaves criadas em outros sites são rejeitadas. Nunca coloque uma chave em código de navegador ou em repositório público.

Authorization: Bearer YOUR_API_KEY

Pontos de extremidade

Criar uma tarefa

Coloque o id do modelo em model e os parâmetros em input. Nomes de parâmetro desconhecidos são rejeitados, então erros de digitação falham na hora. Envie um cabeçalho Idempotency-Key para que uma requisição repetida não crie nem cobre uma segunda tarefa.

curl -X POST https://creovox.ai/api/v1/tasks \
  -H "Authorization: Bearer $CREOVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-fox" \
  -d '{
    "model": "gpt-image-2.6",
    "input": {
      "prompt": "A red fox in fresh snow, cinematic light",
      "variant": "flare",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n42…gptimg",
    "model": "gpt-image-2.6",
    "status": "processing",
    "output": null,
    "credits_charged": 20,
    "refund_pending": false,
    "error": null,
    "created_at": "2026-11-07T08:00:00.000Z"
  }
}

Parâmetros do GPT Image 2.6

Consultar o resultado

Consulte a cada 3 a 5 segundos e pare quando o status for succeeded ou failed. As imagens costumam levar de alguns segundos a alguns minutos; se uma tarefa ainda estiver em processing após 10 minutos, pare e fale com o suporte informando o task_id. Quando a tarefa termina com sucesso, output.images contém as URL das imagens; baixe-as se precisar guardá-las.

curl https://creovox.ai/api/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $CREOVOX_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n42…gptimg",
    "model": "gpt-image-2.6",
    "status": "succeeded",
    "output": { "images": [{ "url": "https://…/image.png" }] },
    "credits_charged": 20,
    "refund_pending": false,
    "error": null,
    "created_at": "2026-11-07T08:00:00.000Z"
  }
}

Status da tarefa

processing

A tarefa está em processamento ou aguarda a confirmação da cobrança ou da aceitação pelo fornecedor.

succeeded

Concluída. output.images contém os resultados e credits_charged é definitivo.

failed

A geração falhou e error.message explica o motivo. Os créditos cobrados são reembolsados automaticamente: refund_pending é true até o reembolso ser aplicado, depois credits_charged mostra 0. Você pode parar de consultar.

// Node.js 18+
const API = 'https://creovox.ai/api/v1'
const headers = {
  Authorization: `Bearer ${process.env.CREOVOX_API_KEY}`,
  'Content-Type': 'application/json',
}

async function call(path, init = {}) {
  const res = await fetch(API + path, { ...init, headers: { ...headers, ...init.headers }, signal: AbortSignal.timeout(30_000) })
  const body = await res.json().catch(() => ({ code: res.status, message: res.statusText }))
  if (body.code !== 200) {
    const error = new Error(body.message)
    Object.assign(error, { status: res.status, type: body.error_type, data: body.data, retryAfter: res.headers.get('retry-after') })
    throw error
  }
  return body.data
}

// Reuse the same key when you retry this request: you get the same task and pay once.
const idempotencyKey = crypto.randomUUID()
let task
try {
  task = await call('/tasks', {
    method: 'POST',
    headers: { 'Idempotency-Key': idempotencyKey },
    body: JSON.stringify({ model: 'gpt-image-2.6', input: { prompt: 'A red fox in fresh snow' } }),
  })
} catch (error) {
  if (!error.data?.task_id || !['billing_unconfirmed', 'submission_unconfirmed'].includes(error.type)) throw error
  task = { task_id: error.data.task_id, status: 'processing' }
}

const deadline = Date.now() + 10 * 60_000
while (task.status === 'processing') {
  if (Date.now() > deadline) throw new Error(`Task ${task.task_id} is still processing; contact support.`)
  await new Promise(resolve => setTimeout(resolve, 4000))
  try {
    task = await call(`/tasks/${task.task_id}`)
  } catch (error) {
    // 429 and 5xx are temporary: wait and poll again. Anything else is final.
    if (error.status !== 429 && error.status < 500) throw error
    await new Promise(resolve => setTimeout(resolve, (Number(error.retryAfter) || 5) * 1000))
  }
}
console.log(task.status, task.output?.images, task.error, task.refund_pending)

Preços

Os preços são em créditos e correspondem exatamente ao site. 1 crédito é US$0.01. Cada imagem de referência adiciona um valor pequeno. GET /api/v1/models sempre retorna a tabela de preços atual.

Erros

Os erros usam o código de status HTTP e a mesma estrutura JSON: code, message, error_type e data.

Limites e boas práticas

• Cada chave tem um limite por minuto e um limite de tarefas em execução. Planos pagos têm limites mais altos.
• Envie um cabeçalho Idempotency-Key em toda requisição de criação. Se uma requisição expirar, repita com o mesmo Idempotency-Key: você recebe a mesma tarefa e nunca é cobrado duas vezes.
• As imagens de referência precisam ser acessíveis pela internet pública. URL assinadas servem se continuarem válidas por alguns minutos.
• As tarefas são privadas. Uma chave só lê as tarefas que criou.

Perguntas frequentes