Authentication

Generation endpoints (/v1/video/generations, /v1/image/generations) authenticate with an API key. Console endpoints (keys, billing) use the JWT returned by POST /v1/auth/login. Both travel in the Authorization header:

Models

The full model directory is always live at GET /v1/models. The table below lists the current line-up; the API response is the source of truth for pricing and availability.

Retired models return MODEL_RETIRED (400) and no longer accept new tasks.

Video API

Starts an asynchronous video generation task. The estimated cost (hold_usd) is frozen from your balance and settled to the real cost_usd on completion — or refunded on failure. Available models: wan2.6, kling3.0, seedance, seedance2.0, seedance2.5, seedance2.0-mini, veo3, veo3.1-fast, hailuo-2.3, hailuo-h3.

{
  "model": "kling3.0",           // required — see GET /v1/models
  "prompt": "Cinematic dolly shot through a neon market…",  // required
  "duration": 5,                 // optional: 5 or 10 (seconds)
  "resolution": "1080p",         // optional: "720p" | "1080p"
  "aspect_ratio": "16:9",        // optional: "16:9" | "9:16" | "1:1"
  "audio": false                 // optional: native audio when supported
}

HTTP/1.1 202 Accepted
{
  "id": "9f3c…",
  "task_id": "viddra-…",
  "object": "video.generation",
  "status": "queued",
  "model": "kling3.0",
  "prompt": "Cinematic dolly shot through a neon market…",
  "duration_seconds": 5,
  "hold_usd": "1.3500",
  "created_at": "2026-08-20T11:24:07.000Z"
}

Image API

Same async contract as video: submit, poll, download. Available models: flux, seedream, qwen-image.

{
  "model": "flux",               // required — flux | flux2-pro | seedream | qwen-image | ideogram-3.0
  "prompt": "Editorial portrait of an astronaut in a 1970s diner, film grain",
  "image_size": "1024x1024",     // optional
  "num_images": 1                // optional
}

HTTP/1.1 202 Accepted
{
  "id": "7ad1…",
  "task_id": "viddra-…",
  "object": "image.generation",
  "status": "queued",
  "model": "flux",
  "prompt": "Editorial portrait of an astronaut…",
  "hold_usd": "0.0500",
  "created_at": "2026-08-20T11:26:41.000Z"
}

Audio API

Text-to-speech powered by MiniMax Speech 02 HD. The provider account is being provisioned — calls currently return 503 PROVIDER_NOT_READY and no balance is held.

curl -X POST https://api.viddra.com/v1/audio/speech \
  -H "Authorization: Bearer $VIDDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "speech-02-hd", "input": "Hello from Viddra!"}'

# Current status: 503 PROVIDER_NOT_READY
# Speech models are being provisioned and will go live shortly.

Task Polling

Retrieve task status with your API key (image tasks: /v1/image/generations/{id}). Poll every 3–5 seconds. Statuses: queued → running → succeeded / failed.

Response (succeeded)

{
  "id": "9f3c…",
  "task_id": "viddra-…",
  "status": "succeeded",
  "model": "kling3.0",
  "video_url": "https://…/result.mp4",
  "result_url": "https://…/result.mp4",
  "hold_usd": "1.3500",
  "cost_usd": "1.3500",
  "created_at": "2026-08-20T11:24:07.000Z",
  "completed_at": "2026-08-20T11:25:52.000Z"
}

# On failure:
# {"status":"failed","error":"UPSTREAM_ERROR: …"}
# → the held amount is automatically refunded (see /v1/billing/transactions).

Errors

All errors share one envelope:

{"error": {"code": "INSUFFICIENT_BALANCE", "message": "Balance 0.1200 USD cannot cover hold 0.6000 USD"}}

Rate Limits

Exceeding a limit returns 429. Back off for a few seconds and retry. You can set a monthly spending cap on each API key in Console → API Keys; once the cap is hit, generation calls return 429 MONTHLY_LIMIT_EXCEEDED until the next month.

SDKs

The API is plain REST + JSON — any HTTP client works. Official Python and Node SDKs are in development; until then, the snippets below are production-ready starting points.

import time, requests

API = "https://api.viddra.com"
H = {"Authorization": "Bearer " + "YOUR_VIDDRA_API_KEY"}

task = requests.post(API + "/v1/video/generations",
    headers=H, json={"model": "wan2.6", "prompt": "A cat DJing at a club"}).json()

while True:
    t = requests.get(f"{API}/v1/video/generations/{task['id']}", headers=H).json()
    if t["status"] == "succeeded":
        print(t["video_url"]); break
    if t["status"] == "failed":
        raise RuntimeError(t.get("error"))  # auto-refunded
    time.sleep(5)

const API = 'https://api.viddra.com';
const H = { Authorization: `Bearer ${process.env.VIDDRA_API_KEY}`,
            'Content-Type': 'application/json' };

const task = await fetch(API + '/v1/image/generations', {
  method: 'POST', headers: H,
  body: JSON.stringify({ model: 'flux', prompt: 'Aurora over a fjord' })
}).then(r => r.json());

while (true) {
  await new Promise(r => setTimeout(r, 5000));
  const t = await fetch(`${API}/v1/image/generations/${task.id}`, { headers: H }).then(r => r.json());
  if (t.status === 'succeeded') { console.log(t.result_url); break; }
  if (t.status === 'failed') throw new Error(t.error); // auto-refunded
}