Creovox API

Быстрый старт

1. 01

   Создайте API-ключ

   Войдите и откройте API Keys в панели управления. Создавайте отдельный ключ для каждого приложения, чтобы отключать один, не ломая остальные.

2. 02

   Купите кредиты

   API тратит только купленные кредиты. Бесплатные и бонусные кредиты продолжают работать на сайте, но недоступны через API.

3. 03

   Создайте задачу и опрашивайте её

   Отправьте промпт через POST на /api/v1/tasks, сохраните task_id, затем каждые несколько секунд выполняйте GET /api/v1/tasks/, пока статус не станет succeeded или failed.

Аутентификация

Передавайте ключ в заголовке Authorization в каждом запросе. Ключи привязаны к вашему аккаунту Creovox; ключи, созданные на других сайтах, отклоняются. Никогда не вставляйте ключ в код браузера или публичный репозиторий.

Authorization: Bearer YOUR_API_KEY

Эндпоинты

Создание задачи

Укажите id модели в model, а её параметры в input. Неизвестные имена параметров отклоняются, чтобы опечатки сразу давали ошибку. Передавайте заголовок Idempotency-Key, чтобы повторный запрос не создавал вторую задачу и не списывал за неё деньги.

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

Опрос результата

Опрашивайте каждые 3–5 секунд и останавливайтесь, когда статус succeeded или failed. Изображения обычно занимают от нескольких секунд до нескольких минут; если задача всё ещё в processing через 10 минут, прекратите опрос и свяжитесь с поддержкой, указав task_id. Когда задача успешна, output.images содержит URL изображений; скачайте их, если нужно хранить долго.

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

Статус задачи

processing

Задача обрабатывается либо ожидает подтверждения списания или принятия провайдером.

succeeded

Готово. output.images содержит результаты, credits_charged — окончательная сумма.

failed

Генерация не удалась, error.message объясняет причину. Списанные кредиты возвращаются автоматически: refund_pending равно true, пока возврат не завершён, затем credits_charged показывает 0. Опрос можно прекратить.

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

Цены

Цены указаны в кредитах и полностью совпадают с сайтом. 1 кредит = US$0.01. Каждое референсное изображение добавляет небольшую сумму. GET /api/v1/models всегда возвращает актуальный прайс-лист.

Ошибки

Ошибки используют HTTP-код статуса и одинаковую структуру JSON: code, message, error_type и data.

Ограничения и рекомендации

• У каждого ключа есть лимит запросов в минуту и лимит запущенных задач. На платных планах лимиты выше.
• Передавайте заголовок Idempotency-Key с каждым запросом на создание. Если запрос завершился по таймауту, повторите его с тем же Idempotency-Key: вы получите ту же задачу, и деньги не спишутся дважды.
• Референсные изображения должны быть доступны из публичного интернета. Подписанные URL подходят, если остаются действительными несколько минут.
• Задачи приватны. Ключ может читать только созданные им задачи.

Вопросы и ответы