Ozor integration docs.

Getting started

Welcome to Ozor for developers

Ozor turns natural-language prompts and documents into fully animated, narrated videos. This documentation covers everything you need to drive that engine from outside the web app — whether you are an AI agent, a no-code automation, or a production service.

You can mix and match the integrations. They all hit the same backend, share the same credit balance, and produce videos that all show up in your dashboard at ozor.ai.

Getting started

Choose your integration

Each integration is a thin wrapper around the same engine. Pick by who is calling:

All three live on top of the same /api/v1/ surface. Anything you can do in the n8n node or the MCP server is also doable directly against the REST API.

Getting started

Authentication overview

There are two ways to authenticate against the Ozor engine. Every integration uses one (or both) of them.

API keys are scoped to the account that created them. Every resource (video, plan, export, job) can only be read or modified by the owning account. Revoke a key in the dashboard and the next request using it fails with 401 immediately.

Getting started

Credits & billing

Every generation operation deducts from your account credit balance. Credits are shared across all integrations — an MCP-driven generation pulls from the same bucket as an n8n run or a curl call.

• New accounts start with 10 free credits. Subscribe or buy a one-time top-up from the dashboard to add more.
• When a generation fails, no credit is deducted. Retry safely.
• If your balance is short, the endpoint returns 402 Payment Required up front — no partial work is performed.
• There is no rate limit. Usage is governed entirely by credits.

MCP / 01

What Ozor MCP is

The Model Context Protocol is an open standard for connecting AI models to external tools. The Ozor MCP server turns the full Ozor video pipeline into a set of typed tools any MCP-compatible client (Claude Desktop, Claude.ai, Cursor, VS Code, custom agents) can call from natural language.

What an agent can do with Ozor MCP, in one paragraph:

• Text → video. A short creative brief becomes a short AI-generated video. The Ozor agent picks scenes, motion, copy, and visuals.
• Document → video. A PDF, PPTX, DOCX, or web URL becomes a narrated video plan you can review, edit, and render.
• Conversational editing. Once a video exists, natural-language instructions (“add our logo to scene 2”, “make the outro shorter”) re-drive the same project.
• Export & embed. A finished project can be rendered to MP4, given a permanent public share page, and converted into a ready-to-paste <iframe>.

The server is stateless — every call carries the user's API key (via Bearer auth or the MCP OAuth flow). All persistence lives in the Ozor backend.

MCP / 02

How it works

┌────────────┐   MCP   ┌──────────────┐    HTTPS    ┌────────────────┐
│  LLM /     │ ──────► │  Ozor MCP    │ ──────────► │  Ozor API      │
│  MCP host  │ ◄────── │  server      │ ◄────────── │  (ozor.ai)     │
└────────────┘  tools  └──────────────┘   JSON      └────────────────┘
                                                          │
                                                          ▼
                                          ┌─────────────────────────────┐
                                          │ Firestore + GCS + Renderer  │
                                          └─────────────────────────────┘

The MCP server is a small Node/TypeScript program that:

• Receives MCP tool calls from the client.
• Authenticates as the end user (API key or OAuth).
• Calls the Ozor REST API at /api/v1/....
• Returns structured JSON results that the LLM presents to the user.

MCP / 03

Connect from Claude Desktop

Claude Desktop launches MCP servers as local subprocesses over stdio. The configuration lives in claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\\Claude\\claude_desktop_config.json).

1. Get an API key

Sign in at ozor.ai, open Settings → Developer → API Keys, and create a key named e.g. claude-desktop. Copy the sk_live_... value — you only see it once.

2. Add the server to your config

{
  "mcpServers": {
    "ozor": {
      "command": "npx",
      "args": ["-y", "@ozor/mcp"],
      "env": {
        "OZOR_API_KEY": "sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
      }
    }
  }
}

3. Restart Claude Desktop

Quit and relaunch the app. In a new conversation, the Ozor tools (generate_video, analyze_document, export_video, etc.) appear in the tool menu. Try it with:

Make a 20-second product teaser for a wireless headphone — minimalist, dark background, calm tone.

MCP / 04

Connect from Claude.ai (web & mobile)

Claude.ai connects to MCP servers over Streamable HTTP using OAuth 2.1 with PKCE. You never paste your API key into the browser — Ozor stores it server-side and exchanges access tokens for it on each call.

1. Open Settings → Connectors

In Claude.ai, open Settings → Connectors (or your workspace settings) and click Add custom connector.

2. Add the Ozor connector

Claude.ai discovers the OAuth endpoints from /.well-known/oauth-authorization-server automatically.

3. Authorize

A browser window opens to ozor.ai for you to sign in and approve the connection. Approving creates a server-side OAuth client tied to your account; Claude.ai receives a short-lived access token it sends as Authorization: Bearer ... on every tool call.

MCP / 05

Connect from Cursor & other IDEs

Cursor, VS Code (with the MCP extension), Zed, and Windsurf all support MCP servers. Configuration is editor-specific but follows the same shape as Claude Desktop: a command + args + environment.

Cursor

Open Cursor Settings → MCP and add:

{
  "ozor": {
    "command": "npx",
    "args": ["-y", "@ozor/mcp"],
    "env": { "OZOR_API_KEY": "sk_live_..." }
  }
}

VS Code (MCP extension)

Add to your workspace .vscode/mcp.json (or user settings) — same shape as above. Reload the window.

Anything else

Any client that supports the stdio transport can launch npx -y @ozor/mcp with OZOR_API_KEY in the environment. The tools are the same on every host.

MCP / 06

Connect over HTTP (scripts & service-to-service)

For custom agents or service-to-service flows you can talk to the hosted MCP server over Streamable HTTP with a static Authorization header — no OAuth round-trip needed.

curl -sS https://mcp.ozor.ai/messages \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "generate_video",
      "arguments": { "prompt": "A 15-second teaser for a coffee subscription" }
    }
  }'

The Bearer value here is your raw sk_live_...API key. Service-to-service is the simplest path if you already use the REST API and just want MCP's tool-shape framing.

MCP / 07

The two workflows

The decision tree is dictated by the input shape, not how the user phrased their ask. Pick by whether a document is involved.

Workflow A — Text → video

• generate_video(prompt) → { videoId, jobId, status: "pending" }
• wait_for_job(videoId, jobId) — blocks until the agent finishes; returns editorUrl.
• Present editorUrl to the user. Stop. Ask whether they want an MP4.
• (only if they say yes) export_video(videoId) → { exportId, exportStatus: "queued" }
• wait_for_export(videoId) — blocks until render completes; returns watchUrl, mp4Url, embedUrl, downloadUrl.
• Optional: get_embed_code(videoId) → ready-to-paste <iframe>.

Workflow B — Document → video

• Get the document to the server (URL, signed upload, or base64 — see analyze_document).
• analyze_document(...) → { planId, status: "draft", scenes, voiceSettings }
• Present the plan as readable chat text — scene count, credit cost, numbered scenes (title + a line of voiceover). Never show raw JSON.
• Wait for user approval. To edit, call update_plan(planId, scenes, voiceSettings?) then re-present.
• generate_from_plan(planId) → { projectId, editorUrl, title }
• From here it's the same as Workflow A: present the editor, ask about exporting, then export_video → wait_for_export.

Iterating on an existing video

• send_message(videoId, message) → { jobId }
• wait_for_job(videoId, jobId) — returns the updated editorUrl (same URL, new content).
• Point the user back at the editor. Ask before re-exporting.
• (if they want a fresh MP4) export_video(videoId) → wait_for_export(videoId). The cached export is reused if nothing render-relevant changed.

MCP / 08

URL fields — decoded

The Ozor API returns several URL fields. They mean different things and are not interchangeable. This is the section everyone gets wrong on the first integration.

Rules

• Never construct a URL from a videoId or shareCode. Even if you “know” the format. Hosts and query params can change.
• watchUrl is the link to give the user. Not mp4Url. A raw storage.googleapis.com MP4 is a download, not a watch page.
• mp4Url is for downloads and <video> embeds — not for sharing on social or sending to humans.
• If watchUrl is null, the export is private. Re-export with isPublic: true and the watch page will appear.
• editorUrl is always safe to present, even before any export exists — it lets the user preview the project on Ozor immediately after generation.

MCP / 09

Tool reference

Every tool returns a JSON body in the MCP content block. Errors come back with isError: true and a message field. All time fields are ISO 8601 strings unless noted.

{ "videoId": "...", "jobId": "...", "status": "pending" }

{
  "videos": [
    { "videoId": "...", "title": "...", "status": "draft",
      "editorUrl": "https://www.ozor.ai/editor?projectId=...",
      "createdAt": "2026-05-26T10:14:22Z" }
  ]
}

{
  "videoId": "GhWBYCdhM4omoHRv9W7p",
  "title": "Ozor MCP launch",
  "status": "complete",
  "editorUrl": "https://www.ozor.ai/editor?projectId=GhWBYCdhM4omoHRv9W7p",
  "createdAt": "2026-05-26T10:14:22Z",

  // Only once an export has been triggered:
  "exportId": "exp_...",
  "exportStatus": "complete",
  "thumbnailUrl": "https://...",
  "downloadUrl": "https://storage.googleapis.com/.../signed.mp4",

  // Only once a PUBLIC export completes:
  "shareCode": "wuq4y9t",
  "watchUrl": "https://www.ozor.ai/share/wuq4y9t",
  "embedUrl": "https://www.ozor.ai/embed/wuq4y9t",
  "mp4Url":   "https://storage.googleapis.com/.../1080p.mp4",
  "shareUrl": "https://storage.googleapis.com/.../1080p.mp4"  // deprecated alias
}

{ "videoId": "...", "editorUrl": "...", "exportId": "...",
  "exportStatus": "queued",
  "watchUrl": "...", "embedUrl": "...", "mp4Url": "...", "shareCode": "wuq4y9t" }

{ "jobId": "...", "status": "pending" }

{ "status": "completed",
  "response": "<agent reply>",
  "editorUrl": "...", "title": "..." }

{
  "videoId": "...",
  "jobId": "...",
  "status": "completed",
  "editorUrl": "https://www.ozor.ai/editor?projectId=...",
  "title": "Ozor MCP launch",
  "response": "<agent's reply text>",

  // Present only if generate_video was called with export:true:
  "exportStatus": "complete",
  "watchUrl": "...", "embedUrl": "...", "mp4Url": "...", "downloadUrl": "...",

  "notes": "Agent finished. Present editorUrl to the user, then ASK before exporting an MP4."
}

{
  "exportStatus": "complete",
  "videoId": "...",
  "shareCode": "wuq4y9t",
  "watchUrl": "https://www.ozor.ai/share/wuq4y9t",
  "embedUrl": "https://www.ozor.ai/embed/wuq4y9t",
  "editorUrl": "https://www.ozor.ai/editor?projectId=...",
  "mp4Url": "https://storage.googleapis.com/.../1080p.mp4",
  "downloadUrl": "https://storage.googleapis.com/.../signed.mp4",
  "thumbnailUrl": "...",
  "notes": "Present watchUrl as the link people open to watch on Ozor. mp4Url is the raw MP4."
}

{
  "videoId": "...",
  "shareCode": "wuq4y9t",
  "watchUrl": "...",
  "embedUrl": "...",
  "iframeEmbed": "<div style=\"position:relative;...\"><iframe src=\"...\"></iframe></div>",
  "videoTagEmbed": "<video src=\"...\" controls playsinline ...></video>",
  "mp4Url": "..."
}

{
  "planId": "plan_...",
  "status": "draft",
  "scenes": [
    { "order": 1, "sceneTitle": "Introduction",
      "scenePrompt": "Title card with logo fading in...",
      "voiceoverText": "Welcome to Acme — we're rethinking collaboration.",
      "imageRefs": [...], "keyPoints": ["intro", "brand"] }
  ],
  "voiceSettings": { ... },
  "creditCost": 3
}

{
  "uploadUrl": "https://mcp.ozor.ai/upload/<ticket>",
  "expiresInSeconds": 900,
  "curlCommand": "curl -sS -F \"file=@/ABSOLUTE/PATH/document.pdf\" \"https://mcp.ozor.ai/upload/<ticket>\"",
  "instructions": "Run curlCommand in a shell..."
}

{
  "status": "done",
  "planId": "...",
  "projectId": "HuANTASx3WdqwwngHRCs",
  "title": "Ozor MCP launch",
  "editorUrl": "https://www.ozor.ai/editor?projectId=HuANTASx3WdqwwngHRCs",
  "message": "Video project created. Present editorUrl, then ASK before exporting."
}

{ "voices": [
  { "id": "aria",   "name": "Aria",   "language": "en", "gender": "female",  "character": "Clear, precise" },
  { "id": "nova",   "name": "Nova",   "language": "en", "gender": "female",  "character": "Warm, natural" },
  { "id": "felix",  "name": "Felix",  "language": "en", "gender": "male",    "character": "Playful, upbeat" },
  { "id": "marcus", "name": "Marcus", "language": "en", "gender": "male",    "character": "Neutral, professional" },
  { "id": "thor",   "name": "Thor",   "language": "en", "gender": "male",    "character": "Deep, authoritative" },
  { "id": "luna",   "name": "Luna",   "language": "en", "gender": "female",  "character": "Soft, calm" },
  { "id": "owen",   "name": "Owen",   "language": "en", "gender": "male",    "character": "Steady, trustworthy" },
  { "id": "sky",    "name": "Sky",    "language": "en", "gender": "neutral", "character": "Light, friendly" }
] }

MCP / 10

Polling patterns

Two endpoints take real time and must be polled. Both use a wait_* tool that does the polling for you.

• Poll every 5 seconds by default.
• Time out after 5 minutes by default.
• Bump timeoutSeconds to 600 if you're rendering 4k or processing a 50-scene document plan.
• Both wait_* tools return { status: "timeout", ... } when the deadline passes — the underlying job continues, the agent can re-poll via get_job / get_video.

generate_video ────► wait_for_job ────► [present editorUrl, ASK about export]
                                                            │
                                                            ▼
                                                     export_video
                                                            │
                                                            ▼
                                                     wait_for_export
                                                            │
                                                            ▼
                                                    [present watchUrl, etc.]

MCP / 11

Presenting results to users

The MCP server returns structured JSON. The LLM's job is to translate that into something a human wants to read.

Three rules

• Never paste raw JSON. No code blocks of API responses, no curly braces.
• Never construct or guess Ozor URLs. Copy values verbatim from tool results.
• Never auto-export. After generation, stop, show the editor, ask.

After wait_for_job (just generated, no export)

After wait_for_export (export complete)

MCP / 12

Error handling

All tools return { isError: true, ...json } on failure. The body always contains a human-readable message and, where relevant, a status field.

The MCP server maps common backend errors (e.g. validation failures) into structured isError responses rather than transport-level errors — the LLM sees them as tool results, not exceptions, which makes recovery much easier.

n8n / 01

What the Ozor n8n node does

The official Ozor node on n8n.io wraps the same /api/v1/ surface as the REST API and the MCP server, but exposes every operation as a clickable action inside an n8n workflow. No code, no polling boilerplate — drag, drop, configure.

Why use the n8n node

• You already run your automations in n8n (form intake, ticket routing, content ingestion) and want video generation slotted into the same workflow.
• You don't want to write a polling loop in code — the node has a polling mode that waits for jobs and exports to finish automatically.
• You want non-engineers on your team to configure video automations without touching code.

When to choose something else

• You need request-level control (custom retries, branching mid-job, embedded in a high-traffic backend) → use the REST API directly.
• You want an AI agent (not a workflow) to make decisions about when to generate or export → use the MCP server.

n8n / 02

Install the node

Self-hosted n8n

• Open Settings → Community nodes.
• Click Install a community node and enter n8n-nodes-ozor.
• Accept the prompt and reload — the “Ozor” node now appears in the node picker.

n8n Cloud

n8n Cloud users can install the verified Ozor node directly from Workflow editor → + (add node) → search “Ozor” or via the integration page. No extra setup.

n8n / 03

Create credentials

The node uses a single Ozor API credential. Set it up once, reuse across every workflow.

• Generate a key at ozor.ai → Settings → Developer → API Keys. Name it e.g. n8n-production so you can revoke it independently.
• In n8n, click + Add credential → Ozor API.
• Paste the sk_live_... value into API Key.
• Click Save — n8n stores the credential encrypted and tests it against /api/v1/videos?limit=1.

n8n / 04

Quickstart workflow

Goal: every time someone submits a form, generate a 30-second product video and email the share link.

Form Trigger
   │  (collects: prompt, recipient_email)
   ▼
Ozor — Video / Generate
   │  Prompt:  ={{ $json.prompt }}
   │  Aspect:  16:9
   │  Wait for completion: ✓
   ▼
Ozor — Video / Export
   │  Video ID:    ={{ $json.videoId }}
   │  Quality:     1080p
   │  Public:      true
   │  Wait for completion: ✓
   ▼
Send Email (SMTP)
   To:       ={{ $('Form Trigger').item.json.recipient_email }}
   Subject:  Your Ozor video is ready
   Body:     "Watch it here: ={{ $json.watchUrl }}"

n8n / 05

Resources & operations

Pick a Resource first (Video, Document Plan, Job, Course, etc.) — the operation picker updates with the actions that apply to that resource.

n8n / 06

Field reference (Generate Video)

Every operation maps cleanly to one REST endpoint. The Generate operation on the Video resource is the most-used — its fields are the same as POST /api/v1/videos/generate.

n8n / 07

Common workflow patterns

1. Document → training video

Google Drive — Trigger (new file in /Policies/)
   ▼
Ozor — Document / Analyze Document
   File: ={{ $binary.data }}
   ▼
Ozor — Document / Generate From Plan
   Plan ID: ={{ $json.planId }}
   Wait for completion: ✓
   ▼
Ozor — Video / Export   (1080p, public)
   ▼
Slack — Send message    "New training video for {{ $('Drive Trigger').item.json.name }}: {{ $json.watchUrl }}"

2. Support ticket → tutorial

Zendesk — Trigger (ticket marked “needs-tutorial”)
   ▼
Set — Build prompt
   prompt = "60-second tutorial answering: " + {{ ticket.subject }} + "\nDetails: " + {{ ticket.body }}
   ▼
Ozor — Video / Generate (Wait for completion ✓)
   ▼
Ozor — Video / Export (Wait ✓, Public ✓)
   ▼
Zendesk — Reply to ticket
   "We turned this into a short video — {{ $json.watchUrl }}"

3. Weekly product update

Schedule Trigger — every Monday 09:00
   ▼
Linear — List recently shipped issues (since last week)
   ▼
Set — Build a single multiline prompt of all the issues
   ▼
Ozor — Video / Generate (Wait ✓, Auto-export ✓, Quality 1080p, Public ✓)
   ▼
Notion — Append block with iframe of {{ $json.embedUrl }}

4. Course generation from PDF library

Google Drive — Trigger (new file in /Course inputs/)
   ▼
Ozor — Course / Generate Course
   Source file: ={{ $binary.data }}
   Title:       ={{ $json.name.replace('.pdf','') }}
   ▼
HTTP — Notify your LMS with the new course URL
   URL: ={{ $json.publicUrl }}

5. Bulk localized renders

Google Sheets — Read rows (each row = one language target)
   ▼
Loop Over Items
   ▼
Ozor — Video / Send Message
   Message: "Translate the voiceover into ={{ $json.language }}"
   Wait for completion: ✓
   ▼
Ozor — Video / Export (Public ✓, Quality 1080p)
   ▼
Google Sheets — Update row with {{ $json.watchUrl }}

n8n / 08

Polling jobs in n8n

Most Ozor operations are async, but the node handles polling for you whenever the Wait for completion toggle is on. Behind the scenes it polls the relevant get_video / get_job endpoint at a 5-second cadence until the operation finishes or times out.

n8n / 09

Tips & troubleshooting

Expressions you'll use a lot

Out of credits

The node throws with a clear 402 Payment Required message. Wire an Error Triggerworkflow to surface this in Slack / email — n8n won't auto-retry credit failures.

Multiple inputs → one video

Use n8n's Merge or Aggregate nodes upstream — the Ozor node processes one item at a time. To combine multiple documents, merge them into a single PDF (or concatenate text into a single prompt) before calling Analyze Document.

Looping over many items

Put Loop Over Items upstream of the Ozor node and set the loop to Wait between batches: 1s — credits are the limit, not request rate, but small breathing room keeps the UI responsive.

Credentials test fails

• Re-copy the key from ozor.ai → Settings → Developer → API Keys — no leading/trailing whitespace.
• Confirm the key is active (not revoked) in the dashboard.
• Make sure your n8n instance can reach https://ozor.ai — proxies and corporate firewalls sometimes block it.

API / 01

Getting started

Create an API key

API keys are created from the dashboard at ozor.ai (Settings → Developer → API Keys) or programmatically through the key-management endpoints. Those management endpoints are authenticated with your Firebase ID token — the same session your browser uses after logging in — not with an API key.

Key format: sk_live_ followed by 32 hex characters (40 characters total). The raw key is shown once, at creation time. Ozor stores only a SHA-256 hash and can never show it again — save it to a secret manager immediately.

Make your first call

curl -X POST https://ozor.ai/api/v1/videos/generate \
  -H "X-API-Key: sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A 15-second ad for a minimalist desk lamp"}'

API / 02

Authentication

All public endpoints live under /api/v1/* and require the X-API-Key header:

X-API-Key: sk_live_<32-hex-chars>

Keys are scoped to the account that created them. Every resource (video, plan, export, job) can only be read or modified by the owning account.

There is no rate limiting — usage is governed entirely by your credit balance.

API / 03

API key management

These endpoints manage API keys themselves. They are authenticated with a Firebase ID token (Authorization: Bearer <firebase_id_token>), not an API key.

{ "name": "Production" }

{
  "keyId": "abc123xyz",
  "name": "Production",
  "prefix": "sk_live_a1b2",
  "rawKey": "sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "createdAt": 1705312200000
}

[
  {
    "keyId": "abc123xyz",
    "name": "Production",
    "prefix": "sk_live_a1b2",
    "status": "active",
    "createdAt": 1705312200000,
    "lastUsedAt": 1705400100000
  }
]

{ "message": "API key abc123xyz revoked" }

API / 04

Credits

Every generation operation deducts from your account's credit balance.

If your balance is insufficient for an operation, the endpoint responds with 402 Payment Required. No partial work is performed, and no credit is deducted on failure.

New accounts receive 10 free credits. You can buy more — a subscription or a one-time credit top-up — from the dashboard.

API / 05

Quickstart

Generate, render, and get a shareable link:

# Step 1 — Kick off generation + auto-export as public
curl -X POST https://ozor.ai/api/v1/videos/generate \
  -H "X-API-Key: $OZOR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 20s product teaser for a wireless headphone",
    "aspect": "16:9",
    "export": true,
    "exportQuality": "1080p",
    "exportIsPublic": true
  }'
# -> { "videoId": "abc123", "jobId": "job_...", "status": "pending" }

# Step 2 — Poll until the export is done
curl https://ozor.ai/api/v1/videos/abc123 \
  -H "X-API-Key: $OZOR_API_KEY"
# -> when exportStatus == "complete":
#    { "shareUrl": "...", "downloadUrl": "...", "shareCode": "a3kf92p", ... }

See Polling patterns for the full set of workflows.

API / 06

Video endpoints

All video endpoints live under /api/v1/videos/* and use X-API-Key auth.

{
  "prompt": "Create a 30-second product showcase for a wireless headphone",
  "aspect": "16:9",
  "export": true,
  "exportQuality": "1080p",
  "exportIsPublic": true,
  "images": [
    { "url": "https://example.com/product.jpg" }
  ],
  "videos": [
    { "url": "https://example.com/clip.mp4", "mimeType": "video/mp4", "durationSec": 8.5 }
  ]
}

{ "videoId": "abc123", "jobId": "job_s0m3R4nd0mId", "status": "pending" }

{
  "videos": [
    {
      "videoId": "abc123",
      "title": "Product showcase for a wirel...",
      "status": "draft",
      "editorUrl": "https://ozor.ai/editor?projectId=abc123",
      "createdAt": "2026-04-20T10:30:00Z"
    }
  ]
}

{
  "videoId": "abc123",
  "title": "Product showcase...",
  "status": "draft",
  "editorUrl": "https://ozor.ai/editor?projectId=abc123",
  "createdAt": "2026-04-20T10:30:00Z",

  "exportId": "exp_xyz789",
  "exportStatus": "complete",
  "downloadUrl": "https://storage.googleapis.com/.../video.mp4",
  "shareUrl":    "https://storage.googleapis.com/.../video.mp4",
  "shareCode":   "a3kf92p",
  "thumbnailUrl":"https://storage.googleapis.com/.../thumb.jpg",
  "exportError": null
}

{ "quality": "1080p", "isPublic": true }

{
  "videoId": "abc123",
  "exportId": "exp_xyz789",
  "exportStatus": "queued",
  "shareCode": "a3kf92p"
}

{
  "message": "Add our logo in the top-right corner of every scene",
  "images": [ { "base64": "<base64-encoded-png>", "mimeType": "image/png" } ]
}

{ "videoId": "abc123", "jobId": "job_s0m3R4nd0mId", "status": "queued" }

{
  "videoId": "abc123",
  "jobId": "job_s0m3R4nd0mId",
  "status": "processing",
  "createdAt": "2026-04-20T10:30:00Z"
}

{
  "videoId": "abc123",
  "jobId": "job_s0m3R4nd0mId",
  "status": "completed",
  "response": "I've added the logo to the top-right corner of all 4 scenes.",
  "createdAt": "2026-04-20T10:30:00Z"
}

{
  "videoId": "abc123",
  "jobId": "job_s0m3R4nd0mId",
  "status": "failed",
  "error": "Agent encountered an error: ...",
  "createdAt": "2026-04-20T10:30:00Z"
}

{
  "videoId": "abc123",
  "conversationId": "conv_xyz",
  "totalAssistantTurns": 3,
  "totalToolCalls": 11,
  "messages": [
    {
      "messageId": "msg_1",
      "createdAt": "2026-04-20T10:30:05Z",
      "textPreview": "I've created the opening scene...",
      "toolCalls": [
        { "name": "create_scene", "args": { "order": 1, "title": "Intro" } }
      ]
    }
  ]
}

API / 07

Document-to-video endpoints

Turn a PDF, PowerPoint, Word document, or web URL into a narrated video with an auto-selected voice, scenes, and images extracted from the source.

{
  "voices": [
    { "id": "aria",   "label": "Aria",   "gender": "female",  "character": "Clear, precise" },
    { "id": "nova",   "label": "Nova",   "gender": "female",  "character": "Warm, natural" },
    { "id": "felix",  "label": "Felix",  "gender": "male",    "character": "Playful, upbeat" },
    { "id": "marcus", "label": "Marcus", "gender": "male",    "character": "Neutral, professional" },
    { "id": "thor",   "label": "Thor",   "gender": "male",    "character": "Deep, authoritative" },
    { "id": "luna",   "label": "Luna",   "gender": "female",  "character": "Soft, calm" },
    { "id": "owen",   "label": "Owen",   "gender": "male",    "character": "Steady, trustworthy" },
    { "id": "sky",    "label": "Sky",    "gender": "neutral", "character": "Light, friendly" }
  ]
}

{
  "plan": {
    "planId": "plan_a1b2c3d4e5f6",
    "fileName": "pitch-deck.pdf",
    "fileType": "pdf",
    "sourceUrl": null,
    "aspectRatio": "16:9",
    "status": "draft",
    "language": "en",
    "style": {
      "colors": ["#0F172A", "#3B82F6"],
      "fonts": ["Inter"],
      "tone": "professional",
      "layout": "slide"
    },
    "scenes": [
      {
        "order": 1,
        "sceneTitle": "Introduction",
        "scenePrompt": "A blue-tinted title card with the company logo fading in...",
        "voiceoverText": "Welcome to Acme — we're rethinking how teams collaborate.",
        "imageRefs": [
          { "storagePath": "users/uid/plans/plan_.../page_0_img_0.png",
            "url": "https://storage.googleapis.com/..." }
        ],
        "keyPoints": ["intro", "brand"]
      }
    ],
    "projectId": null,
    "error": null,
    "createdAt": 1705312200,
    "updatedAt": 1705312200,
    "createdVia": "api",
    "creditsCost": 3
  }
}

{
  "scenes": [
    {
      "order": 1,
      "sceneTitle": "Introduction",
      "scenePrompt": "A blue-tinted title card...",
      "voiceoverText": "Welcome to Acme — we're reimagining collaboration.",
      "imageRefs": [
        { "storagePath": "users/uid/plans/plan_.../page_0_img_0.png" }
      ],
      "keyPoints": ["intro"]
    }
  ],
  "voiceSettings": {
    "voiceId": "nova",
    "speakingStyle": "warm",
    "speakingRate": 1.0
  }
}

data: {"step": "...", "detail": "...", "pct": 0-100}

data: {"step": "init",     "detail": "Starting generation",     "pct": 0}
data: {"step": "tts",      "detail": "Generating voiceover 1/6", "pct": 15}
data: {"step": "scenes",   "detail": "Rendering scene 3/6",      "pct": 55}
data: {"step": "assembly", "detail": "Assembling project",       "pct": 90}
data: {"step": "done",     "detail": "Video project ready!",     "pct": 100, "projectId": "abc123"}

data: {"step": "error", "detail": "TTS failed: ...", "pct": -1}

API / 08

Media attachments

Both POST /api/v1/videos/generate and POST /api/v1/videos/{videoId}/message accept optional images and videos arrays. Each item may be supplied as a URL, a base64 payload, or both.

Image object (ChatImage)

Video object (ChatVideo)

API / 09

Polling patterns

Generate + auto-export

POST /api/v1/videos/generate   { ..., "export": true, "exportIsPublic": true }
  -> { videoId, jobId, status: "pending" }

Poll GET /api/v1/videos/{videoId}
  - wait until "exportStatus" appears (agent finished, export queued)
  - wait until "exportStatus" === "complete"
  -> { shareUrl, downloadUrl, shareCode, thumbnailUrl, ... }

Suggested cadence: 2–3 seconds between polls for the first minute, 5–10 seconds after that. Typical end-to-end time ranges from tens of seconds to a few minutes, depending on prompt complexity and export quality.

Generate, then export separately

POST /api/v1/videos/generate              { prompt: "..." }
  -> { videoId, jobId, status: "pending" }

Poll GET /api/v1/videos/{videoId}/jobs/{jobId}   until status === "completed"

POST /api/v1/videos/{videoId}/export      { quality: "1080p", isPublic: true }
  -> { exportId, exportStatus: "queued", shareCode }

Poll GET /api/v1/videos/{videoId}         until exportStatus === "complete"

Iterative edit

POST /api/v1/videos/{videoId}/message     { message: "Change background to dark blue" }
  -> { jobId, status: "queued" }

Poll GET /api/v1/videos/{videoId}/jobs/{jobId}   until status === "completed"

POST /api/v1/videos/{videoId}/export      { quality: "1080p" }
  -> poll GET /api/v1/videos/{videoId}   until exportStatus === "complete"

Document → video

POST /api/v1/documents/analyze            (multipart: file + target_duration_sec + ...)
  -> { plan: { planId, scenes: [...], creditsCost } }

(optional) PATCH /api/v1/documents/plans/{planId}   { scenes, voiceSettings }

POST /api/v1/documents/plans/{planId}/generate      (consume SSE stream)
  -> final event: { step: "done", projectId }

POST /api/v1/videos/{projectId}/export    { quality: "1080p", isPublic: true }
  -> poll GET /api/v1/videos/{projectId}  until exportStatus === "complete"

API / 10

Error responses

All errors are JSON with a detail field.

Example

{ "detail": "You are out of credits. Please add more to continue chatting." }

API / 11

Reference tables

Aspect ratios

Export qualities

Output is always mp4 at 30 fps.

Share code

When an export is public, a 7-character alphanumeric shareCode (e.g. a3kf92p) is generated. shareUrl is the permanent public URL to the MP4; shareCode is the handle used internally and in the web UI to look up the shared video.

Video statuses

Export statuses

Agent job statuses

TTS voices

Document formats

Max file size: 50 MB. A http(s):// URL may be supplied instead of a file.

Resources

Glossary

Resources

FAQ

Can I use Ozor without an API key?

Yes — the web app at ozor.ai works without one. API keys, the n8n node, and the MCP server are only needed when you want to drive Ozor from outside the web app.

Are videos generated through the API visible in the web app?

Yes — every video shows up in your dashboard regardless of which integration created it. The reverse is not true: GET /api/v1/videos only lists API-originated videos (this scoping is intentional, to keep the list deterministic for scripts).

How do I include reference images?

Pass them in the images array of either POST /videos/generate or POST /videos/{videoId}/message. URL or base64 both work — see Media attachments.

How do I make the same video in 16:9 and 9:16?

Generate twice with different aspectvalues. Scenes are computed per-aspect, so a single project doesn't hold both — separate videoIds. Tip: drop the same prompt + brand kit into both calls.

Can I keep my export private?

Yes. Omit isPublic (or set it to false) on POST /videos/{videoId}/export. You'll get a 24h-signed downloadUrl but no watchUrl, embedUrl, or shareCode — no public page exists.

What happens if a render fails?

exportStatus becomes failed and exportError contains the reason. No credit is deducted. You can re-run POST /export as many times as needed.

Is there a webhook for “export complete”?

Not yet — polling is the supported pattern today. The MCP server and n8n node both wrap that polling for you; for direct API integrations, see Polling patterns. Outbound webhooks are on the roadmap.

How do I rotate a leaked key?

Open the dashboard, deletethe compromised key (it's revoked instantly), and create a new one. Update wherever it's stored (env var, n8n credential, MCP config).

Where do I report a bug or request a feature?

Email support@ozor.ai with reproduction steps. For API issues, include the X-Request-ID header from your response — it helps us trace the call end-to-end.