Documentation

Build with Oracium

One API. Every frontier video and image model. Production-ready primitives, typed SDKs, and infrastructure that scales with you.

Quickstart

Make your first generation in under 60 seconds.

Authentication

API keys, scopes, and rotating credentials safely.

Model reference

Every supported video and image model with parameters.

SDKs

Official clients for Node, Python, Go, and Rust.

Webhooks

Receive async generation results with signed payloads.

Guides

Patterns for streaming, retries, and production scale.

Quickstart

From zero to your first generation

Install the SDK, drop in your API key, and call any of 100+ models with the same interface.

1

Install the SDK

bash
npm install @oracium/sdk
2

Set your API key

bash
export ORACIUM_API_KEY="sk_live_..."

Generate a key from your dashboard. Keys are scoped per environment.

3

Generate your first video

ts
import { Oracium } from "@oracium/sdk";

const oracium = new Oracium({ apiKey: process.env.ORACIUM_API_KEY });

const job = await oracium.video.generate({
  model: "kling-2.0-pro",
  prompt: "Cinematic shot of a hovercar weaving through neon Tokyo at night",
  duration: 8,
  resolution: "1080p",
});

console.log(job.url);

Authentication

API keys & scopes

Authenticate every request with a Bearer token. Restrict keys to specific models, environments, or rate limits.

bash
curl https://api.oracium.ai/v1/models \
  -H "Authorization: Bearer $ORACIUM_API_KEY"

Model reference

Supported models

ModelTypeMax durationStatus
kling-2.0-provideo10sstable
veo-3video16sstable
seedance-provideo8sstable
runway-gen-4video10sstable
flux-pro-1.1image—stable
sdxl-turboimage—stable
ideogram-v3image—beta

SDKs

Official clients

Node.js
@oracium/node
Python
@oracium/python
Go
@oracium/go
Rust
@oracium/rust

Webhooks

Async results delivery

Long-running generations are delivered to your webhook endpoint with HMAC signatures.

json
{
  "id": "gen_8a2f...",
  "model": "veo-3",
  "status": "succeeded",
  "output": { "url": "https://cdn.oracium.ai/..." },
  "created_at": 1746998400
}

Guides

Production patterns

Battle-tested patterns we recommend for shipping Oracium to real users at scale.

Streaming generations to the browser

Pipe partial frames or progress events directly to the client over SSE so users see results the instant they're ready.

ts
const stream = await oracium.video.stream({
  model: "kling-2.0-pro",
  prompt: "A drone shot over the Alps at sunrise",
});

for await (const event of stream) {
  if (event.type === "progress") send({ pct: event.pct });
  if (event.type === "frame")    send({ url: event.url });
  if (event.type === "complete") send({ done: true, url: event.url });
}

Idempotency & safe retries

Pass an Idempotency-Key on every write. Retries within 24h return the original result instead of charging twice.

bash
curl https://api.oracium.ai/v1/video/generate \
  -H "Authorization: Bearer $ORACIUM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "model": "veo-3", "prompt": "..." }'

Rate limit handling

Respect Retry-After and back off exponentially with jitter. Our SDKs do this automatically; here's the manual version.

ts
async function withBackoff<T>(fn: () => Promise<T>, max = 5): Promise<T> {
  for (let attempt = 0; attempt < max; attempt++) {
    try { return await fn(); }
    catch (err: any) {
      if (err.status !== 429 || attempt === max - 1) throw err;
      const wait = Number(err.headers["retry-after"] ?? 1) * 1000;
      await new Promise((r) => setTimeout(r, wait + Math.random() * 250));
    }
  }
  throw new Error("unreachable");
}

Cost-aware model routing

Route prompts to the cheapest model that meets your quality bar, then fall back to a flagship model on failure.

ts
const tiers = ["sdxl-turbo", "flux-pro-1.1", "veo-3"] as const;

for (const model of tiers) {
  try {
    return await oracium.image.generate({ model, prompt });
  } catch (err) {
    if (!isRetryable(err)) throw err;
  }
}

Content moderation pipelines

Pre-screen prompts with the moderation endpoint and tag generations with a policy version for downstream review.

ts
const check = await oracium.moderation.check({ input: prompt });
if (check.flagged) throw new Error("Prompt rejected: " + check.categories.join(", "));

const job = await oracium.video.generate({
  model: "kling-2.0-pro",
  prompt,
  metadata: { policy_version: "2026-05-01", user_id: user.id },
});

Multi-region failover

Pin requests to the closest region and fall back automatically when a region degrades.

ts
const oracium = new Oracium({
  apiKey: process.env.ORACIUM_API_KEY,
  regions: ["us-east", "eu-west", "ap-southeast"],
  failover: "auto", // retries the next region on 5xx / timeout
});

Start generating in
under 60 seconds.

Get an API key, install the SDK, ship your first generation today.

Get your API key Talk to sales