Referencia de la API · Platform
Films
Film projects — a script, a storyboard and an edit, on the video engines.
A film is a PROJECT, never media: a title, a shared look (engine, format, film type, era, tempo, camera…) and ordered scenes (prompt, camera move, duration, cast). Up to 50 per account — the studio's Cinema saves them here. Renders always land in /v1/creations; a film only points at them.
Cinema writes data as its v2 project ("v": 2): script — Notion-style blocks for notes (never sent to an engine) where every scene block IS a storyboard scene, in order; scenes — each with its heading (slugline), prompt (the action), dialogue ([{ speaker, manner, line }] — speaker is char:<id> or a free name), shot, seconds, cast and the takes it rendered (options: library ids, pick = the one in the cut); edit — the timeline (clips with in/out and transitions, free audio clips, titles). The API stores data as sent (400 KB max); deleting a film never touches the renders it produced.
POST /v1/films/{id}/render shoots the whole storyboard in one call: every scene with a prompt is queued as an async video job (charged per scene, like POST /v1/videos/generations), the response maps each scene to its job id (poll them) or to the error that kept it from queueing. On a v2 project each scene's slugline and its dialogue lines ride its prompt (@Name (manner) says: "…"), and every speaking cast member joins its references (their voice too, on engines that take one). Scenes fail independently — a drained wallet stops the remaining queue cleanly, and every charged failure refunds itself.
Media. GET /v1/films/{id} returns media: every take, clip and sound the project points at, as fresh signed URLs (the Store is private); POST /v1/films/media re-signs a list of keys (creation:<id>, upload:<id>) during a long session. The cut. The studio renders the edit to one MP4 in the browser and saves it with POST /v1/films/{id}/export (raw video/mp4 body, ≤ 95 MB, free — it counts against your storage); the saved cut is a library clip, and publishing it as the film's single segment puts the edited film on the community shelf.
The draft's look is applied to every scene: model, aspect, resolution, audio, seed and the director's rack (filmType, era, tempo, cameraType, lens, aperture, palette, lighting) — each scene adds its own prompt, shot, seconds and cast. Every engine takes the whole rack; a recurring cast keeps the same faces from scene to scene only on engines that read reference pictures (references in /v1/engines — Seedance, Kling, Veo 3.1, Hailuo 3, Wan). Start/end frames are per-clip controls of POST /v1/videos/generations, not part of a film. The studio's continuous shots (each scene opening on the last frame of the scene before) is the same API used scene by scene: grab the previous clip's last frame, upload it (POST /v1/uploads) and send it as references[0] of the next POST /v1/videos/generations.
A film can go public. POST /v1/films/{id}/cover (multipart file, image ≤ 5MB, free) sets its cover; POST /v1/films/{id}/publish puts the whole film on https://eroq.ai/community as one entry that plays the segments (your own hosted scene renders, in order) back to back — every URL must belong to a video in your library. DELETE /v1/films/{id}/publish makes it private again; likes and comments survive a re-publish. Deleting the draft deletes its community entry too (scene renders stay in the library).
Endpoints
Selecciona un verbo para cargar su solicitud, su playground y su respuesta.
List your film drafts.
Create a draft.
Up to 80 characters.
The recipe, stored verbatim: { look: {…}, scenes: [{ prompt, shot, seconds, cast }] }.
One film, full recipe.
Update title and/or data.
New title, up to 80 characters.
The whole recipe, replaced verbatim. Omit to keep the stored one.
Delete the draft — renders stay in the library.
Fresh signed URLs for media keys (creation:<id>, upload:<id>, up to 300) — unknown or foreign keys are left out.
Media keys to sign.
Save the rendered cut (raw video/mp4 body, ?seconds=, ≤ 95 MB) to the library — free, counts against storage; replaces the film's previous unpublished cut.
Shoot the whole storyboard: one async video job per scene, charged per scene, jobs to poll in the response.
Persist every clip to the eroq Store (charged at the Store's rate). Default false.
Library folder every scene's clip lands in — one of yours (GET /v1/folders). Omitted = the Library root; an unknown id answers 404 folder_not_found before anything is billed.
Set the film's cover (multipart file, image ≤ 5MB). Free; shown on the community shelf and player. A new cover on an approved film sends it back to review (review in the response).
Cover image, up to 5MB.
Submit the film to the community: segments (your own hosted scene renders) play in order. It goes public once our team approves it — review starts at pending (readable on GET /v1/films/{id}); publishing again keeps the verdict unless the title, scenes or cover change.
Ordered clip URLs (1–24). Each must be a hosted render from your own library — no foreign media.
Public title, up to 120 characters. Defaults to the draft's title.
Total runtime shown as the duration badge.
Take the film off the community shelf — engagement is kept for a re-publish.
curl https://eroq.ai/v1/films \
-H "Authorization: Bearer $EROQ_API_KEY"Respuesta
{
"films": [{
"id": "7f2a…", "title": "Rooftop night",
"scenes": 3, "updatedAt": "2026-09-11T14:02:11Z"
}]
}