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.aiMCP server
https://api.ozor.ai/mcpAPI 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
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:
| Integration | Who it's for | Auth | Use it when |
|---|---|---|---|
| MCP server | AI assistants: Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code, custom MCP clients. | OAuth or API key | You want an assistant to build the video in conversation: it writes the scenes, Ozor checks, narrates and renders them. |
| n8n node | Operations & automation teams using n8n. | API key credential | You want to wire video generation into a Zapier-style workflow (form → video, doc → course, etc.) without writing code. |
| REST API | Your own backend, scripts, or any HTTP client. | X-API-Key header | You 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.
| Method | Header / mechanism | Used by |
|---|---|---|
| API key | X-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 token | Authorization: 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.
| Operation | Cost | When deducted |
|---|---|---|
| Generate video (text prompt) | 1 credit | On successful job completion |
| Send message / edit instruction | 1 credit | On successful job completion |
| Video your own Claude / ChatGPT writes (one-click connection) | 1 credit per video, up to 10 narrated scenes — 50% fewer | When its first scene is saved |
| Analyze document (build a plan) | 0 credits | — |
| Generate from document plan | max(1, floor(voiceover_scenes / 2)) | On successful completion |
| Export an MP4 | 0 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 Requiredup 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
voiceovertext 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
MCP / 02
How it works
┌──────────────────┐ 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 | |
|---|---|
| Endpoint | https://api.ozor.ai/mcp |
| Transport | MCP Streamable HTTP, stateless, JSON responses. No session to keep: every request stands alone. |
| Auth | OAuth 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. |
| Identity | Every call runs as the person who approved the connection (or owns the key). Tools never take a user id. |
| Answers | Compact JSON. Scene code is never echoed back unless asked for, to keep the assistant's context small. |
One source of truth for links
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.
| Client | How | Plan notes |
|---|---|---|
| Claude | Connectors → Add custom connector, name it Ozor, paste the URL, Connect. | Every plan; the free plan allows one custom connector. Web and desktop app. |
| ChatGPT | Settings → 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 Code | One command (below), then /mcp → Authenticate. | Approve on the same computer Claude Code runs on. |
| Codex | One command (below) that adds the server and starts the login. | Terminal and IDE extension. |
| Cursor | Add to Cursor in Ozor, or mcp.json (below). | Signs in on first use. |
| VS Code | Add to VS Code in Ozor, or .vscode/mcp.json (below). | Signs in on first use. |
Claude Code and Codex
# 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 ozorCursor and VS Code
{
"mcpServers": {
"ozor": { "url": "https://api.ozor.ai/mcp" }
}
}{
"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.
401.Verify the connection
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 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:
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:
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 returnedEditing
get_scene_code(video_id, scene_id)reads one scene back;get_videolists the scenes with their ids, timing and narration.update_scenechanges only that scene: code, title, duration, data and/or narration. New code goes through the same checks.add_scenewithpositioninserts a scene;delete_sceneremoves 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:
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>
);
};| Rule | Why |
|---|---|
One export const Scene, ending in };; inline styles only | The renderer mounts exactly that component, in preview and in the MP4 export. |
Everything that moves is a function of frame | Frames render in any order on any machine. No Math.random, Date.now, timers, requestAnimationFrame or CSS transitions. |
Import only from /shared-lib | React 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 / height | Exports are 1920×1080 or 1080×1920; previews are smaller. |
Copy from data, with fallbacks | The 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.
| Check | Verifies | Typical failures |
|---|---|---|
parse | The TSX compiles. | Unbalanced braces, ${} outside a template string, a second export. |
rules | Only /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(). |
render | First, 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.
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: trueaccepts 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_sceneruns the same checks without saving (free).preview_scenereturns real frames as images.
MCP / 08
Credits
| What | Cost |
|---|---|
| A video built through MCP | 1 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 editor | 1 credit per 10 narrations (no video fee) |
start_video, code edits, delete_scene, previews, checks, reads | Free |
export_video (720p, 1080p, 4K) | Free |
- The credit is charged with the first scene;
start_videoonly 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_accountshows the balance and plan.
MCP / 09
URL fields
| Field | What it is | When set |
|---|---|---|
editorUrl | The video in the Ozor editor, where the person watches and tweaks it. | From start_video on, in every build result. |
watchUrl | Public watch page. The link to share. | When a public export is complete. |
embedUrl | Player for an <iframe src>. | When a public export is complete. |
mp4Url | The MP4 file, for downloads and <video> tags. Private exports' links expire in 24 hours. | When any export is complete. |
thumbnailUrl | Poster image. | When the export has one. |
- Never construct a URL from a
videoIdor share code; copy it from the result. editorUrlis the default answer when a video is done.watchUrlis the link to share, notmp4Url.- No
watchUrl? The export was private (public: false); export again withpublic: 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
get_scene_guideThe 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.
list_recipesTested example scenes ranked for a query such as kpi dashboard, product ui, quote, logo outro or chart. read
| Field | Type | Required | Notes |
|---|---|---|---|
query | string | No | What the scene needs to show. |
family | string | No | Exact animation family, e.g. kinetic-cascade. |
limit | number | No | Default 12, max 50. |
{ "recipes": [
{ "recipe": "KPIDashboard_LiveTiles", "title": "...", "family": "kpi-dashboard",
"durationSec": 5, "description": "..." }
] }get_recipeThe full code of one recipe. Adapt it; never ship it unchanged. read
| Field | Type | Required |
|---|---|---|
recipe | string (name from list_recipes) | Yes |
{ "recipe": "...", "title": "...", "family": "...", "durationSec": 5, "code": "import { React, ... } from '/shared-lib'; ..." }search_iconsFind valid Lucide icon names. Unknown names crash the render. read
| Field | Type | Required | Notes |
|---|---|---|---|
query | string | Yes | e.g. chart, security. |
limit | number | No | Default 12, max 40. |
{ "icons": [{ "name": "ChartLine", "category": "charts" }],
"exactNameExists": false, "usage": "const { Name } = Icons; ..." }Brand, images and voices
get_brand_kitThe person's brand kit. The same tokens are injected into every scene as data.brand. read
{ "hasBrandKit": true, "name": "Acme", "tagline": "...", "tone": ["confident"],
"brand": { "colors": { "primary": "...", "accent": "...", "background": "...", "text": "..." },
"fonts": { "heading": "...", "body": "..." } },
"logoAssetRef": "asset:user:abc123" }search_logosCompany and product logos from Ozor's library. read
| Field | Type | Required | Notes |
|---|---|---|---|
query | string | Yes | Brand name, e.g. slack. |
limit | number | No | Default 8, max 20. |
{ "logos": [{ "name": "Slack", "assetRef": "asset:global:...",
"recommendedBackground": "light", "theme": "color" }] }list_my_imagesImages in the person's Ozor library. read
| Field | Type | Required | Notes |
|---|---|---|---|
limit | number | No | Default 30, max 50. |
{ "images": [{ "name": "dashboard.png", "assetRef": "asset:user:...",
"description": "...", "recommendedBackground": "dark" }] }import_imageCopy a public image (PNG, JPEG, WebP, GIF or SVG, max 15 MB) into the person's library and get an assetRef.
| Field | Type | Required | Notes |
|---|---|---|---|
url | string | Yes | Public https URL. |
name | string | No | — |
description | string | No | What the image shows; helps later reuse. |
{ "assetRef": "asset:user:...", "name": "...", "mime": "image/png", "bytes": 48213 }list_voicesNarration voices for the voice field. read
{ "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" }
] }get_accountCredit balance, plan, and what a video costs. read
{ "credits": 42, "plan": "pro", "pricing": "1 credit per video, covering up to 10 narrations; ...",
"billingUrl": "https://www.ozor.ai/settings" }Check and preview
validate_sceneRun the three scene checks without saving. Free. read
| Field | Type | Required | Notes |
|---|---|---|---|
code | string | Yes | The full TSX scene. |
video_id | string | No | Also check against this video's other scenes (and use its aspect). |
duration_sec | number | No | — |
data | object | No | The data you will pass with the scene. |
aspect | "16:9" | "9:16" | No | — |
render | boolean | No | false runs parse and rules only. Default true. |
{ "ok": false, "checks": { "parse": "passed", "rules": "failed", "render": "not run" },
"errors": [{ "rule": "bad-easing", "message": "..." }], "warnings": [], "forceCanAccept": false }preview_sceneRender 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
| Field | Type | Required | Notes |
|---|---|---|---|
code | string | No | Unsaved scene code. |
video_id, scene_id | string | No | A saved scene. |
duration_sec, data, aspect | — | No | As in validate_scene. |
frames | number[] | No | Up 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
start_videoCreate an empty video and get its editorUrl. Nothing is charged until the first scene.
| Field | Type | Required | Notes |
|---|---|---|---|
title | string | Yes | — |
aspect | "16:9" | "9:16" | No | Default "16:9". |
voice | voice id | No | Narration voice for every scene. Default picks one for the language. |
language | string | No | ISO 639-1, e.g. es. Default en. |
use_brand_kit | boolean | No | Default true. |
{ "videoId": "GhWBYCdhM4omoHRv9W7p", "title": "Approvals in one click", "aspect": "16:9",
"editorUrl": "https://www.ozor.ai/editor?projectId=GhWBYCdhM4omoHRv9W7p", "next": "..." }add_sceneAdd one scene, checked before it is saved. The first scene of a video started over MCP charges its credit.
| Field | Type | Required | Notes |
|---|---|---|---|
video_id | string | Yes | — |
code | string | Yes | The full TSX scene. |
title | string | No | Label in the editor timeline. |
position | number | No | 1-based. Default: appended. |
duration_sec | number | No | 0.5–30. With narration, at least the audio length. |
voiceover | string | No | 1–3 short sentences, max 500 characters. Omit for a silent scene. |
data | object | No | Content the code reads as data; brand tokens are added. |
voice, language | — | No | Default: the video's. |
force | boolean | No | See Scene checks. |
{ "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=..." }create_videoCreate 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.
| Field | Type | Required | Notes |
|---|---|---|---|
title | string | Yes | — |
scenes | array (1–20) | Yes | Each: code (required), title, duration_sec, voiceover, data. |
aspect, voice, language, use_brand_kit, force | — | No | As in start_video / add_scene. |
{ "videoId": "...", "title": "...", "aspect": "16:9", "totalDurationSec": 31.5,
"creditsUsed": 1, "editorUrl": "...", "scenes": [ ... ], "next": "..." }update_sceneChange 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.
| Field | Type | Required | Notes |
|---|---|---|---|
video_id, scene_id | string | Yes | — |
code, title, duration_sec, data | — | No | Only what changes. |
voiceover | string | No | New narration; "" removes it. |
voice, language, force | — | No | — |
{ "videoId": "...", "sceneId": "...", "saved": true, "durationSec": 4.1,
"checks": { ... }, "voiceover": "...", "creditsUsed": 0 }delete_sceneRemove a scene and its narration. Destructive.
| Field | Type | Required |
|---|---|---|
video_id, scene_id | string | Yes |
{ "videoId": "...", "deleted": "<scene_id>" }Read
list_videosThe person's most recent videos, from the app and from MCP. read
| Field | Type | Required | Notes |
|---|---|---|---|
limit | number | No | Default 20, max 50. |
{ "videos": [{ "videoId": "...", "title": "...", "aspect": "16:9", "scenes": 5,
"durationSec": 31.5, "createdVia": "mcp", "editorUrl": "..." }] }get_videoA 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
{ "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": "..." } }get_scene_codeOne scene's current code, narration and data, to edit it. read
{ "sceneId": "...", "title": "...", "durationSec": 3.4, "voiceover": "...", "data": { ... }, "code": "..." }Export
export_videoRender the video to an MP4. Free. Only when the person asks for an MP4 file or a share link.
| Field | Type | Required | Notes |
|---|---|---|---|
video_id | string | Yes | — |
quality | "720p" | "1080p" | "4k" | No | Default "1080p". |
public | boolean | No | Default true: a shareable watch page and embed. |
{ "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.
get_exportExport status. Waits up to wait_seconds (default 40, capped at 45) for the render, then returns; call again while it is still rendering. read
| Field | Type | Required | Notes |
|---|---|---|---|
video_id | string | Yes | — |
export_id | string | No | Default: the latest export. |
wait_seconds | number | No | Default 40. |
{ "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)
| Status | Meaning | What to do |
|---|---|---|
401 | No 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. |
503 | The 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:
| Message | Meaning | What 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 left | The 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 else | Wrong 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 failed | The 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
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-productionso 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 }}"Test as you build
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.
Resource: Video| Operation | What it does | Required fields |
|---|---|---|
| Generate | Create a new video from a prompt. | prompt |
| Get | Fetch one video, including export URLs. | videoId |
| List | List API-created videos, newest first. | — |
| Update | Edit title / description. | videoId, fields to update |
| Delete | Remove a video and its assets. | videoId |
| Send Message | Send a natural-language edit instruction to the agent. | videoId, message |
| Export | Trigger an MP4 render. | videoId |
Resource: Document Plan| Operation | What it does | Required fields |
|---|---|---|
| Analyze Document | Convert a file or URL into a draft plan. | One of file / url |
| Get Plan | Fetch a plan with fresh image URLs. | planId |
| Update Plan | Replace scenes or change voice settings. | planId, scenes |
| Generate From Plan | Render the plan into a video project (consumes SSE internally). | planId |
| List Voices | Returns the available TTS voices. | — |
Resource: CourseBuild full multi-lesson courses on top of the Ozor video pipeline — every lesson is its own narrated video, wrapped in a hosted student portal.
| Operation | What it does | Required fields |
|---|---|---|
| Generate Course | Create 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 Course | Returns metadata, lesson breakdown, completion analytics, and public URL. | courseId |
| List Courses | Returns the workspace's courses (filter by status, date, tag). | — |
| Update Course | Edit metadata, branding, visibility. | courseId |
| Delete Course | Remove a course and its associated assets. | courseId |
| Regenerate Lesson | Rebuild a single lesson inside an existing course. | courseId, lessonId |
Resource: Job| Operation | What it does | Required fields |
|---|---|---|
| Get Status | Poll a generation or edit job. Used internally when “Wait for completion” is on. | videoId, jobId |
| Cancel | Stop an in-progress generation. (Best-effort — once the renderer starts an MP4, cancellation is not guaranteed.) | videoId, jobId |
Resource: Distribution| Operation | What it does |
|---|---|
| Get Share Link | Returns the public or token-gated viewer URL for a finished export. |
| Get Embed Code | Returns an iframe snippet for external embedding or LMS platforms. |
| Get Download Assets | Returns signed URLs for MP4, captions, transcript, and thumbnail. |
Resource: Workspace| Operation | What it does |
|---|---|
| Get Workspace | Returns plan, credit balance, and usage stats. |
| List Brand Kits | Returns 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.
| Field | Type | Required | Notes |
|---|---|---|---|
Prompt | string | Yes | 1–2000 chars. The creative brief. |
Aspect | 16:9 | 9:16 | No | Default 16:9. |
Brand Kit | select | No | Populated from List Brand Kits. Applies your colors, fonts, logo. |
Wait for completion | boolean | No | When on, the node blocks until the job finishes — no separate polling step needed. |
Auto-export | boolean | No | When on, an MP4 render is triggered automatically once generation finishes. |
Export Quality | 720p | 1080p | 4k | No | Used when Auto-export is on. Default 720p. |
Export Is Public | boolean | No | When on, the export gets a permanent watchUrl + shareCode. |
Images | array | No | Reference images (URL or binary from previous node). |
Videos | array | No | Reference video clips. |
Binary data
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
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.
| Toggle | Behavior |
|---|---|
| Wait for completion ON | Node 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 OFF | Node 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
n8n / 09
Tips & troubleshooting
Expressions you'll use a lot
| Expression | What 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
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>| Status | Meaning |
|---|---|
401 Unauthorized | Header missing, key not recognized, or key revoked. |
403 Forbidden | Key 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.
/api/api-keysCreate a new API key.
Request
{ "name": "Production" }Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | 1–64 chars. Shown in the dashboard to identify the key. |
Response (200)
{
"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.
/api/api-keysList all keys (active and revoked) for the current account.
Response (200)
[
{
"keyId": "abc123xyz",
"name": "Production",
"prefix": "sk_live_a1b2",
"status": "active",
"createdAt": 1705312200000,
"lastUsedAt": 1705400100000
}
]/api/api-keys/{keyId}Revoke an API key. Takes effect immediately — the next request using this key fails with 401.
Response (200)
{ "message": "API key abc123xyz revoked" }API / 04
Credits
Every generation operation deducts from your account's credit balance.
| Endpoint | Cost | When deducted |
|---|---|---|
POST /api/v1/videos/generate | 1 credit | On successful job completion |
POST /api/v1/videos/{videoId}/message | 1 credit | On successful job completion |
POST /api/v1/videos/{videoId}/export | 0 credits | — |
POST /api/v1/documents/analyze | 0 credits | — |
POST /api/v1/documents/plans/{planId}/generate | max(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:
# 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.
/api/v1/videos/generateCreate 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
{
"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
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
prompt | string | Yes | — | 1–2000 chars. |
aspect | "16:9" | "9:16" | No | "16:9" | Landscape or portrait. |
export | bool | No | false | Auto-trigger an MP4 render after the agent finishes. |
exportQuality | "720p" | "1080p" | "4k" | No | "720p" | Applied only when export=true. |
exportIsPublic | bool | No | false | true → the auto-export gets a permanent shareUrl + shareCode. |
images | ChatImage[] | No | — | See Media Attachments. |
videos | ChatVideo[] | No | — | See Media Attachments. |
Response (200)
{ "videoId": "abc123", "jobId": "job_s0m3R4nd0mId", "status": "pending" }Next steps
- Poll
GET /api/v1/videos/{videoId}/jobs/{jobId}untilstatusis"completed"to get the agent's reply. - If
export=true, also pollGET /api/v1/videos/{videoId}untilexportStatusis"complete"to get the rendered MP4.
/api/v1/videosList all videos created via the public API by the current account, newest first.
Query parameters
| Name | Type | Default | Range |
|---|---|---|---|
limit | int | 20 | 1–100 |
Response (200)
{
"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.
/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)
{
"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
}| exportStatus | Meaning |
|---|---|
queued | Render accepted, not yet picked up by the renderer. |
processing | Renderer actively working. |
complete | downloadUrl is set; if public, shareUrl + shareCode are too. |
failed | Render 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).
/api/v1/videos/{videoId}/exportManually 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
{ "quality": "1080p", "isPublic": true }Parameters
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
quality | "720p" | "1080p" | "4k" | No | "1080p" | — |
isPublic | bool | No | false | true → returns a permanent shareUrl + shareCode. |
Response (200)
{
"videoId": "abc123",
"exportId": "exp_xyz789",
"exportStatus": "queued",
"shareCode": "a3kf92p"
}Caching
exportStatus: "complete" and its URLs already populated./api/v1/videos/{videoId}/messageSend a natural-language edit instruction to the agent. Asynchronous — a jobId is returned immediately. Deducts 1 credit on successful completion.
Request
{
"message": "Add our logo in the top-right corner of every scene",
"images": [ { "base64": "<base64-encoded-png>", "mimeType": "image/png" } ]
}Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
message | string | Yes | 1–2000 chars. |
images | ChatImage[] | No | See Media Attachments. |
videos | ChatVideo[] | No | See Media Attachments. |
Response (200)
{ "videoId": "abc123", "jobId": "job_s0m3R4nd0mId", "status": "queued" }/api/v1/videos/{videoId}/jobs/{jobId}Poll the status of an agent job (from generate or message).
Response — running
{
"videoId": "abc123",
"jobId": "job_s0m3R4nd0mId",
"status": "processing",
"createdAt": "2026-04-20T10:30:00Z"
}Response — completed
{
"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
{
"videoId": "abc123",
"jobId": "job_s0m3R4nd0mId",
"status": "failed",
"error": "Agent encountered an error: ...",
"createdAt": "2026-04-20T10:30:00Z"
}/api/v1/videos/{videoId}/conversations/{conversationId}/tool-traceDiagnostic endpoint. Returns a chronological trace of the tools the agent invoked in a conversation — useful for debugging and observability. Read-only.
Response (200)
{
"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
- Analyze — upload a file or URL. You receive a
planIdand a scene-by-scene plan (narration script + visual descriptions) to review. - Update (optional) — edit the scenes' voiceover text, prompts, or voice settings.
- Generate — render the plan. Progress streams over Server-Sent Events; the final event carries a
projectIdyou can then use with the/api/v1/videos/*endpoints (e.g. to export).
/api/v1/documents/voicesList the available text-to-speech voices.
Response (200)
{
"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" }
]
}/api/v1/documents/analyzeExtract scenes and narration from a document or web URL. Deducts 1 credit immediately.
Content type: multipart/form-data (not JSON).
Form fields
| Field | Type | Required | Notes |
|---|---|---|---|
file | file | One of file / url | PDF, PPTX, or DOCX. Max 50 MB. |
url | string | One of file / url | http(s):// URL — its readable text is analyzed. |
target_duration_sec | int | No | Target output duration. Default 30. Drives scene count. |
prompt | string | No | Optional guidance (tone, focus, audience, language). |
aspect_ratio | "16:9" | "9:16" | No | Default "16:9". |
Supported file MIME types
application/pdfapplication/vnd.openxmlformats-officedocument.presentationml.presentation(.pptx)application/vnd.openxmlformats-officedocument.wordprocessingml.document(.docx)
Response (200)
{
"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).
/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.
/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
{
"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
| Field | Type | Notes |
|---|---|---|
scenes | scene[] | Full replacement — send the complete list. |
voiceSettings.voiceId | string | A voice id from /documents/voices. Omit to auto-select by language. |
voiceSettings.speakingStyle | string | Free-text style hint ("formal", "energetic", "calm"). |
voiceSettings.speakingRate | float | 0.5–2.0. Default 1.0. |
/api/v1/documents/plans/{planId}/generateRender 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:
data: {"step": "...", "detail": "...", "pct": 0-100}Typical sequence
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
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)
| Field | Type | Notes |
|---|---|---|
url | string | Publicly accessible HTTPS URL. |
base64 | string | Raw base64 (no data: prefix needed). |
mimeType | string | image/jpeg, image/png, or image/webp. Recommended with base64. |
Video object (ChatVideo)
| Field | Type | Notes |
|---|---|---|
url | string | Publicly accessible HTTPS URL. |
base64 | string | Raw base64. |
mimeType | string | video/mp4 or video/webm. Recommended with base64. |
durationSec | float | Clip duration — helps the agent reason about pacing. |
thumbnailUrl | string | Optional thumbnail URL. |
base64 is provided it takes precedence — the data is uploaded to Ozor storage and url is ignored.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.
| HTTP | When it happens |
|---|---|
400 Bad Request | Validation failed — missing field, value out of range, unsupported file type, file too large, invalid aspect_ratio, plan not in draft/failed state, etc. |
401 Unauthorized | X-API-Key missing, unrecognized, or revoked. For key-management endpoints: Firebase token missing/expired. |
402 Payment Required | Credit balance insufficient for this operation. detail includes the cost when relevant. |
403 Forbidden | The API key is valid but does not own the target video/plan/job. |
404 Not Found | The videoId, jobId, planId, or exportId does not exist. |
500 Internal Server Error | Upstream failure — document fetch, renderer, or analysis error. Safe to retry after a short delay. |
Example
{ "detail": "You are out of credits. Please add more to continue chatting." }API / 11
Reference tables
Aspect ratios
| Value | Use case |
|---|---|
16:9 | Desktop, YouTube, landing pages (1920×1080 at 1080p). |
9:16 | Mobile, TikTok, Reels, Shorts (1080×1920 at 1080p). |
Export qualities
| Value | Resolution (16:9 / 9:16) |
|---|---|
720p | 1280×720 / 720×1280 |
1080p | 1920×1080 / 1080×1920 |
4k | 3840×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 |
|---|---|
draft | Project exists and is editable. |
rendering | A render is in progress. |
completed | A render has completed at least once. |
Export statuses
| exportStatus | Meaning |
|---|---|
queued | Accepted, not yet picked up by the renderer. |
processing | Actively rendering. |
complete | Done. downloadUrl (and shareUrl if public) are set. |
failed | Render failed. exportError contains the reason. |
Agent job statuses
| status (job) | Meaning |
|---|---|
queued | Job accepted, agent not yet started. |
pending | Returned synchronously by /generate; equivalent to queued. |
processing | Agent running. |
completed | Done. response is set. |
failed | Errored. error is set. No credit deducted. |
TTS voices
| id | gender | character |
|---|---|---|
aria | female | Clear, precise |
nova | female | Warm, natural |
felix | male | Playful, upbeat |
marcus | male | Neutral, professional |
thor | male | Deep, authoritative |
luna | female | Soft, calm |
owen | male | Steady, trustworthy |
sky | neutral | Light, friendly |
Document formats
| Format | MIME |
|---|---|
PDF | application/pdf |
PPTX | application/vnd.openxmlformats-officedocument.presentationml.presentation |
DOCX | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
Max file size: 50 MB. A http(s):// URL may be supplied instead of a file.
Resources
Glossary
| Term | Meaning |
|---|---|
| Project / video | Same 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. |
| Plan | A draft of a document-to-video script — scenes, voiceover, images, voice settings. Lives in "draft" status until generate_from_plan consumes it. |
| Job | An 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.) |
| Export | An 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 code | The short URL-safe token (e.g. wuq4y9t) that maps to a public export. Used in watchUrl and embedUrl. Treat as opaque. |
| Editor URL | https://www.ozor.ai/editor?projectId=<id>. Always safe to present, even before any export. Lets the user preview, scrub, and tweak. |
| Watch URL | https://www.ozor.ai/share/<shareCode>. Public watch page. The link to give people to watch the finished video. |
| Embed URL | https://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. |
| Credit | The unit Ozor bills generation in. 1 credit ≈ 1 generation step. See the credits table. |
| Brand kit | A 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.