Voor AI developer docs

Voor AI API

One REST API for the image, video and audio models on Voor AI. Requests spend the same credits as the website, and results appear in your History.

Base URL: https://voor.ai/v1

Authentication

Create a key on the API keys page and send it as a Bearer token. Keys are shown once; Voor stores only a hash. Revoke a key there and it stops working immediately.

Authorization: Bearer voor_sk_...

Create a generation

POST /v1/generations with a model id and its input parameters (see each model's page). The price in credits is the same as on voor.ai. It is charged when the task is created and refunded automatically if the generation fails. Optional fields: callback_url (public https URL for the webhook), expected_credits (reject if the price differs) and public (default false). The response is 202 with the task.

curl https://voor.ai/v1/generations \
  -H "Authorization: Bearer $VOOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "851-labs/background-remover",
  "input": {
    "prompt": "A red fox standing in fresh snow at golden hour, soft light"
  },
  "callback_url": "https://example.com/webhooks/voor"
}'

# Then poll the task (or wait for the webhook):
curl https://voor.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $VOOR_API_KEY"

Idempotency

Send an Idempotency-Key header (1-255 printable characters, a UUID works) to retry safely. Repeating the same key with the same body returns the original task with Idempotent-Replayed: true and charges nothing. The same key with a different body returns 409 idempotency_key_conflict. Keys are scoped to the API key.

Task status

GET /v1/tasks/{id} returns the task. status is pending, running, completed, failed or cancelled. Output URLs follow the same rules as the website: paid accounts receive the clean file, free accounts the watermarked copy. GET /v1/account returns your credit balance. GET /v1/models and GET /v1/models/{id} need no key.

{
  "id": "cm0abc123",
  "object": "task",
  "model": "MODEL_ID",
  "status": "completed",
  "created_at": "2026-10-20T08:00:00.000Z",
  "completed_at": "2026-10-20T08:00:41.000Z",
  "failed_at": null,
  "credits_charged": 13,
  "credits_refunded": 0,
  "output": [
    { "type": "image", "url": "https://cdn.voor.ai/...", "width": 1024, "height": 1024 }
  ],
  "error": null
}

Webhooks

With a callback_url, Voor sends one POST when the task finishes (task.completed, task.failed or task.cancelled). Answer with any 2xx status within 10 seconds. Other answers are retried after 30 s, 2 min, 10 min, 30 min, 1 h, 3 h and 6 h. Each key has its own signing secret (whsec_...) on the API keys page. The Voor-Signature header is t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.rawBody">; reject timestamps older than 5 minutes.

POST https://example.com/webhooks/voor
Content-Type: application/json
Voor-Event: task.completed
Voor-Webhook-Id: whd_cm0abc123
Voor-Signature: t=1792483241,v1=5f2b...e9

{ "id": "whd_cm0abc123", "object": "event", "type": "task.completed",
  "created_at": "2026-10-20T08:00:41.000Z", "data": { ...task } }
import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody must be the exact bytes Voor sent, before JSON parsing.
export function verifyVoorSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
  const timestamp = Number(parts.t);
  if (!parts.v1 || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
  const received = Buffer.from(parts.v1, "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Errors and limits

Errors are JSON: { "error": { "code": "...", "message": "..." } }. Each key allows 60 requests per minute; every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Concurrent running tasks follow your account's website limit.

StatusCodesMeaning
400invalid_request, invalid_input, invalid_json, invalid_callback_url, invalid_idempotency_keyFix the request; nothing was charged.
401invalid_api_keyMissing, malformed or revoked key.
402insufficient_creditsBalance is below the price. The body has credits_required and balance.
403account_restrictedThe account cannot generate.
404model_not_found, task_not_foundUnknown model id, or a task that is not yours.
409idempotency_key_conflict, price_changedSame Idempotency-Key with a different body, or expected_credits no longer matches.
413request_too_largeBodies are limited to 256 KB; pass media as URLs.
429rate_limited, concurrency_limitWait for Retry-After seconds.
503service_unavailable, service_busyRetry later with the same Idempotency-Key.

Models

3D

Audio

Image

Text

Video