Developers

Ozor integration docs.

Three ways to drive Ozor from your stack — the Model Context Protocol server for AI agents, the official n8n node for no-code workflows, and the REST API for everything else. One auth model, one credit balance, one underlying engine.

Base URL

https://ozor.ai

MCP server

https://api.ozor.ai/mcp

API version

/api/v1/

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.

Where to find an API key

Sign in at ozor.ai and open Settings → Developer → API Keys. The raw key (sk_live_ + 32 hex chars) is shown once at creation time — copy it into a secret manager immediately. You can have up to 5 active keys per account.

Getting started

Choose your integration

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

IntegrationWho it's forAuthUse it when
MCP serverAI assistants: Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code, custom MCP clients.OAuth or API keyYou want an assistant to build the video in conversation: it writes the scenes, Ozor checks, narrates and renders them.
n8n nodeOperations & automation teams using n8n.API key credentialYou want to wire video generation into a Zapier-style workflow (form → video, doc → course, etc.) without writing code.
REST APIYour own backend, scripts, or any HTTP client.X-API-Key headerYou need full programmatic control — custom polling, your own queue, batching, embedded in your product.

The n8n node and the REST API share the same /api/v1/surface, where Ozor's own agent writes the video. The MCP server is different by design: the connected assistant writes the scenes and Ozor checks, narrates and renders them.

Getting started

Authentication overview

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

MethodHeader / mechanismUsed by
API keyX-API-Key: sk_live_<32 hex>REST API, n8n credential, MCP from scripts and CI (also accepted as a Bearer token).
OAuth 2.1 (PKCE)Authorization: Bearer <access_token> — issued by Ozor after the person approves the connection at ozor.ai/connect.MCP: Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code.
Firebase ID tokenAuthorization: Bearer <firebase_id_token>API key management endpoints only — the same session your browser uses after sign-in.

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-built video pulls from the same bucket as an n8n run or a curl call.

OperationCostWhen deducted
Generate video (text prompt)1 creditOn successful job completion
Send message / edit instruction1 creditOn successful job completion
Video your own Claude / ChatGPT writes (one-click connection)1 credit per video, up to 10 narrated scenes — 50% fewerWhen its first scene is saved
Analyze document (build a plan)0 credits—
Generate from document planmax(1, floor(voiceover_scenes / 2))On successful completion
Export an MP40 credits—
All read endpoints (list, get, jobs)0 credits—
  • New accounts start with 6 free credits. Subscribe or buy a one-time top-up from the dashboard to add more.
  • Connect Claude or ChatGPT in one click from developer settings and your assistant writes the scenes itself, so videos use 50% fewer credits: 1 credit covers a whole video with up to 10 narrated scenes, and edits are free. Details in MCP credits.
  • 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.

Integration

MCP integration

MCP / 01

What Ozor MCP is

The Model Context Protocol is an open standard for connecting AI assistants to external tools. Ozor's MCP server lets Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code or any MCP client build narrated videos in the person's Ozor account.

The assistant writes the video.Every scene is a React component rendered once per frame at 30 fps, and the connected assistant writes it after reading Ozor's scene guide. Ozor runs no language model for these videos. Its tools do the machinery around the code:

  • Check.Every scene is compiled, linted against the renderer's rules and rendered (first, middle and last frame) before it is saved. See Scene checks.
  • Narrate. A scene's voiceover text becomes AI narration in one of eight voices, and the scene is stretched to fit the audio.
  • Brand and assets.The person's brand kit is injected into every scene; logos, uploaded images and imported images are available as asset: refs.
  • Store, preview and export. Scenes are saved to a normal Ozor project the person opens in the editor. Frame previews come back as images, and exports render MP4s with a watch page and embed.

Why it is built this way

Because the assistant writes the scenes, the tokens are spent on the person's own AI plan, and Ozor only charges for narration and storage: one credit per video for up to ten narrations. See Credits.

MCP / 02

How it works

architecture
┌──────────────────┐  MCP (Streamable HTTP)  ┌──────────────────────────┐
│ Claude, ChatGPT, │ ──────────────────────► │ https://api.ozor.ai/mcp  │
│ Codex, Cursor... │ ◄────────────────────── │ checks · voices · stores │
└──────────────────┘    tools + JSON         └────────────┬─────────────┘
   writes the scene                                       │
   code and narration                                     ▼
                                          ┌──────────────────────────────┐
                                          │ Ozor project · TTS · renderer │
                                          └──────────────────────────────┘
Details
Endpointhttps://api.ozor.ai/mcp
TransportMCP Streamable HTTP, stateless, JSON responses. No session to keep: every request stands alone.
AuthOAuth 2.1 with PKCE (discovered from the 401's WWW-Authenticate header), or an Ozor API key as Authorization: Bearer sk_live_... or X-API-Key.
IdentityEvery call runs as the person who approved the connection (or owns the key). Tools never take a user id.
AnswersCompact JSON. Scene code is never echoed back unless asked for, to keep the assistant's context small.

One source of truth for links

Every link (editorUrl, watchUrl, embedUrl, mp4Url) comes from a tool result. Never build an Ozor URL from a videoId or share code. See URL fields.

MCP / 03

Connect your assistant

Every client uses the same URL and the same approval page. Signed in to Ozor, open Developer → Connect AI assistants for one-click versions of each of these.

ClientHowPlan notes
ClaudeConnectors → Add custom connector, name it Ozor, paste the URL, Connect.Every plan; the free plan allows one custom connector. Web and desktop app.
ChatGPTSettings → Apps & Connectors → Advanced settings: turn on developer mode. Then Create, name it Ozor, paste the URL, choose OAuth.Developer mode is on paid plans.
Claude CodeOne command (below), then /mcp → Authenticate.Approve on the same computer Claude Code runs on.
CodexOne command (below) that adds the server and starts the login.Terminal and IDE extension.
CursorAdd to Cursor in Ozor, or mcp.json (below).Signs in on first use.
VS CodeAdd to VS Code in Ozor, or .vscode/mcp.json (below).Signs in on first use.

Claude Code and Codex

bash
# Claude Code: then run /mcp inside Claude Code and choose "Authenticate"
claude mcp add --transport http ozor 'https://api.ozor.ai/mcp'

# Codex: adds the server and opens the approval in your browser
codex mcp add ozor --url 'https://api.ozor.ai/mcp' && codex mcp login ozor

Cursor and VS Code

cursor · mcp.json
{
  "mcpServers": {
    "ozor": { "url": "https://api.ozor.ai/mcp" }
  }
}
vs code · .vscode/mcp.json
{
  "servers": {
    "ozor": { "type": "http", "url": "https://api.ozor.ai/mcp" }
  }
}

The approval

The client opens ozor.ai/connect. The person signs in (or signs up free), sees which app is asking and which host it will return to, and clicks Approve. Apps Ozor does not recognize are flagged on that page. Approved, the app can create videos and edit their scenes, use the brand kit and images, add narration (with the person's credits), and render MP4s and share links.

Connections are listed, with when each was last used, under Developer → Connected AI apps. Revoking one makes its next call fail with 401.

Verify the connection

Ask the assistant “Which Ozor tools do you have?” It should list get_scene_guide, start_video, add_scene, preview_scene, export_video and the rest of the tool reference.

MCP / 04

Connect with an API key (scripts & CI)

For pipelines, scheduled jobs and clients that cannot do OAuth, send an Ozor API key instead. Create one under Developer → API Keys; it acts as your account exactly like an OAuth connection.

claude code, headless
claude mcp add --transport http ozor https://api.ozor.ai/mcp \
  --header "Authorization: Bearer $OZOR_API_KEY"

Or call the endpoint directly with JSON-RPC. The server is stateless, so no initialize handshake is needed:

bash
curl -sS https://api.ozor.ai/mcp \
  -H "Authorization: Bearer $OZOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "get_account", "arguments": {} }
  }'

Keep keys in a secret manager, use one key per pipeline so each can be revoked on its own, and never commit one to a repository.

MCP / 05

The build loop

The server's instructions tell every client to build in front of the person, one scene at a time:

flow
get_scene_guide            once per conversation: the rules the renderer enforces
get_brand_kit              colors, fonts, logo (also injected into every scene)
search_logos / list_my_images / import_image / search_icons   as the video needs
        │
        ▼
start_video ──► share editorUrl ("Your video is started in Ozor: …")
        │
        ▼
add_scene ×N ──► after each: "✓ Scene 2/5 — The problem (3.4 s, narrated)"
        │        (a failed check returns the error: fix that scene, call again)
        ▼
give editorUrl ──► STOP. Do not export on your own.
        │
        ▼ only when the person asks for an MP4 or a share link
export_video ──► get_export ──► present watchUrl exactly as returned

Editing

  • get_scene_code(video_id, scene_id) reads one scene back; get_video lists the scenes with their ids, timing and narration.
  • update_scene changes only that scene: code, title, duration, data and/or narration. New code goes through the same checks.
  • add_scene with position inserts a scene; delete_scene removes one and its narration.
  • The person can also keep editing in the Ozor editor; both edit the same project.

All at once

create_videotakes 1–20 scenes in one call and checks them all before saving any. Use it only when the person does not want to watch the video being built; it costs the same.

MCP / 06

Writing scenes

get_scene_guide is the full contract and the assistant should read it before writing anything. The short version:

tsx
import { React, getProgress, ease, lerp } from '/shared-lib';

export const Scene = ({ width, height, frame, durationSec = 3, data }) => {
  const totalFrames = Math.round(durationSec * 30);
  const c = data?.brand?.colors || {};
  const p = getProgress(frame, 6, 18, ease.outExpo);          // 0 → 1, frames 6–24
  const drift = Math.sin(frame / 40) * 12;                    // ambient motion
  return (
    <div style={{ width, height, position: 'relative', overflow: 'hidden',
                  background: c.background || '#0E1116' }}>
      <h1 style={{ color: c.text || '#F5F3EF', fontSize: height * 0.1, opacity: p,
                   transform: `translateY(${lerp(40, 0, p) + drift}px)` }}>
        {data?.headline || 'Ship the story'}
      </h1>
    </div>
  );
};
RuleWhy
One export const Scene, ending in };; inline styles onlyThe renderer mounts exactly that component, in preview and in the MP4 export.
Everything that moves is a function of frameFrames render in any order on any machine. No Math.random, Date.now, timers, requestAnimationFrame or CSS transitions.
Import only from /shared-libReact and hooks, motion (Framer Motion, frame-driven), GSAP with SplitText, MorphSVG, DrawSVG, MotionPath, Physics2D, ScrambleText, CustomEase and Flip, Recharts, D3, Three.js, Lottie, Lucide Icons, and the getProgress / ease / lerp helpers.
Size from width / heightExports are 1920×1080 or 1080×1920; previews are smaller.
Copy from data, with fallbacksThe scene must work with or without a brand kit. Brand tokens arrive as data.brand.
Images only as asset: refs<AssetImage assetRef="asset:user:ID" /> with refs from search_logos, list_my_images, import_image or get_brand_kit. Scenes cannot load URLs.
Text at least 13px (22px for anything that matters)Readable at every export size.

Scenes run 0.5–30 seconds, or as long as their narration. Narration is 1–3 short sentences per scene, 500 characters at most. A video holds up to 60 scenes. For a head start, list_recipes searches 121 tested example scenes by topic and get_recipe returns one to adapt.

MCP / 07

Scene checks

add_scene, update_scene and create_video check every scene before anything is saved, voiced or charged. The checks are programmatic; no AI is involved.

CheckVerifiesTypical failures
parseThe TSX compiles.Unbalanced braces, ${} outside a template string, a second export.
rulesOnly /shared-lib names, every identifier declared, real Lucide icons and easings, no wall-clock APIs, CSS transitions, external URLs or unsupported Framer Motion, text ≥ 13px.import … from 'framer-motion', ease.outQuad, an invented icon, Math.random().
renderFirst, middle and last frame render in the engine that exports the MP4, with the scene's data, brand kit and duration.Reading a property of undefined data, “x is not a function”, frames that are one flat color.

A failing call returns an error that names the scene, the check and the exact message (line and column for parse errors). Nothing is saved; fix only that scene and call again.

tool error
Not saved: fix this and call add_scene again.
  failed check: rules
  ✗ [unknown-icon] `ChartGrowth` is not an icon in the renderer's lucide bundle, ...
  • force: true accepts quality errors the assistant could not fix (e.g. a frame blank on purpose). Parse errors, bad imports and render crashes are never accepted.
  • Saved scenes report checks: { parse, rules, render }. render: "skipped" means the renderer was briefly unreachable; the export renders every scene again anyway.
  • validate_scene runs the same checks without saving (free). preview_scene returns real frames as images.

MCP / 08

Credits

WhatCost
A video built through MCP1 credit, covering its first 10 narrations
Every 10 more narrations (a scene's voiceover, or a re-voice)1 credit
Narration added to a video made in the Ozor editor1 credit per 10 narrations (no video fee)
start_video, code edits, delete_scene, previews, checks, readsFree
export_video (720p, 1080p, 4K)Free
  • The credit is charged with the first scene; start_video only checks that the account has credits left.
  • Scene-by-scene and all-at-once cost the same.
  • A scene that fails its checks is not charged. If narration fails to synthesize, its charge is refunded and the scene is saved silent.
  • Out of credits, a build call fails with a message that gives the balance and where to top up. get_account shows the balance and plan.

MCP / 09

URL fields

FieldWhat it isWhen set
editorUrlThe video in the Ozor editor, where the person watches and tweaks it.From start_video on, in every build result.
watchUrlPublic watch page. The link to share.When a public export is complete.
embedUrlPlayer for an <iframe src>.When a public export is complete.
mp4UrlThe MP4 file, for downloads and <video> tags. Private exports' links expire in 24 hours.When any export is complete.
thumbnailUrlPoster image.When the export has one.
  • Never construct a URL from a videoId or share code; copy it from the result.
  • editorUrl is the default answer when a video is done.
  • watchUrl is the link to share, not mp4Url.
  • No watchUrl? The export was private (public: false); export again with public: true.

MCP / 10

Tool reference

22 tools. Results are compact JSON (shown pretty-printed here). Tools marked read change nothing; delete_scene is the only destructive one.

Reference

TOOLget_scene_guide

The scene authoring rules: component contract, /shared-lib API, motion, composition, durations, the checks, and a reference scene. Read once per conversation before writing scenes. read

Returns

Markdown text.

TOOLlist_recipes

Tested example scenes ranked for a query such as kpi dashboard, product ui, quote, logo outro or chart. read

FieldTypeRequiredNotes
querystringNoWhat the scene needs to show.
familystringNoExact animation family, e.g. kinetic-cascade.
limitnumberNoDefault 12, max 50.
returns
{ "recipes": [
  { "recipe": "KPIDashboard_LiveTiles", "title": "...", "family": "kpi-dashboard",
    "durationSec": 5, "description": "..." }
] }
TOOLget_recipe

The full code of one recipe. Adapt it; never ship it unchanged. read

FieldTypeRequired
recipestring (name from list_recipes)Yes
returns
{ "recipe": "...", "title": "...", "family": "...", "durationSec": 5, "code": "import { React, ... } from '/shared-lib'; ..." }
TOOLsearch_icons

Find valid Lucide icon names. Unknown names crash the render. read

FieldTypeRequiredNotes
querystringYese.g. chart, security.
limitnumberNoDefault 12, max 40.
returns
{ "icons": [{ "name": "ChartLine", "category": "charts" }],
  "exactNameExists": false, "usage": "const { Name } = Icons; ..." }

Brand, images and voices

TOOLget_brand_kit

The person's brand kit. The same tokens are injected into every scene as data.brand. read

returns
{ "hasBrandKit": true, "name": "Acme", "tagline": "...", "tone": ["confident"],
  "brand": { "colors": { "primary": "...", "accent": "...", "background": "...", "text": "..." },
             "fonts": { "heading": "...", "body": "..." } },
  "logoAssetRef": "asset:user:abc123" }
TOOLsearch_logos

Company and product logos from Ozor's library. read

FieldTypeRequiredNotes
querystringYesBrand name, e.g. slack.
limitnumberNoDefault 8, max 20.
returns
{ "logos": [{ "name": "Slack", "assetRef": "asset:global:...",
  "recommendedBackground": "light", "theme": "color" }] }
TOOLlist_my_images

Images in the person's Ozor library. read

FieldTypeRequiredNotes
limitnumberNoDefault 30, max 50.
returns
{ "images": [{ "name": "dashboard.png", "assetRef": "asset:user:...",
  "description": "...", "recommendedBackground": "dark" }] }
TOOLimport_image

Copy a public image (PNG, JPEG, WebP, GIF or SVG, max 15 MB) into the person's library and get an assetRef.

FieldTypeRequiredNotes
urlstringYesPublic https URL.
namestringNo—
descriptionstringNoWhat the image shows; helps later reuse.
returns
{ "assetRef": "asset:user:...", "name": "...", "mime": "image/png", "bytes": 48213 }
TOOLlist_voices

Narration voices for the voice field. read

returns
{ "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" }
] }
TOOLget_account

Credit balance, plan, and what a video costs. read

returns
{ "credits": 42, "plan": "pro", "pricing": "1 credit per video, covering up to 10 narrations; ...",
  "billingUrl": "https://www.ozor.ai/settings" }

Check and preview

TOOLvalidate_scene

Run the three scene checks without saving. Free. read

FieldTypeRequiredNotes
codestringYesThe full TSX scene.
video_idstringNoAlso check against this video's other scenes (and use its aspect).
duration_secnumberNo—
dataobjectNoThe data you will pass with the scene.
aspect"16:9" | "9:16"No—
renderbooleanNofalse runs parse and rules only. Default true.
returns
{ "ok": false, "checks": { "parse": "passed", "rules": "failed", "render": "not run" },
  "errors": [{ "rule": "bad-easing", "message": "..." }], "warnings": [], "forceCanAccept": false }
TOOLpreview_scene

Render the entrance, middle and exit frames of a scene (or up to 4 chosen frames) and return them as images. Pass code for an unsaved scene, or video_id + scene_id. read

FieldTypeRequiredNotes
codestringNoUnsaved scene code.
video_id, scene_idstringNoA saved scene.
duration_sec, data, aspect—NoAs in validate_scene.
framesnumber[]NoUp to 4 frame numbers (30 fps).

Returns a text block (durationSec, size, frames) followed by image blocks. Previews are scaled down; exports render at full size.

Build and edit

TOOLstart_video

Create an empty video and get its editorUrl. Nothing is charged until the first scene.

FieldTypeRequiredNotes
titlestringYes—
aspect"16:9" | "9:16"NoDefault "16:9".
voicevoice idNoNarration voice for every scene. Default picks one for the language.
languagestringNoISO 639-1, e.g. es. Default en.
use_brand_kitbooleanNoDefault true.
returns
{ "videoId": "GhWBYCdhM4omoHRv9W7p", "title": "Approvals in one click", "aspect": "16:9",
  "editorUrl": "https://www.ozor.ai/editor?projectId=GhWBYCdhM4omoHRv9W7p", "next": "..." }
TOOLadd_scene

Add one scene, checked before it is saved. The first scene of a video started over MCP charges its credit.

FieldTypeRequiredNotes
video_idstringYes—
codestringYesThe full TSX scene.
titlestringNoLabel in the editor timeline.
positionnumberNo1-based. Default: appended.
duration_secnumberNo0.5–30. With narration, at least the audio length.
voiceoverstringNo1–3 short sentences, max 500 characters. Omit for a silent scene.
dataobjectNoContent the code reads as data; brand tokens are added.
voice, language—NoDefault: the video's.
forcebooleanNoSee Scene checks.
returns
{ "videoId": "...", "sceneId": "...", "order": 2, "sceneCount": 2, "durationSec": 3.4,
  "videoDurationSec": 5.8, "checks": { "parse": "passed", "rules": "passed", "render": "passed" },
  "creditsUsed": 0, "voiceover": "ok", "editorUrl": "https://www.ozor.ai/editor?projectId=..." }
TOOLcreate_video

Create a whole video in one call. Every scene is checked first; if any fails, nothing is saved or charged and the error lists each failing scene. Prefer start_video + add_scene.

FieldTypeRequiredNotes
titlestringYes—
scenesarray (1–20)YesEach: code (required), title, duration_sec, voiceover, data.
aspect, voice, language, use_brand_kit, force—NoAs in start_video / add_scene.
returns
{ "videoId": "...", "title": "...", "aspect": "16:9", "totalDurationSec": 31.5,
  "creditsUsed": 1, "editorUrl": "...", "scenes": [ ... ], "next": "..." }
TOOLupdate_scene

Change one scene. New code or data is checked before saving; new narration re-times the scene to the audio and counts toward the video's narrations.

FieldTypeRequiredNotes
video_id, scene_idstringYes—
code, title, duration_sec, data—NoOnly what changes.
voiceoverstringNoNew narration; "" removes it.
voice, language, force—No—
returns
{ "videoId": "...", "sceneId": "...", "saved": true, "durationSec": 4.1,
  "checks": { ... }, "voiceover": "...", "creditsUsed": 0 }
TOOLdelete_scene

Remove a scene and its narration. Destructive.

FieldTypeRequired
video_id, scene_idstringYes
returns
{ "videoId": "...", "deleted": "<scene_id>" }

Read

TOOLlist_videos

The person's most recent videos, from the app and from MCP. read

FieldTypeRequiredNotes
limitnumberNoDefault 20, max 50.
returns
{ "videos": [{ "videoId": "...", "title": "...", "aspect": "16:9", "scenes": 5,
  "durationSec": 31.5, "createdVia": "mcp", "editorUrl": "..." }] }
TOOLget_video

A video's scenes (ids, titles, timing, narration, data) and its latest export. Code is left out unless include_code: true; prefer get_scene_code for one scene. read

returns
{ "videoId": "...", "title": "...", "aspect": "16:9", "totalDurationSec": 31.5, "editorUrl": "...",
  "scenes": [{ "sceneId": "...", "order": 1, "title": "Hook", "startSec": 0, "durationSec": 2.4,
               "voiceover": "...", "data": { ... } }],
  "latestExport": { "exportId": "...", "status": "complete", "quality": "1080p",
                    "visibility": "public", "watchUrl": "...", "embedUrl": "...", "mp4Url": "..." } }
TOOLget_scene_code

One scene's current code, narration and data, to edit it. read

returns
{ "sceneId": "...", "title": "...", "durationSec": 3.4, "voiceover": "...", "data": { ... }, "code": "..." }

Export

TOOLexport_video

Render the video to an MP4. Free. Only when the person asks for an MP4 file or a share link.

FieldTypeRequiredNotes
video_idstringYes—
quality"720p" | "1080p" | "4k"NoDefault "1080p".
publicbooleanNoDefault true: a shareable watch page and embed.
returns
{ "exportId": "...", "status": "queued", "visibility": "public",
  "next": "Call get_export with this exportId; it waits for the render to finish." }

An identical export that already exists comes back complete straight away.

TOOLget_export

Export status. Waits up to wait_seconds (default 40, capped at 45) for the render, then returns; call again while it is still rendering. read

FieldTypeRequiredNotes
video_idstringYes—
export_idstringNoDefault: the latest export.
wait_secondsnumberNoDefault 40.
returns when complete
{ "exportId": "...", "status": "complete",
  "watchUrl": "https://www.ozor.ai/share/wuq4y9t",
  "embedUrl": "https://www.ozor.ai/embed/wuq4y9t",
  "mp4Url": "https://storage.googleapis.com/.../1080p.mp4",
  "thumbnailUrl": "...", "durationSec": 31.5, "editorUrl": "...",
  "present": "Give the person watchUrl to watch and share it; mp4Url downloads the file. ..." }

While rendering, status is queued or processing with a progress value. On failed, error and errorCode explain why; for INVALID_CODE, preview the scenes, fix the failing one with update_scene and export again.

MCP / 11

Presenting results to users

  • Report each scene as it lands, in one short line.
  • Never paste raw JSON or scene code into the chat unless asked.
  • Copy links verbatim from tool results.
  • Never auto-export. Finish with the editor link; export when asked.

While building

Plan: 5 scenes. Hook, the old way, the new flow, time saved, call to action.

Your video is started in Ozor: https://www.ozor.ai/editor?projectId=…

✓ Scene 1/5 — Hook (2.4 s, narrated)

✓ Scene 2/5 — The old way (6.1 s, narrated)

…

When every scene is in

Done: 5 scenes, 31.5 seconds, narrated by Nova in your brand colors.

Watch and tweak it in Ozor: https://www.ozor.ai/editor?projectId=…

Tell me what to change, or ask for an MP4 or a share link when you're happy with it.

After an export

Your 1080p export is ready.

  • Watch / share: https://www.ozor.ai/share/wuq4y9t
  • MP4 file: https://storage.googleapis.com/.../1080p.mp4
  • Embed: https://www.ozor.ai/embed/wuq4y9t

MCP / 12

Error handling

Connection errors (HTTP)

StatusMeaningWhat to do
401No credential, or an expired, revoked or unknown one. The WWW-Authenticate header carries resource_metadata, which OAuth clients use to start sign-in.Reconnect the assistant, or check the API key.
503The MCP server is starting.Retry in a few seconds.

Tool errors

Anything that goes wrong inside a tool comes back as a tool result with isError: true and a plain-language message the assistant can act on:

MessageMeaningWhat to do
Not saved: fix this and call …A scene failed its checks. Nothing was saved or charged.Fix the named scene and call again.
Not enough Ozor credits / no Ozor credits leftThe balance cannot cover the narration or the video.Tell the person; the message includes where to top up. Don't retry.
Video '…' not found / belongs to someone elseWrong id, or another account's video.Check the id with list_videos. Don't guess ids.
Scene '…' is not in video '…'Wrong scene id.get_video lists the scenes.
Export refused / The render failedThe export could not start or finish.Read error / errorCode; preview and fix the scene for INVALID_CODE.
Ozor hit an internal error running …Unexpected server error.Retry once; if it repeats, surface the error.

get_export never blocks past ~45 seconds, to stay inside client tool timeouts (about 60 seconds in Codex). A long render simply needs another call.

Integration

n8n integration

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.

Community-node setting

Self-hosted instances must have community nodes enabled — set N8N_COMMUNITY_PACKAGES_ENABLED=truein your env (it's on by default in most installs).

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.
If the test fails, double-check that you copied the full key (40 characters total) and that it hasn't been revoked.

n8n / 04

Quickstart workflow

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

workflow
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 }}"

Test as you build

After each Ozor step, run the workflow in test mode and inspect the node's output panel — every URL field documented in the URL fields section shows up there.

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.

OPResource: Video
OperationWhat it doesRequired fields
GenerateCreate a new video from a prompt.prompt
GetFetch one video, including export URLs.videoId
ListList API-created videos, newest first.—
UpdateEdit title / description.videoId, fields to update
DeleteRemove a video and its assets.videoId
Send MessageSend a natural-language edit instruction to the agent.videoId, message
ExportTrigger an MP4 render.videoId
OPResource: Document Plan
OperationWhat it doesRequired fields
Analyze DocumentConvert a file or URL into a draft plan.One of file / url
Get PlanFetch a plan with fresh image URLs.planId
Update PlanReplace scenes or change voice settings.planId, scenes
Generate From PlanRender the plan into a video project (consumes SSE internally).planId
List VoicesReturns the available TTS voices.—
OPResource: Course

Build full multi-lesson courses on top of the Ozor video pipeline — every lesson is its own narrated video, wrapped in a hosted student portal.

OperationWhat it doesRequired fields
Generate CourseCreate a multi-lesson course from a document, prompt, transcript, or URL. Auto-generates lesson breakdown, narration, visuals, and quizzes.One of file / url / prompt
Get CourseReturns metadata, lesson breakdown, completion analytics, and public URL.courseId
List CoursesReturns the workspace's courses (filter by status, date, tag).—
Update CourseEdit metadata, branding, visibility.courseId
Delete CourseRemove a course and its associated assets.courseId
Regenerate LessonRebuild a single lesson inside an existing course.courseId, lessonId
OPResource: Job
OperationWhat it doesRequired fields
Get StatusPoll a generation or edit job. Used internally when &ldquo;Wait for completion&rdquo; is on.videoId, jobId
CancelStop an in-progress generation. (Best-effort — once the renderer starts an MP4, cancellation is not guaranteed.)videoId, jobId
OPResource: Distribution
OperationWhat it does
Get Share LinkReturns the public or token-gated viewer URL for a finished export.
Get Embed CodeReturns an iframe snippet for external embedding or LMS platforms.
Get Download AssetsReturns signed URLs for MP4, captions, transcript, and thumbnail.
OPResource: Workspace
OperationWhat it does
Get WorkspaceReturns plan, credit balance, and usage stats.
List Brand KitsReturns available brand kits — pass a brand kit id when generating videos to apply your colors, fonts, and logo.

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.

FieldTypeRequiredNotes
PromptstringYes1–2000 chars. The creative brief.
Aspect16:9 | 9:16NoDefault 16:9.
Brand KitselectNoPopulated from List Brand Kits. Applies your colors, fonts, logo.
Wait for completionbooleanNoWhen on, the node blocks until the job finishes — no separate polling step needed.
Auto-exportbooleanNoWhen on, an MP4 render is triggered automatically once generation finishes.
Export Quality720p | 1080p | 4kNoUsed when Auto-export is on. Default 720p.
Export Is PublicbooleanNoWhen on, the export gets a permanent watchUrl + shareCode.
ImagesarrayNoReference images (URL or binary from previous node).
VideosarrayNoReference video clips.

Binary data

For Images and Videos, you can either point at a URL or feed binary data from a previous node (e.g. HTTP Request downloading a file). The Ozor node uploads it on your behalf.

n8n / 07

Common workflow patterns

1. Document → training video

workflow
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

workflow
Zendesk — Trigger (ticket marked &ldquo;needs-tutorial&rdquo;)
   ▼
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

workflow
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

workflow
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

workflow
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.

ToggleBehavior
Wait for completion ONNode blocks for up to 10 minutes. On success, the output item contains the full result (URLs, response text, etc.). On failure or timeout, the node throws — you can catch it with an Error Trigger workflow.
Wait for completion OFFNode returns immediately with the videoId + jobId. Use a separate Job / Get Status node in a loop (or n8n's Wait + IF combo) to poll manually.

Long renders

For 4k exports or 50-scene document plans, set the operation's Timeout field above the 10-minute default — otherwise the node will throw before the render finishes (the work continues server-side regardless; you can still find the video by ID).

n8n / 09

Tips & troubleshooting

Expressions you'll use a lot

ExpressionWhat it returns
={{ $json.videoId }}The ID of the video just generated by the previous node.
={{ $json.watchUrl }}Public watch page after an export finishes.
={{ $json.editorUrl }}Always present, even before exporting.
={{ $('Ozor Generate').item.json.videoId }}Reference an earlier Ozor node by name.
={{ $binary.data }}Pass binary file data from a Google Drive / HTTP Download node.

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.

Integration

REST API

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.

Limit

A maximum of 5 active keys per account. Revoke unused keys before creating new ones.

Make your first call

bash
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:

http
X-API-Key: sk_live_<32-hex-chars>
StatusMeaning
401 UnauthorizedHeader missing, key not recognized, or key revoked.
403 ForbiddenKey is valid but does not own the resource you are accessing.

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.

POST/api/api-keys

Create a new API key.

Request

json
{ "name": "Production" }

Parameters

FieldTypeRequiredNotes
namestringYes1–64 chars. Shown in the dashboard to identify the key.

Response (200)

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

rawKey is returned only in this response. All later list/read operations return only prefix.

GET/api/api-keys

List all keys (active and revoked) for the current account.

Response (200)

json
[
  {
    "keyId": "abc123xyz",
    "name": "Production",
    "prefix": "sk_live_a1b2",
    "status": "active",
    "createdAt": 1705312200000,
    "lastUsedAt": 1705400100000
  }
]
DELETE/api/api-keys/{keyId}

Revoke an API key. Takes effect immediately — the next request using this key fails with 401.

Response (200)

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

API / 04

Credits

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

EndpointCostWhen deducted
POST /api/v1/videos/generate1 creditOn successful job completion
POST /api/v1/videos/{videoId}/message1 creditOn successful job completion
POST /api/v1/videos/{videoId}/export0 credits—
POST /api/v1/documents/analyze0 credits—
POST /api/v1/documents/plans/{planId}/generatemax(1, floor(voiceover_scenes / 2))On successful completion

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 6 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:

bash
# 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.

POST/api/v1/videos/generate

Create a new video from a natural-language prompt. Asynchronous — the agent runs in the background. The response returns immediately with a jobId to poll and a videoId referencing the newly created project.

Deducts 1 credit on successful completion. If you pass export: true, an MP4 render is automatically triggered once the agent finishes.

Request

json
{
  "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 }
  ]
}

Parameters

FieldTypeRequiredDefaultNotes
promptstringYes—1–2000 chars.
aspect"16:9" | "9:16"No"16:9"Landscape or portrait.
exportboolNofalseAuto-trigger an MP4 render after the agent finishes.
exportQuality"720p" | "1080p" | "4k"No"720p"Applied only when export=true.
exportIsPublicboolNofalsetrue → the auto-export gets a permanent shareUrl + shareCode.
imagesChatImage[]No—See Media Attachments.
videosChatVideo[]No—See Media Attachments.

Response (200)

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

Next steps

  • Poll GET /api/v1/videos/{videoId}/jobs/{jobId} until status is "completed" to get the agent's reply.
  • If export=true, also poll GET /api/v1/videos/{videoId} until exportStatus is "complete" to get the rendered MP4.
GET/api/v1/videos

List all videos created via the public API by the current account, newest first.

Query parameters

NameTypeDefaultRange
limitint201–100

Response (200)

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

Videos created inside the web app do not appear here — this list is scoped to API-originated videos.

GET/api/v1/videos/{videoId}

Full status for a video, including its latest export. This is the endpoint you poll while an export renders.

Response (200)

json
{
  "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
}
exportStatusMeaning
queuedRender accepted, not yet picked up by the renderer.
processingRenderer actively working.
completedownloadUrl is set; if public, shareUrl + shareCode are too.
failedRender failed — exportError contains the reason.

URL lifetimes

  • downloadUrl — signed URL, valid ~24 hours. Re-fetch this endpoint for a fresh one.
  • shareUrl — permanent and public, never expires (only set when the export was public).
POST/api/v1/videos/{videoId}/export

Manually trigger an MP4 render for an existing video. Use this when you generated without export: true, or when you want a second render at a different quality or visibility.

Request

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

Parameters

FieldTypeRequiredDefaultNotes
quality"720p" | "1080p" | "4k"No"1080p"—
isPublicboolNofalsetrue → returns a permanent shareUrl + shareCode.

Response (200)

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

Caching

If an identical export (same scene content + quality + visibility) already exists, the cached result is returned immediately with exportStatus: "complete" and its URLs already populated.
POST/api/v1/videos/{videoId}/message

Send a natural-language edit instruction to the agent. Asynchronous — a jobId is returned immediately. Deducts 1 credit on successful completion.

Request

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

Parameters

FieldTypeRequiredNotes
messagestringYes1–2000 chars.
imagesChatImage[]NoSee Media Attachments.
videosChatVideo[]NoSee Media Attachments.

Response (200)

json
{ "videoId": "abc123", "jobId": "job_s0m3R4nd0mId", "status": "queued" }
GET/api/v1/videos/{videoId}/jobs/{jobId}

Poll the status of an agent job (from generate or message).

Response — running

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

Response — completed

json
{
  "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"
}

Response — failed

json
{
  "videoId": "abc123",
  "jobId": "job_s0m3R4nd0mId",
  "status": "failed",
  "error": "Agent encountered an error: ...",
  "createdAt": "2026-04-20T10:30:00Z"
}
GET/api/v1/videos/{videoId}/conversations/{conversationId}/tool-trace

Diagnostic endpoint. Returns a chronological trace of the tools the agent invoked in a conversation — useful for debugging and observability. Read-only.

Response (200)

json
{
  "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.

The flow

  1. Analyze — upload a file or URL. You receive a planId and a scene-by-scene plan (narration script + visual descriptions) to review.
  2. Update (optional) — edit the scenes' voiceover text, prompts, or voice settings.
  3. Generate — render the plan. Progress streams over Server-Sent Events; the final event carries a projectId you can then use with the /api/v1/videos/* endpoints (e.g. to export).
GET/api/v1/documents/voices

List the available text-to-speech voices.

Response (200)

json
{
  "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" }
  ]
}
POST/api/v1/documents/analyze

Extract scenes and narration from a document or web URL. Deducts 1 credit immediately.

Content type: multipart/form-data (not JSON).

Form fields

FieldTypeRequiredNotes
filefileOne of file / urlPDF, PPTX, or DOCX. Max 50 MB.
urlstringOne of file / urlhttp(s):// URL — its readable text is analyzed.
target_duration_secintNoTarget output duration. Default 30. Drives scene count.
promptstringNoOptional guidance (tone, focus, audience, language).
aspect_ratio"16:9" | "9:16"NoDefault "16:9".

Supported file MIME types

  • application/pdf
  • application/vnd.openxmlformats-officedocument.presentationml.presentation (.pptx)
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx)

Response (200)

json
{
  "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
  }
}

creditsCost is the future cost of calling /generate on this plan — it equals floor(count_of_scenes_with_voiceover / 2).

GET/api/v1/documents/plans/{planId}

Retrieve a plan. Image URLs are refreshed on every read (they are short-lived signed URLs), so always fetch immediately before displaying or editing.

Response (200): same shape as analyze.

PATCH/api/v1/documents/plans/{planId}

Edit the plan before generating — rewrite voiceover, reorder scenes, drop scenes, or lock in a voice.

Valid only while the plan's status is draft or failed.

Request

json
{
  "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
  }
}

Parameters

FieldTypeNotes
scenesscene[]Full replacement — send the complete list.
voiceSettings.voiceIdstringA voice id from /documents/voices. Omit to auto-select by language.
voiceSettings.speakingStylestringFree-text style hint ("formal", "energetic", "calm").
voiceSettings.speakingRatefloat0.5–2.0. Default 1.0.
POST/api/v1/documents/plans/{planId}/generate

Render the plan into a real video project. Valid only while plan status is draft or failed.

Credit cost: max(1, floor(voiceover_scenes / 2)) — e.g. a 6-scene plan costs 3 credits. The balance is checked before streaming begins; if you are short you receive 402 up front and no work is done.

Response: text/event-stream (SSE). Each event is a line:

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

Typical sequence

sse
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"}

On error

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

Consume with any SSE-capable client. Once you receive the done event, use the returned projectId as videoId with the rest of the API — e.g. POST /api/v1/videos/{projectId}/export to render the MP4.

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)

FieldTypeNotes
urlstringPublicly accessible HTTPS URL.
base64stringRaw base64 (no data: prefix needed).
mimeTypestringimage/jpeg, image/png, or image/webp. Recommended with base64.

Video object (ChatVideo)

FieldTypeNotes
urlstringPublicly accessible HTTPS URL.
base64stringRaw base64.
mimeTypestringvideo/mp4 or video/webm. Recommended with base64.
durationSecfloatClip duration — helps the agent reason about pacing.
thumbnailUrlstringOptional thumbnail URL.
When base64 is provided it takes precedence — the data is uploaded to Ozor storage and url is ignored.

API / 09

Polling patterns

Generate + auto-export

flow
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

flow
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

flow
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

flow
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.

HTTPWhen it happens
400 Bad RequestValidation failed — missing field, value out of range, unsupported file type, file too large, invalid aspect_ratio, plan not in draft/failed state, etc.
401 UnauthorizedX-API-Key missing, unrecognized, or revoked. For key-management endpoints: Firebase token missing/expired.
402 Payment RequiredCredit balance insufficient for this operation. detail includes the cost when relevant.
403 ForbiddenThe API key is valid but does not own the target video/plan/job.
404 Not FoundThe videoId, jobId, planId, or exportId does not exist.
500 Internal Server ErrorUpstream failure — document fetch, renderer, or analysis error. Safe to retry after a short delay.

Example

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

API / 11

Reference tables

Aspect ratios

ValueUse case
16:9Desktop, YouTube, landing pages (1920×1080 at 1080p).
9:16Mobile, TikTok, Reels, Shorts (1080×1920 at 1080p).

Export qualities

ValueResolution (16:9 / 9:16)
720p1280×720 / 720×1280
1080p1920×1080 / 1080×1920
4k3840×2160 / 2160×3840

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

status (project)Meaning
draftProject exists and is editable.
renderingA render is in progress.
completedA render has completed at least once.

Export statuses

exportStatusMeaning
queuedAccepted, not yet picked up by the renderer.
processingActively rendering.
completeDone. downloadUrl (and shareUrl if public) are set.
failedRender failed. exportError contains the reason.

Agent job statuses

status (job)Meaning
queuedJob accepted, agent not yet started.
pendingReturned synchronously by /generate; equivalent to queued.
processingAgent running.
completedDone. response is set.
failedErrored. error is set. No credit deducted.

TTS voices

idgendercharacter
ariafemaleClear, precise
novafemaleWarm, natural
felixmalePlayful, upbeat
marcusmaleNeutral, professional
thormaleDeep, authoritative
lunafemaleSoft, calm
owenmaleSteady, trustworthy
skyneutralLight, friendly

Document formats

FormatMIME
PDFapplication/pdf
PPTXapplication/vnd.openxmlformats-officedocument.presentationml.presentation
DOCXapplication/vnd.openxmlformats-officedocument.wordprocessingml.document

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

Resources

Glossary

TermMeaning
Project / videoSame thing seen from two angles: a video is a project the user is building in the Ozor editor. The videoId (also projectId for document-mode outputs) is the canonical identifier.
PlanA draft of a document-to-video script — scenes, voiceover, images, voice settings. Lives in "draft" status until generate_from_plan consumes it.
JobAn async agent run (generation or message). Has a jobId scoped to the project. Poll with GET /jobs/{jobId} or the n8n Job resource. (MCP builds have no jobs: each tool call finishes its work.)
ExportAn MP4 render of a project's current state. Has an exportId, a quality, and a visibility (public / private). The public ones get a shareCode and the /share/<code> + /embed/<code> pages.
Share codeThe short URL-safe token (e.g. wuq4y9t) that maps to a public export. Used in watchUrl and embedUrl. Treat as opaque.
Editor URLhttps://www.ozor.ai/editor?projectId=<id>. Always safe to present, even before any export. Lets the user preview, scrub, and tweak.
Watch URLhttps://www.ozor.ai/share/<shareCode>. Public watch page. The link to give people to watch the finished video.
Embed URLhttps://www.ozor.ai/embed/<shareCode>. The <iframe src>. Not for humans to open directly.
MP4 URL (raw)https://storage.googleapis.com/.../1080p.mp4. The actual file. Use for downloads or <video> tags, not as the “watch” link.
CreditThe unit Ozor bills generation in. 1 credit ≈ 1 generation step. See the credits table.
Brand kitA saved bundle of colors, fonts, logo, and tone-of-voice that Ozor applies to new videos automatically.

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 get_export tool and the 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). Assistants connected with OAuth don't use keys: revoke them under Connected AI apps instead.

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.

Ready to build with Ozor?

Connect Claude, ChatGPT or your coding agent in a minute, or create an API key and drive Ozor from n8n or plain HTTP. New accounts start with 6 free credits.