Creovox API

Quick start

1. 01

   Create an API key

   Sign in and open API Keys in the dashboard. Create a separate key for each app so you can disable one without breaking the others.

2. 02

   Buy credits

   The API spends purchased credits only. Free and bonus credits keep working on the website but cannot be used through the API.

3. 03

   Create a task and poll it

   POST your prompt to /api/v1/tasks, keep the task_id, then GET /api/v1/tasks/ every few seconds until the status is succeeded or failed.

Authentication

Send your key in the Authorization header on every request. Keys are tied to your Creovox account; keys created on other sites are rejected. Never put a key in browser code or a public repository.

Authorization: Bearer YOUR_API_KEY

Endpoints

Create a task

Put the model id in model and its parameters in input. Unknown parameter names are rejected so typos fail loudly. Send an Idempotency-Key header so a retried request never creates or charges a second task.

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

GPT Image 2.6 parameters

Poll for the result

Poll every 3 to 5 seconds and stop when the status is succeeded or failed. Images usually take from a few seconds to a few minutes; if a task is still processing after 10 minutes, stop and contact support with its task_id. When the task succeeds, output.images holds the image URLs; download them if you need to keep them long term.

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

Task status

processing

The task is processing or awaiting confirmation of billing or provider acceptance.

succeeded

Finished. output.images contains the results and credits_charged is final.

failed

Generation failed and error.message explains why. Any credits charged are refunded automatically: refund_pending is true until the refund lands, then credits_charged shows 0. You can stop polling.

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

Pricing

Prices are in credits and match the website exactly. 1 credit is US$0.01. Each reference image adds a small amount. GET /api/v1/models always returns the current price list.

Errors

Errors use the HTTP status code and the same JSON shape: code, message, error_type and data.

Limits and good practice

• Each key has a per-minute limit and a limit on running tasks. Paid plans get higher limits.
• Send an Idempotency-Key header with every create request. If a request times out, retry it with the same key: you get the same task and are never charged twice.
• Reference images must be reachable from the public internet. Signed URLs work if they stay valid for a few minutes.
• Tasks are private. A key can only read the tasks it created.

FAQ