Creovox API

Schnellstart

1. 01

   API-Schlüssel erstellen

   Melde dich an und öffne API Keys im Dashboard. Erstelle für jede App einen eigenen Schlüssel, damit du einen deaktivieren kannst, ohne die anderen zu stören.

2. 02

   Credits kaufen

   Die API verbraucht nur gekaufte Credits. Kostenlose und Bonus-Credits funktionieren weiterhin auf der Website, sind aber über die API nicht nutzbar.

3. 03

   Aufgabe erstellen und abfragen

   Sende deinen Prompt per POST an /api/v1/tasks, merke dir die task_id und frage dann alle paar Sekunden GET /api/v1/tasks/ ab, bis der Status succeeded oder failed ist.

Authentifizierung

Sende deinen Schlüssel bei jeder Anfrage im Authorization-Header. Schlüssel sind an dein Creovox-Konto gebunden; auf anderen Seiten erstellte Schlüssel werden abgelehnt. Lege einen Schlüssel niemals in Browsercode oder ein öffentliches Repository.

Authorization: Bearer YOUR_API_KEY

Endpunkte

Aufgabe erstellen

Setze die Modell-id in model und ihre Parameter in input. Unbekannte Parameternamen werden abgelehnt, damit Tippfehler sofort auffallen. Sende einen Idempotency-Key-Header, damit eine wiederholte Anfrage keine zweite Aufgabe erstellt und nichts doppelt berechnet.

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

Parameter von GPT Image 2.6

Ergebnis abfragen

Frage alle 3 bis 5 Sekunden ab und höre auf, wenn der Status succeeded oder failed ist. Bilder dauern meist einige Sekunden bis einige Minuten; ist eine Aufgabe nach 10 Minuten noch in processing, höre auf und wende dich mit ihrer task_id an den Support. War die Aufgabe erfolgreich, enthält output.images die Bild-URLs; lade sie herunter, wenn du sie dauerhaft behalten willst.

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

Aufgabenstatus

processing

Der Auftrag wird verarbeitet oder wartet auf die Bestätigung der Abbuchung oder der Annahme durch den Anbieter.

succeeded

Fertig. output.images enthält die Ergebnisse, credits_charged ist endgültig.

failed

Die Generierung ist fehlgeschlagen, error.message nennt den Grund. Bereits belastete Credits werden automatisch erstattet: refund_pending ist true, bis die Erstattung eingeht, danach zeigt credits_charged 0. Du kannst das Abfragen beenden.

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

Preise

Preise sind in Credits und entsprechen genau der Website. 1 Credit sind US$0.01. Jedes Referenzbild kostet einen kleinen Zusatzbetrag. GET /api/v1/models liefert immer die aktuelle Preisliste.

Fehler

Fehler nutzen den HTTP-Statuscode und dieselbe JSON-Struktur: code, message, error_type und data.

Grenzen und bewährte Praxis

• Jeder Schlüssel hat ein Minutenlimit und ein Limit für laufende Aufgaben. Bezahlte Pläne haben höhere Limits.
• Sende bei jeder Erstellungsanfrage einen Idempotency-Key-Header. Läuft eine Anfrage in einen Timeout, wiederhole sie mit demselben Idempotency-Key: Du bekommst dieselbe Aufgabe und wirst nie doppelt belastet.
• Referenzbilder müssen aus dem öffentlichen Internet erreichbar sein. Signierte URLs funktionieren, wenn sie einige Minuten gültig bleiben.
• Aufgaben sind privat. Ein Schlüssel kann nur seine eigenen Aufgaben lesen.

Häufige Fragen