Creovox API

Inicio rápido

1. 01

   Crea una clave de API

   Inicia sesión y abre API Keys en el panel. Crea una clave distinta para cada aplicación, así puedes desactivar una sin romper las demás.

2. 02

   Compra créditos

   La API solo gasta créditos comprados. Los créditos gratuitos y de bonificación siguen funcionando en el sitio web, pero no se pueden usar con la API.

3. 03

   Crea una tarea y consúltala

   Envía tu prompt con POST a /api/v1/tasks, guarda el task_id y luego haz GET /api/v1/tasks/ cada pocos segundos hasta que el estado sea succeeded o failed.

Autenticación

Envía tu clave en el encabezado Authorization en cada solicitud. Las claves están vinculadas a tu cuenta de Creovox; las claves creadas en otros sitios se rechazan. Nunca pongas una clave en código de navegador ni en un repositorio público.

Authorization: Bearer YOUR_API_KEY

Puntos de enlace

Crear una tarea

Pon el id del modelo en model y sus parámetros en input. Los nombres de parámetro desconocidos se rechazan, así los errores de escritura fallan al instante. Envía un encabezado Idempotency-Key para que una solicitud reintentada no cree ni cobre una segunda tarea.

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 de GPT Image 2.6

Consultar el resultado

Consulta cada 3 a 5 segundos y detente cuando el estado sea succeeded o failed. Las imágenes suelen tardar de unos segundos a unos minutos; si una tarea sigue en processing después de 10 minutos, detente y contacta con el soporte indicando su task_id. Cuando la tarea termina con éxito, output.images contiene las URL de las imágenes; descárgalas si necesitas conservarlas.

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

Estado de la tarea

processing

La tarea se está procesando o espera la confirmación del cargo o de su aceptación por el proveedor.

succeeded

Terminada. output.images contiene los resultados y credits_charged es definitivo.

failed

La generación falló y error.message explica el motivo. Los créditos cobrados se reembolsan automáticamente: refund_pending es true hasta que llega el reembolso, y después credits_charged muestra 0. Puedes dejar 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)

Precios

Los precios están en créditos y coinciden exactamente con el sitio web. 1 crédito son US$0.01. Cada imagen de referencia añade un importe pequeño. GET /api/v1/models siempre devuelve la lista de precios actual.

Errores

Los errores usan el código de estado HTTP y la misma estructura JSON: code, message, error_type y data.

Límites y buenas prácticas

• Cada clave tiene un límite por minuto y un límite de tareas en ejecución. Los planes de pago tienen límites más altos.
• Envía un encabezado Idempotency-Key en cada solicitud de creación. Si una solicitud se agota por tiempo de espera, reinténtala con el mismo Idempotency-Key: obtienes la misma tarea y nunca se te cobra dos veces.
• Las imágenes de referencia deben ser accesibles desde internet público. Las URL firmadas sirven si siguen siendo válidas unos minutos.
• Las tareas son privadas. Una clave solo puede leer las tareas que creó.

Preguntas frecuentes