API reference

Quickstart

Start a Veo 3.1 Lite video, then poll the task until it has succeeded.

curl -X POST https://avatarity.dev/v1/video/generations \
  -H "Authorization: Bearer av_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "veo-3.1-lite", "prompt": "Slow drone flight over misty sandstone pillars at golden hour", "aspect_ratio": "16:9" }'

# -> 202 { "task_id": "task_...", "status": "queued", "model": "veo-3.1-lite", "eta_seconds": 35, ... }
#    eta_seconds is a rough static estimate; the real time depends on the queue.

curl https://avatarity.dev/v1/tasks/task_... -H "Authorization: Bearer av_live_YOUR_KEY"

Authentication

Create your key in the Studio under Settings (one key per account). It is shown once, starts with av_live_ (keys created before 23 October 2026 start with vf_live_ and keep working) and is sent as a Bearer token. Keys use the plan of the account that created them. Rotate or revoke a key at any time; a revoked key fails at once.

Authorization: Bearer av_live_...

POST /v1/video/generations

Starts a video render and answers 202 with a task id. Veo 3.1 Lite uses your plan allowance; Omni 1.1 Flash needs the Omni add-on ($0.15 per successful generation). Send an Idempotency-Key header to make retries safe: the same key returns the first answer and starts nothing new.

Every clip is about 8 seconds at 720p. The response carries X-Avatarity-Remaining-Veo with the Veo 3.1 Lite videos left this period.

POST /v1/images/generations

Generates Nano Banana images from your plan allowance and answers 200 with the image URLs. Each image counts once. Add "async": true to get a task id instead and poll GET /v1/tasks/{id}.

{ "created": 1792771834, "data": [ { "url": "https://avatarity.dev/v1/assets/..." } ] }

GET /v1/tasks/{id}

Status of a video or image task. status is queued, processing, succeeded or failed. Poll every 5 to 10 seconds. Links to results expire; download what you keep.

{
  "task_id": "task_...",
  "status": "succeeded",
  "progress_pct": 100,
  "model": "veo-3.1-lite",
  "video_url": "https://avatarity.dev/v1/assets/...",
  "error": null,
  "created_at": "2026-10-23T12:00:00.000Z"
}

A failed task returns its allowance automatically; error then has a code and a message.

GET /v1/usage

Your plan, the current period and what is left. Omni spend and cap are in cents.

{
  "plan": { "id": "pro", "name": "Pro", "price_cents": 7000, "currency": "USD", "concurrency": 4 },
  "status": "active",
  "current_period_end": "2026-11-23T00:00:00.000Z",
  "cancel_at_period_end": false,
  "allowances": {
    "veo":    { "granted": 8000,  "used": 1240, "reserved": 2, "remaining": 6758 },
    "images": { "granted": 20000, "used": 310,  "reserved": 0, "remaining": 19690 }
  },
  "omni": { "enabled": true, "price_cents": 15, "cap_cents": 5000, "spent_cents": 450 }
}

GET /v1/models

The models you can call, with formats and how they are billed. No key needed.

GET /v1/capacity

Free render capacity right now, in percent: available (40 % or more), busy (10 to 39 %) or full (below 10 %: Studio renders wait in the queue, API renders may take longer to start). No key needed.

{ "capacity_pct": 72, "state": "available", "products": { "veo": 72, "omni": 72, "images": 72 }, "updated_at": "..." }

Webhooks

With webhook_url set, we POST task.started, task.succeeded and task.failed events to it. Treat a webhook as a notification only and read the result with GET /v1/tasks/{id} using your key; signatures you can verify yourself are not offered yet.

Errors

Errors have the shape { "error": { "code", "message", "details"? } }.

Limits

• Renders at a time: Starter and Pro 4, Advanced 8, Dedicated 16.
• Requests per minute per key: shown in the X-RateLimit-* headers of every answer.
• Videos: about 8 seconds at 720p, 16:9 or 9:16. Images: 1 to 4 per request, up to 4 reference images.
• Questions or a result that looks wrong? Use support with the task id.