Developer docs

Orvian API

Integrate Orvian’s AI video and image generation directly into your platform. Everything the Orvian dashboard does — avatar videos, voice synthesis, image generation, lip sync — is available as a simple HTTP API.

Get Agency access View pricing

API access requires the Agency plan ($129/mo). Once subscribed, generate up to 10 API keys from Dashboard → API Keys.

Step 1

Authentication

Every request to the Orvian API must include your API key in the Authorization header. Your key starts with orvian_.

# Every request needs this header Authorization: Bearer orvian_your-api-key-here

Keys are valid indefinitely until you revoke them.

A key has the same permissions as your account — it can read and write everything your account has access to.

For SSE streams (job progress), pass the key as a query parameter: ?token=orvian_your-key because browsers cannot send custom headers on EventSource connections.

Step 2

Base URL

All API requests go to the following base URL. All routes are versioned under /v1/.

https://api.orvian.com

Step 3

How AI jobs work

AI operations — video generation, image creation, voice synthesis — take seconds to minutes to complete. Orvian uses an async job pattern so your app never waits or times out.

1. Submit the job

POST to a /generate/* endpoint. Orvian validates your request and queues the job. You get a jobId back in under 200ms.

2. Stream progress

Open an EventSource connection to /v1/jobs/:id/stream. You receive real-time progress events (0–100%) as the AI processes your job.

3. Get the result

When progress hits 100%, the final event contains the CDN URL of your generated file. Download or serve it directly from there.

// Step 1 — Submit the job const jobRes = await fetch('https://api.orvian.com/v1/generate/avatar-video', { method: 'POST', headers: { 'Authorization': 'Bearer orvian_your-key', 'Content-Type': 'application/json' }, body: JSON.stringify({ avatarId: 'avatar_abc123', script: 'Welcome to our platform...', voiceId: 'voice_xyz789' }) }); const { data: { jobId } } = await jobRes.json(); // Step 2 — Stream real-time progress const stream = new EventSource(`https://api.orvian.com/v1/jobs/${jobId}/stream?token=orvian_your-key`); stream.onmessage = (event) => { const update = JSON.parse(event.data); console.log(update.progress); // 0 → 100 if(update.status === 'completed') console.log(update.resultUrl); // CDN URL };

Reference

Available endpoints

All endpoints require authentication. Credit costs are deducted only after a job is confirmed as accepted — failed jobs are never charged.

Method	Endpoint	Description	Cost
POST	/v1/generate/avatar-video	Generate a video of an avatar speaking a script with a chosen voice.	410–1,090 credits
POST	/v1/generate/lipsync	Sync an existing video to a new audio track using AI lip sync.	420 credits / 30s
POST	/v1/generate/image	Generate a marketing image from a text prompt (FLUX.1 Pro).	12 credits
POST	/v1/generate/voice	Convert a text script to speech using a cloned or preset voice.	50 credits / min
POST	/v1/generate/bg-remove	Remove the background from an image or video.	5–110 credits
GET	/v1/jobs/:id	Get the current status and result of a job.	Free
GET	/v1/jobs/:id/stream	Subscribe to real-time progress updates for a job (Server-Sent Events).	Free
GET	/v1/avatars	List all avatars in your account.	Free
GET	/v1/voices	List all voice profiles in your account.	Free
GET	/v1/media	List all generated assets in your media library.	Free
GET	/v1/billing/credits	Get your current credit balance and subscription tier.	Free

Reference

Error responses

All errors return a structured JSON body — never a raw stack trace or plain-text message.

{ "success": false, "error": { "code": "INSUFFICIENT_CREDITS", "message": "Your account does not have enough credits for this operation.", "statusCode": 402 } }

Status	Meaning	What to do
401	Unauthorized	Your API key is missing, invalid, or has been revoked.
403	Forbidden	Your account tier does not have access to this feature.
422	Validation Error	Your request body is missing a required field or a value is invalid.
429	Rate Limited	You have exceeded the request limit for your tier. Wait a moment and retry.
402	Insufficient Credits	Your account does not have enough credits to complete this job.
500	Server Error	Something went wrong on our side. These are rare — contact support if it persists.

Reference

Rate limits

Rate limits apply per account on /v1/generate/* routes. Read-only endpoints (list avatars, get job status, etc.) share a general limit of 100 requests per minute. If you exceed a limit, you receive a 429 response — back off briefly and retry.

Plan	Generation limit
Trial	5 generation requests / min
Starter	20 generation requests / min
Pro	60 generation requests / min
Agency	200 generation requests / min

Reference

Credits

Every AI operation costs a defined number of credits. Credits are only deducted when a job is confirmed as accepted — if a job fails for any reason, your credits are returned automatically.

You can check your current balance at any time with GET /v1/billing/credits. Credit top-up packs (1,000 / 5,000 / 15,000 credits) can be purchased from the billing dashboard — credits never expire.

Ready to build?

Get started View Agency pricing