PeakMV
Back

PeakMV API Docs

v1 API is Deprecated

The v1 API (/api/v1/*) has been deprecated and retired. All new integrations and existing clients must use the /api/v2/* endpoints (e.g. POST /api/v2/generate) or /api/v3/*.

New Release: V3 Cinematic API

Generate Up to 5-Minute Cinematic AI Videos

The V3 Cinematic Video API enables long-form multi-scene video generation (up to 300s) with AI director camera controls (dolly_in, orbit, crane_up), 2.39:1 anamorphic framing, character persistence, and real-time SSE progress streaming.

Machine-Readable Resources

For AI agents, LLMs, and automated tooling. These files are always available at the root of the site.

OpenAPI 3.1 Spec
/openapi.json

Full machine-parseable spec with schemas, examples, and error definitions for the full API surface.

Open Spec
AI Agent Index
/llms.txt

Discovery file for AI agents. Like robots.txt but for LLMs β€” lists capabilities and links.

Open Index
Full Reference
/llms-full.txt

Complete plain-text API reference. One file an agent can ingest to fully integrate.

Open
Step 1

Calling the API

Pick your language tab to view integration samples. Every example returns immediately with a job_id β€” use it to stream real-time SSE progress or poll for completion.v3: 5-minute continuous cinematic video Β· 2.39:1 / 4:3 Β· ARRI & Panavision camera physics Β· SSE streaming

Get your API Key

Create an API key from your dashboard to get started.

Keys stay server-side only.

Create API Key β†’

Setup your API Key

Set your API key as an environment variable in your runtime.

Node.js
export PEAKMV_API_KEY="peak_..."

Submit a request

Direct a long-form cinematic video (up to 300s) with camera physics and aspect ratio control. Monitor via real-time SSE stream or polling.

Node.js Client (V3)
// Run on your server; keep the API key private.
const headers = {
Authorization: 'Bearer ' + process.env.PEAKMV_API_KEY,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
};
const res = await fetch('https://peakmv.com/api/v3/generate', {
method: 'POST', headers,
body: JSON.stringify({
prompt: 'Maya discovers a missing letter, follows its clues, and reunites two sisters.',
duration_seconds: 60,
aspect_ratio: '16:9', video_quality: '1080p',
characters: [{ name: 'Maya', face_image_url: 'https://example.com/maya.jpg', description: 'Red coat, short dark hair' }]
// Add audio: { url: 'https://example.com/song.mp3', start_sec: 0 }
// to replace generated scene sound with your soundtrack.
})
});
if (!res.ok) throw new Error(await res.text());
const job = await res.json();
console.log('Quoted credits:', job.cost);
while (true) {
const response = await fetch(job.status_url, { headers });
if (!response.ok) throw new Error(await response.text());
const status = await response.json();
if (status.status === 'failed') throw new Error(status.error);
if (status.status === 'ready') { console.log(status.video_url); break; }
await new Promise(resolve => setTimeout(resolve, 3000));
}
Processing Time: Video generation takes 2-20 minutes depending on length. The API returns immediately β€” poll the status URL, listen to SSE stream, or inspect the dashboard.
Step 2

Authentication

API Key

Include your API key in the Authorization header as a Bearer token.

Authorization: Bearer peak_...
Keep your API key secure. Never expose it in client-side code or commit it to version control.
Step 3

Schema

Input

Parameter
Type
Description
prompt
Required
string
Cinematic scene description, story atmosphere, emotional tone, or screenplay beat.
duration_seconds
Optional
integer
Total film duration in seconds (15 to 300, up to 5 continuous minutes). Default: 60.
aspect_ratio
Optional
string
Framing format: 2.39:1 (Anamorphic Cinema), 16:9 (Widescreen), 4:3 (Academy Classic), 9:16 (Vertical), 1:1 (Square). Default: 2.39:1.
camera_rig
Optional
object
Cinephile hardware directives:
  • camera_body: arri_alexa_65, panavision_millennium_xl2, red_v_raptor, imax_70mm, sony_venice_2, bolex_16mm
  • lens_system: panavision_c_series, cooke_s4, arri_master_prime
  • camera_motion: dolly_in, orbit, crane_up, tracking_shot, static
  • shutter_angle: 180deg_standard, 90deg_crisp
  • film_stock: kodak_vision3_500t, fujifilm_eterna, kodak_tri_x_bw
characters
Optional
array
Array of up to five characters for reference-based identity continuity: name, description, optional face_image_url.
video_quality
Optional
string
Master rendering resolution: 1080p (Full HD) or 4k (Master). Default: 1080p.
audio_url
Optional
string
Public HTTP/HTTPS URL to background score or soundtrack.

Output

Field
Description
job_id
string
Unique asynchronous rendering job identifier.
status_url
string
URL to check job status and retrieve final MP4 video link.
stream_url
string
Server-Sent Events (SSE) stream endpoint for real-time scene-by-scene progress updates.
cost
number
Credits or dollar cost for this generation.
video_url
string
Direct link to the raw MP4 file (when ready).
Get the finished video URL
// Poll with the job_id from POST /generate response
const jobId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'; // from job_id
const res = await fetch(`https://peakmv.com/api/v3/jobs/${jobId}`, {
headers: { Authorization: `Bearer ${process.env.PEAKMV_API_KEY}` }
});
const job = await res.json();
// job.video_url -> https://auth.peakmv.com/.../vid.mp4
// job.status -> 'ready' | 'processing' | 'queued'
Step 4

Status Lifecycle

Video generation is async (2-20 minutes). After submitting, poll the status_url every 5-10 seconds.

Status Flow
queued→processing→rendering→
ready βœ“failed βœ—
Terminal states: ready (video_url available) and failed (error message available). Do not continue polling after reaching a terminal state.
GET
/v3/jobs/{id}

Primary polling endpoint. Returns status, video_url (when ready), and error (when failed).

// Response when ready
{
  "id": "a1b2c3d4-...",
  "status": "ready",
  "video_url": "https://auth.peakmv.com/.../video.mp4",
  "created_at": "2026-02-21T12:00:00Z",
  "duration_seconds": 185,
  "clips_generated": 6
}
GET
/v3/projects/{id}

Same as /jobs but also includes a shareable project_page_url.

// Response when ready
{
  "id": "a1b2c3d4-...",
  "status": "ready",
  "video_url": "https://auth.peakmv.com/.../video.mp4",
  "duration_seconds": 185,
  "project_page_url": "https://peakmv.com/project/a1b2...",
  "created_at": "2026-02-21T12:00:00Z"
}
Polling Best Practice: Poll every 5-10 seconds. Typical generation time is 2-20 minutes depending on video length. Do not set client-side timeouts shorter than 25 minutes.
Step 5

Pricing & Duration Tiers

Credits are deducted upon job submission. The V3 Cinematic Video API supports continuous multi-scene generation up to 300 seconds (5 minutes). View full pricing & margins β†’

15s Teaser
$10
3 Scenes (1080p)
30s Spot
$15
5 Scenes (1080p)
60s Trailer
$26
10 Scenes (1080p)
120s Short
$48
20 Scenes (1080p)
300s (5-Min Epic)
$113
50 Scenes (1080p)

V3 image-first pricing: Nano Banana 2 keyframes and a shared continuity reference feed LTX 2.3 Fast. Native scene audio or uploaded music is included. Quotes account for every image and each clip’s six-second minimum. Native 4K uses its actual provider rate. V2 has a separate calculator.

Step 6

Rate Limits

100
requests per minute per API key
When you hit the limit, the API returns these headers with the 429 response:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1703001234
Retry-After: 42
Headers apply to both /v1/*, /v2/*, and /v3/* endpoints.
Step 7

Error Codes

Code
Description
Example Response
400
Bad Request
Invalid parameters or missing fields. Do not retry.
{"error": "prompt is required"}
401
Unauthorized
Invalid or missing API key. Do not retry.
{"error": "Invalid or inactive API Key"}
402
Payment Required
Insufficient credits. Do not retry.
{"error": "Insufficient credits",
 "required": 14, "available": 5.5}
404
Not Found
Project/job not found or not owned by this key. Do not retry.
{"error": "Project not found"}
429
Rate Limited
Wait retry_after_seconds, then retry.
{"error": "Rate limit exceeded",
 "retry_after_seconds": 42}
500
Server Error
Retry with exponential backoff (1s, 2s, 4s… max 30s).
{"error": "Server Error"}
Retry Strategy: Only retry on 429 (after waiting) and 500 (with backoff). Never retry 400/401/402 β€” fix the request instead. Never retry a successful POST /generate β€” you will be charged again.