Developers
Films from your code, Claude and ChatGPT.
One call turns an idea or a whole script into a finished film — script, a cast that never changes, every shot, voices, music, captions, 1080p or 4K. The same engine, prices and credits as the app.
Your first 15-second film in Full HD is free in Claude and ChatGPT.
In Claude
Ask in plain words. See the script, the price and every picture in the chat, then the film.
In ChatGPT
The same — with the film playing right in the conversation.
With the API
One call, autopilot or approve-first, signed webhooks, JS and Python.
Claude and ChatGPT
Connect in ten seconds
Copy this address — it is the whole setup:
https://cloudfilm.ai/mcpClaude
- Settings → Connectors → Add custom connector
- Paste the address, press Add, then Connect
- Sign in with Google or your email, pick a monthly limit, press Allow
Works on claude.ai, the desktop app and the Claude phone apps.
ChatGPT
- Apps → search “CloudFilm” → Connect
- Or Settings → Apps → Advanced → Developer mode → Create, and paste the address
- Sign in, pick a monthly limit, press Allow
The film plays right in the conversation — on the web and in the ChatGPT apps.
Then just ask: “Make a 30-second film about a paper boat that reaches the sea, tall for Reels.” You get the script and its exact price — say go — then every picture to approve or redo — then the film, with its download, 4K and share link. Say “just make it” and it goes start to finish by itself.
Each app only spends up to the monthly limit you pick when you connect it (change it in Settings → Developers). When your credits run out, the film waits and carries on by itself the moment you top up.
API
Quick start
- Get a key in Settings → Developers (keys come with your first credit purchase). Send it as
Authorization: Bearer tc_live_…. - Make a film — an
idea(CloudFilm writes the script) or yourscript(any story; long ones become parts). - Follow it with
GET /v1/films/{id}— or a signed webhook — untilstate: "ready", then download.
curl https://cloudfilm.ai/api/v1/films \
-H "Authorization: Bearer $CLOUDFILM_KEY" \
-H "Content-Type: application/json" \
-d '{
"idea": "A paper boat sails down a rain-soaked street and reaches the sea",
"length_seconds": 30,
"shape": "9:16",
"resolution": "1080p",
"mode": "autopilot"
}'API
Approve first, change anything
mode: "approve" stops twice: at script_ready (the script and its exact price) and at pictures_ready (every picture). mode: "autopilot" goes start to finish. Both are the same engine and the same price.
# 1. Your own script, approve first
curl https://cloudfilm.ai/api/v1/films -H "Authorization: Bearer $CLOUDFILM_KEY" -H "Content-Type: application/json" \
-d '{"script": "<your whole script or story>", "mode": "approve", "resolution": "4k"}'
# → state "writing" (any story is turned into a film script), then "script_ready" with the exact price
# 2. Go: the script and its price are approved
curl -X POST https://cloudfilm.ai/api/v1/films/FILM_ID/approve -H "Authorization: Bearer $CLOUDFILM_KEY" \
-H "Content-Type: application/json" -d '{"what": "script"}'
# → cast, then every picture → state "pictures_ready" (each with its picture_url and its moment)
# 3. Redo one picture with new words, approve the rest
curl -X POST https://cloudfilm.ai/api/v1/films/FILM_ID/redo -H "Authorization: Bearer $CLOUDFILM_KEY" \
-H "Content-Type: application/json" -d '{"shots": [{"shot": 3, "moment": "0:08 – 0:12\nThe boat spins in a puddle as a cyclist splashes past.\nshot size: close-up"}]}'
curl -X POST https://cloudfilm.ai/api/v1/films/FILM_ID/approve -H "Authorization: Bearer $CLOUDFILM_KEY" \
-H "Content-Type: application/json" -d '{"what": "pictures"}'
# → clips, music, 4K, the film → state "ready" with film.download_url and film.download_4k_urlAfter a film is ready: POST /v1/films/{id}/change changes a line's words, the captions, the music or makes it 4K; POST /v1/films/{id}/redo remakes shots; POST /v1/films/{id}/languages makes it in more languages. Only what changed is made and paid again. Every film is also in the app, ready to edit by hand.
Your own photo, music or clip: POST /v1/uploads gives an upload link (24 hours, works once). PUT the file to upload_url with your key, or open upload_page on any device. Then use its id: photos: { "maya": "<upload id>" }, music: { "upload_id": "…" }, intro_upload_id / outro_upload_id.
Reference
Endpoints
Base address https://cloudfilm.ai/api/v1. JSON in, JSON out. Send Idempotency-Key on POST /films to make a retry safe. Machine-readable: openapi.json.
| Endpoint | What it does |
|---|---|
| POST /films | Make a film (idea or script). Returns the film with its quote. |
| POST /films/quote | The price before anything is made — free. |
| GET /films | Your films, newest first (?limit, ?state, ?before). |
| GET /films/{id} | State, stage, progress, eta_seconds, price, cast, pictures, lines, the files. ?include=script for the script. |
| POST /films/{id}/approve | { "what": "script" } — go. { "what": "pictures", "shots"?: [1, 3] } — approve pictures. |
| POST /films/{id}/script | { "change": "…" } — rewrite the waiting script as asked. |
| POST /films/{id}/redo | { "shots": [{ "shot": 3, "moment"?: "…" }] } — remake pictures (after the film: refilm too). |
| POST /films/{id}/change | { "lines"?: [{ "line": 2, "text": "…" }], "captions"?, "music"?, "resolution"? } |
| POST /films/{id}/languages | { "languages": ["hi", "es"] } — the same film in more languages. |
| POST /films/{id}/share | A public watch page. |
| GET /films/{id}/download | Redirects to the file (24-hour link). ?res=4k for 4K. |
| POST /films/{id}/retry | Try a stopped film again from where it stopped (nothing is paid twice). |
| DELETE /films/{id} | Cancel: anything not made yet is refunded, what's made is kept. |
| GET /characters | Your saved characters — reuse them by @handle. |
| GET /voices | Voices by ?language, ?search, ?gender — use a name or id. |
| GET /languages | The 29 film languages (no key needed). |
| GET /credits | Balance, credits held for films under way, this key's limit, the prices. |
| POST /uploads · PUT /uploads/{id} | Your own photo, music or clip. |
| GET /status | Is everything working (no key needed). |
What you can ask for
| Field | Meaning |
|---|---|
| idea | What the film is about — CloudFilm writes the script (10–4,000 characters). |
| script | Your whole script or story, any form, up to 200,000 characters. Long stories become parts (each part its own film, linked by series). |
| mode | "autopilot" (default) or "approve". |
| length_seconds | For an idea: 10 to 3,600 (default 60). |
| shape | "16:9" (default) or "9:16". |
| resolution | "1080p" (default) or "4k". |
| language / languages | A film language by name or code (default English), and more to make it in: English, Hindi, Tamil, Spanish, French, German, Portuguese, Italian, Arabic, Chinese… |
| detail | "normal", "detailed" (default) or "extreme" — how deep the script goes. |
| presenter | true for a presenter on screen talking to the viewer. |
| narrator_voice / voices | A voice name or id for the narrator; { "<cast tag>": "<voice>" } for characters. |
| characters / photos | { "<cast tag>": "@handle" } to reuse saved characters; { "<cast tag>": "<upload id>" } for faces from photos. |
| captions | "off" or one of "highlight", "outline", "box", "clean", "cinematic" (default "highlight"). |
| music | false, { "words": "piano and strings, slow, hopeful" } or { "upload_id": "…" }. |
| intro_upload_id / outro_upload_id | Your own clip at the start or end. |
| picture_quality | "standard" (default) or "best". |
| max_credits | The most this one film may spend — it waits rather than pass it. |
| webhook_url | Where this film's events go (as well as your account's webhook). |
States
| state | Meaning |
|---|---|
| queued | Waiting its turn — 3 films per account are made at once, so no one waits behind someone else's hundred. |
| writing | The script is being written (or your story turned into one). |
| script_ready | Approve mode: the script and its exact price wait for your go. |
| cast | Every person, thing and place gets its one fixed look. |
| pictures / pictures_ready | Every shot's picture is made / waits for approve or redo (approve mode). |
| filming | Clips, voices, music, 4K and the export — stage says where (“Making clips · 3 of 8”). |
| languages | The other languages are being made. |
| ready | film.download_url (and download_4k_url) work for 24 hours; ask again for fresh ones. |
| needs_credits | Paused for credits — top up and it carries on by itself. |
| limit_reached | A monthly limit or max_credits would be passed — raise it and it carries on. |
| failed / cancelled | Stopped; error says why. What was made is kept; anything not made was refunded. |
Reference
Webhooks
Set an address in Settings → Developers (or webhook_url on a film). Every state change is sent as film.<state> — film.script_ready, film.pictures_ready, film.ready, film.failed, film.needs_credits and the rest — with the film in data. Answer 2xx; anything else is retried with backoff for about a day.
Every event is signed: CloudFilm-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body> with your signing secret.
import crypto from "node:crypto";
// Express: app.post("/cloudfilm", express.raw({ type: "application/json" }), handler)
function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}Reference
Errors, in plain words
Every error is { "error": { "code", "message", "docs" } } — the message is one sentence you can show a person as it is.
| code | When |
|---|---|
| UNAUTHORIZED (401) | No key, a wrong key, or a revoked one. |
| INVALID_REQUEST (422) | A field is missing or wrong — details lists each one. |
| CONTENT_NOT_ALLOWED (422) | The story goes against the usage rules. |
| OVER_MAX_CREDITS (422) | The film costs more than max_credits — the quote is in details. |
| LIMIT_REACHED (402) | This key's monthly limit would be passed. |
| INSUFFICIENT_CREDITS (402) | Not enough credits for a change or a redo — top up. |
| NOT_WAITING / BUSY / NOT_READY (409) | The film isn't at the step that action needs — its state says where it is. |
| NOT_FOUND (404) | No film (or upload) with that id on this account. |
| RATE_LIMITED (429) | More than 120 requests a minute — Retry-After says when. |
| INTERNAL (500) | Our side — nothing was charged for it. Try again. |
Money
Prices and limits
The same prices and credits as the app — no API surcharge. Credits never expire; failed renders come back automatically.
| What | Credits |
|---|---|
| A picture | 0.3 (best quality 0.8) |
| A narrator line | 0.02 |
| A minute of film, 1080p | 6 |
| A minute of film, 4K | 18 |
| A minute of music | 0.6 |
| Writing a script (a minute, detailed) | 0.4 |
- Every film is priced before it starts (
POST /films/quoteis free). Its credits are set aside while it's made, so two films never count on the same credits. - Limits you set are never passed: a key's or an app's monthly limit, and each film's
max_credits. A film waits and says which limit, rather than pass it. - Keys can be revoked in one press. Usage follows the API terms and the usage rules.
- Is everything working? cloudfilm.ai/status
Libraries
JavaScript and Python, one command
npm install https://cloudfilm.ai/sdk/cloudfilm-js-1.0.0.tgzNo other packages needed. Or take the single files: cloudfilm.mjs · cloudfilm.py · openapi.json.
Try it
Make one now
“Make it” uses your credits (the price above). In approve mode nothing past the script is made until you approve it.
The answer shows here.Questions
Is there a script to video API?
Yes. CloudFilm's API turns an idea or a whole script into one finished film — a fixed cast, every shot pictured and filmed, narration and dialogue voiced, an original score and captions — in 1080p or 4K, with one call.
Can I make films in Claude or ChatGPT?
Yes. Add https://cloudfilm.ai/mcp as a connector in Claude or ChatGPT, sign in, and ask for a film in plain words. You see the script, the price and every picture in the chat before anything is made.
How much does the API cost?
The same as the app — credits: a picture 0.3 credits, a minute of 1080p film 6, a minute of 4K 18, music 0.6 a minute. Credits never expire and failed renders are refunded.
Who can get an API key?
Anyone who has bought credits: make it in Settings → Developers. Claude and ChatGPT work without a key.