Developers

The video generation API

Turn a prompt into a finished video from your own code. Authenticate with an API key, POST a prompt, poll for status, and get a downloadable MP4.

1. Get an API key

Create a key in Settings → API keys. Keys look like ss_live_… and are shown once.

2. POST a prompt

Send a prompt to /generate. You get back a project_id and a queued status.

3. Poll for the result

Poll /generate/{id} until ready:true, then download the video_url.

Authentication

Every request is authenticated with an API key in the X-API-Key header. Create one in Settings → API keys — it is shown only once, so store it securely. The key is scoped to one workspace and its credits.

http

X-API-Key: ss_live_your_key_here

Generate a video

POST /api/v1/generate creates and starts a video. It responds immediately with 202 Accepted and a project id.

curl

curl -X POST https://api.scenesynth.ai/api/v1/generate \
  -H "X-API-Key: ss_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The history of the Roman Empire, cinematic documentary",
    "source_type": "topic",
    "video_type": "long_form",
    "aspect_ratio": "16:9",
    "target_duration_seconds": 300,
    "language": "en"
  }'

Response:

json

{
  "project_id": "5edf65c2-38bc-4c55-ab76-c018d9f82396",
  "workspace_id": "2bc94622-41a9-4408-80ce-df8d4054ddd0",
  "status": "queued"
}

Request parameters

Field	Type	Description
prompt	string (required)	Topic, idea or full script. 1–5000 characters.
source_type	"topic" \| "script"	"topic" runs AutoPilot (AI writes the script); "script" uses your text verbatim. Default "topic".
video_type	"long_form" \| "shorts"	Long-form (16:9 default) or vertical shorts. Default long_form.
aspect_ratio	"16:9" \| "9:16" \| "1:1"	Output framing. Default 16:9.
target_duration_seconds	integer	5–7200 seconds. Default 180.
language	"en", "tr", "de", …	One of 15 supported languages. Default en.

Check status & get the video

Poll GET /api/v1/generate/{project_id} until ready is true. The video_url is your finished MP4.

curl

curl https://api.scenesynth.ai/api/v1/generate/PROJECT_ID \
  -H "X-API-Key: ss_live_your_key_here"

Response:

json

{
  "project_id": "5edf65c2-...",
  "status": "ready",
  "progress": 100,
  "ready": true,
  "video_url": "/media/workspaces/.../renders/bd64454d-....mp4"
}

Full example (JavaScript)

Start a short and wait for it to finish:

javascript

const API = "https://api.scenesynth.ai/api/v1";
const headers = { "X-API-Key": process.env.SCENESYNTH_KEY, "Content-Type": "application/json" };

// 1. Start a video
const start = await fetch(API + "/generate", {
  method: "POST",
  headers,
  body: JSON.stringify({ prompt: "5 mind-blowing space facts", source_type: "topic", video_type: "shorts" }),
}).then((r) => r.json());

// 2. Poll until ready
let job;
do {
  await new Promise((r) => setTimeout(r, 5000));
  job = await fetch(API + "/generate/" + start.project_id, { headers }).then((r) => r.json());
} while (!job.ready && job.status !== "failed");

console.log("Done:", job.video_url);

Rate limits & errors

60 generations / hour per workspace. Exceeding it returns 429 with a Retry-After header.
401 — invalid or missing API key.
422 — the prompt failed validation or content moderation.

Replace https://api.scenesynth.ai with your own API host if self-hosting. Generation consumes workspace credits like the dashboard.

Ship video from your code

Create a key and make your first API call in minutes.