Get started

Quickstart

Create an API key, check your balance, generate an image, wait for it, then turn a character into a video.

1. Create a key

Open Dashboard → Developers, create a key and copy it — it is shown once. Store it as an environment variable on your server:

Terminal

export ORIOR_API_KEY="orior_live_…"

Keys spend real credits. Keep them server-side, give each environment its own key, and set a monthly credit limit on keys you share.

2. Check the account

curl https://api.oriorai.com/v1/account \
  -H "Authorization: Bearer $ORIOR_API_KEY"

const res = await fetch('https://api.oriorai.com/v1/account', {
  headers: { Authorization: `Bearer ${process.env.ORIOR_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get("https://api.oriorai.com/v1/account", headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"})
print(res.json())

You get your plan, credit balance and limits. A 401 means the key is wrong or revoked; 403 PLAN_REQUIRED means the account is not on Influencer or Agency.

Write requests need an Idempotency-Key — any unique string per logical request. If the network drops, send the same request with the same key and you get the original response instead of a second charge.

curl https://api.oriorai.com/v1/images \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A barista smiling behind a latte, morning light",
    "aspect_ratio": "9:16",
    "resolution": "2K"
  }'

const res = await fetch('https://api.oriorai.com/v1/images', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'A barista smiling behind a latte, morning light',
    aspect_ratio: '9:16',
    resolution: '2K',
  }),
})
const generation = await res.json() // 202

import os, uuid, requests

res = requests.post(
    "https://api.oriorai.com/v1/images",
    headers={
        "Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"prompt": "A barista smiling behind a latte, morning light", "aspect_ratio": "9:16", "resolution": "2K"},
)
generation = res.json()  # 202

202 Accepted

{
  "id": "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b",
  "object": "generation",
  "type": "image",
  "model": "orior-image",
  "status": "queued",
  "credits": 2,
  "refunded_credits": 0,
  "result": null,
  "error": null,
  "request": {
    "prompt": "A barista smiling behind a latte, morning light",
    "character_id": null,
    "product_id": null,
    "aspect_ratio": "9:16",
    "resolution": "2K",
    "edit": false,
    "has_scene_image": false,
    "reference_images": 0
  },
  "timeline": [],
  "created_at": 1758620000000,
  "completed_at": null
}

The 2 credits are reserved now. If the generation fails, they are returned automatically.

4. Wait for the result

Poll GET /generations/{id} every few seconds (images usually take 20–60 s), or register a webhook and skip polling entirely.

const headers = { Authorization: `Bearer ${process.env.ORIOR_API_KEY}` }

async function waitFor(id, { interval = 4000, timeout = 10 * 60_000 } = {}) {
  const started = Date.now()
  while (Date.now() - started < timeout) {
    const res = await fetch(`https://api.oriorai.com/v1/generations/${id}`, { headers })
    const generation = await res.json()
    if (['completed', 'failed', 'cancelled'].includes(generation.status)) return generation
    await new Promise(resolve => setTimeout(resolve, interval))
  }
  throw new Error('Timed out waiting for ' + id)
}

const generation = await waitFor('gen_…')
if (generation.status === 'completed') console.log(generation.result.url)
else console.error(generation.error.code, generation.error.message)

import os, time, requests

HEADERS = {"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"}

def wait_for(generation_id, interval=4, timeout=600):
    started = time.time()
    while time.time() - started < timeout:
        generation = requests.get(f"https://api.oriorai.com/v1/generations/{generation_id}", headers=HEADERS, timeout=30).json()
        if generation["status"] in ("completed", "failed", "cancelled"):
            return generation
        time.sleep(interval)
    raise TimeoutError(generation_id)

generation = wait_for("gen_…")
print(generation["result"]["url"] if generation["status"] == "completed" else generation["error"])

When completed, result.url is the full-resolution file. It stays available (and in your Orior library) until you delete the generation.

5. Make a video

Create a character from three photos once, then feature it in any video. Media fields accept upload IDs, public https URLs or data URLs.

cURL

# Create a character (free)
curl https://api.oriorai.com/v1/characters \
  -H "Authorization: Bearer $ORIOR_API_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"name":"Ava","gender":"female","images":["https://example.com/ava-1.jpg","https://example.com/ava-2.jpg","https://example.com/ava-3.jpg"]}'

# Check the price first (nothing is charged)
curl https://api.oriorai.com/v1/quote \
  -H "Authorization: Bearer $ORIOR_API_KEY" -H "Content-Type: application/json" \
  -d '{"type":"video","model":"seedance-2.5","character_id":"<id>","prompt":"She turns to camera and laughs","duration":"8","resolution":"720p"}'

# Generate
curl https://api.oriorai.com/v1/videos \
  -H "Authorization: Bearer $ORIOR_API_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.5","character_id":"<id>","prompt":"She turns to camera and laughs","duration":"8","resolution":"720p","audio":true}'

Videos take 1–6 minutes. Poll every 10–15 seconds or use webhooks. See Models for every model’s options.

Before production

Retry network errors and 5xx with the same Idempotency-Key; back off on 429 using Retry-After.
Handle INSUFFICIENT_CREDITS (top up in the dashboard) and CONTENT_BLOCKED (prompt rejected, not charged).
Verify webhook signatures and treat event IDs as idempotent.
Set a monthly credit limit per key and watch GET /usage.
Read the API terms — especially consent for real people’s photos.