เอกสารอ้างอิง API

Generate the cast and world: character portraits + 3×3 character sheets, plus scene and item images. Required assets must be ready before /storyboard. Skips assets that already have images. Runs as the app's Make cast art: a look the series already has is reused for free, and each asset that could not be drawn is refunded on its own. Answers 202 { jobId, runId, runUrl, pollUrl, estimatedCredits }. Scene looks are always made when clips need them; appearanceVariations is deprecated and ignored.

Optional storyboard review: draw one opening frame for each clip that has neither an image nor a video, the same engine as the app's Generate storyboard. Clips go in story order, four at a time as ONE 2×2 grid image (up to three grids at once), drawn at the model's largest size and split into one 1080p frame per clip; a lone last clip is its own image, and a group of two or three leaves its spare panels unused. Each panel is the clip's image prompt (stillPrompt) word for word; a missing one is written first, and a clip whose prompt cannot be written is left out before any charge. Clips a hire covers, and clips that already have an image or a video, are listed in skipped with a reason (hire_blocked, has_image, has_video). An image or video that appears while the run works is kept, never overwritten; a grid that fails (or is still unfinished after ~50 min, then cancelled) is refunded and its clips are drawn one by one only while they fit the approved credits (the quote, or X-Max-Generation-Credits when sent); the rest are left undrawn and uncharged (overApprovedBudget, reason over_approved_budget). Required character sheets, backgrounds, props and selected looks must be ready first: otherwise 409 ASSETS_REQUIRED (nothing charged) with assetsNeeded (each asset, whether it needs a picture or a look, and the clips waiting on it). Uses the saved image model; an optional imageModel overrides it for this run, and explicit auto keeps automatic selection. Stops after images. Answers 202 { runId, runUrl, clipsToGenerate, imagesToGenerate, skipped, estimatedCredits }; poll GET /api/runs/:runId. To redraw one clip afterwards, use POST /clips/:clipId/image.

Generate video for each clip. Skips clips that already have a video URL. Runs as the app's own Generate All: one clip at a time in story order, each continuing the previous clip's video (parallel: true runs a few at once without that reference), each clip charged, settled and refunded on its own within the batch price. Like Generate All, clipIds narrows it to those clips, and with includeExisting: true they are re-generated even when they have a video. Answers 202 { runId, runUrl, cancelUrl, clipIds, estimatedCredits }: poll GET /api/runs/:runId until it ends (result.results lists each clip); POST /api/v1/runs/:runId/cancel stops it. /clips-all takes the same options. With fixFirst: true it first fixes what stops clips (missing character sheets, backgrounds and looks in one cast-art run; the length a clip's lines need, free; videos made before their script changed, unless listed in untick) and then generates, at ONE quote built from each step's own quote: quoteOnly: true answers the plan (fixes, needsYou, readyClipIds, quote { credits, getReady, videos, hash }); start with acceptedQuoteHash; it answers 202 { status: "queued", plan, runId, castArtRunId } (runId is left out when only pictures are fixed: follow castArtRunId, and the videos start inside that run once the pictures land). What needs you is never fixed for you and its clips are skipped; a clip whose fix fails is not started or charged. Send your own Idempotency-Key, one per consent: the same key again (a retry of the same request) joins the batch it started; a new key is a new start with its own charges, so use a new one after a failed batch. MCP: generate_all_videos with fixFirst (a resent confirmToken joins the run it started; a fresh quote is a new consent).

Stitch all clip videos + music + captions into a final MP4. Every clip of the cut needs its video first: otherwise it answers 409 clips_missing_video with missingVideoClips (clipId, position, title, hasImage) and charges nothing. Optional timelineMode (clip or edit); omitted, it is edit when the story has saved freeform layers, Edit-only changes or exported clips, else clip. An Edit layer with no saved media file answers 400 timeline_media_unsaved, nothing charged.

(Re)generate the image for ONE clip (one storyboard frame, drawn alone at full resolution from its image prompt). Optional body: prompt (art direction for this shot) and imageModel. Runs as the clip panel's own image run: answers 202 { runId, runUrl, estimatedCredits }; poll GET /api/runs/:runId until it ends, then read result.status and result.imageUrl. The same Idempotency-Key answers with the run it already started.

(Re)generate the video for ONE clip. Optional body: videoModel, and the clip panel's pills for this run: durationSeconds (snapped up to a length the model makes) and resolution (one the model makes; GET /api/v1/models). Both are saved on the clip, as the pills save them; the aspect ratio is the story's. POST .../regenerate takes the same two. An unknown videoModel is 400; a model that cannot make the story's aspect ratio, or a duration / resolution the model does not make, is 400 invalid_video_settings with allowed in the error (aspectRatio + videoModel, durationSeconds or resolution) — an explicit pick is refused, never silently changed. A clip whose lines need more seconds than the video would have answers 409 DIALOGUE_LONGER_THAN_VIDEO (nothing charged) with clipId, speechSeconds, videoSeconds and suggestedDurationSeconds in the error: send that durationSeconds, or shorten the lines when it is null. There is no mode to pick. The selected model locks the input mode: frame models use the current clip image as start and the next clip image as end; reference models receive their supported, named image, video and voice references. Missing required clip images are rejected before charging. The final clip uses start-only where supported. Runs as the clip panel's own Generate: answers 202 { runId, runUrl, estimatedCredits, durationSeconds, resolution, aspectRatio, videoModel, requested, adjustments? } (what the run makes, and what was asked); poll GET /api/runs/:runId until it ends, then read result.status. The same Idempotency-Key answers with the run it already started; while an API job works on the clip or story it answers 409 API_JOB_RUNNING.

Rebuild ONE clip end to end — a fresh clip image, then a fresh video from it — as a single run: the app's Generate All over this clip with its still drawn first, so the video never starts against the old image, and a still that does not land leaves the video unstarted (nothing charged for it). The right call after changing a clip's description or cast. Optional body: prompt (art direction for the new image), imageModel, videoModel, and the clip panel's durationSeconds / resolution pills (saved on the clip). Answers 202 { runId, runUrl, estimatedCredits, breakdown, durationSeconds, resolution, aspectRatio, videoModel, requested } (what the clip's video makes, and what was asked); poll GET /api/runs/:runId: result.results[0] is the clip, its image the still.

Clip authoring supports description for scene and image context, and optional motionDescription for video movement and timed beats. Video generation uses both. When motion is empty, video generation automatically creates and saves timed motion first. Send null to prepare new motion on the next video run. Draw a multi-panel continuity reference sheet for one clip. The panels are derived from the clip's time beats — an authored beat track when motionDescription carries one, otherwise the beat plan its generation length implies — so the sheet mirrors that shot rather than a fixed set of generic moments. Two panels per beat, snapped to a supported grid layout. The sheet is drawn on a 2:3 canvas when it has more rows than columns (3:2 when it has more columns, square otherwise). Starts a run and answers 202 with runId and runUrl; poll GET /api/runs/:runId until status is terminal, then read result.status: completed with the grid URL in result.imageUrl (also saved on the clip), or failed with result.error (refunded). The balance is checked before the run starts: too few credits answers 402 insufficient_credits, and a start the platform refuses answers 503 workflow_start_failed with nothing charged.

Changed 2026-10-19 (breaking): this endpoint used to answer 200 { gridImageUrl, gridData, creditsCharged } with the finished grid. It now answers 202 { runId, runUrl, status: "queued", creditsQuoted, panels, imageModel } at once. Poll GET /api/runs/:runId (MCP: get_run) every 15–30 s until status is completed, failed, canceled or needs_attention; the grid is result.imageUrl. The same Idempotency-Key answers with the run it already started (deduped: true).

Draw (or redraw) ONE character, scene or item from its description, or re-derive a character's 3×3 reference sheet and portrait crop from its current portrait. Characters are sheet-first: one generation produces the sheet and the portrait together. The answer is the new URLs when the run finishes within the request. A long one (a sheet-first character with a fallback chain) answers 202 { "status": "queued", "runId", "runUrl", "creditsCharged" }: poll GET /api/runs/:runId (runUrl) until status is completed or failed; on completion result.status is the HTTP status the request would have answered and result.body the same JSON (the asset, or { error } with the charge already refunded). The charge is made before the run starts and is settled or refunded by the run either way.

The looks a hired character brings from its creator: { bookingId, owner, pictures, canChoose, looks: [{ id, kind: "main" | "style" | "look", label, styleId, styleLabel, imageUrl, characterSheetUrl, chosen, imported, clipAssetId }] }. The main sheet always comes; chosen looks are in the episode as ready looks (imported) that never apply on their own: a clip uses one when it is picked for that clip. Names only until the hire is paid (pictures: false), pictures after. POST { lookIds } sets the extra looks to bring (ids from GET; the ones left out are removed) and answers { lookIds, imported, removed, staleClipIds, looks }: clips that used a removed look go back to the usual look and are marked out of date. Free (the looks are included in the character fee); the same as Add (free) / Remove on the hire page. A character that is not hired answers 404 not_hired; an unpaid hire or one without the face 409 looks_not_available. MCP: list_hire_looks, choose_hire_looks.

Generate every missing clip video, drawing first the still of each clip that has nothing else to reference (no cast, no pictured place or item), as ONE run: the app's Generate All, each such still drawn (as the clip panel's image run) just before its own clip's video. Running /storyboard and /videos separately lets the video pass start while images are still missing. It only fills gaps, so re-running after a partial failure is safe; a still that does not land leaves its clip's video unstarted (nothing charged for it). Answers 202 { runId, runUrl, cancelUrl, imagesToGenerate, videosToGenerate, breakdown }; poll GET /api/runs/:runId.

Write a NEW storyline branching off an existing clip — an alternative continuation the story keeps alongside the original, which is untouched. Required body: branchFromClipId. Optional prompt (where the story goes) and clipCount (4–24). The new clips and their images are made within the price; video is not, so animating them is a separate, separately-priced step. Runs as the editor's own continuation (a story run): answers 202 { jobId, runId, runUrl, pollUrl }; poll the job (or GET /api/runs/:runId) until it ends. A paid-value price above X-Max-Generation-Credits answers 409 with the quote and starts nothing.

Review a finished script before it is written, free: what a follow_script write (or an episode draft) keeps of it. Body { screenplay, seriesId?, storyId? } (a storyId alone reviews that draft's stored screenplay). Answers { scenes: [{ heading, clips: [{ number, seconds, lines: [{ speaker, text }], cast }] }], linesKept, linesTotal, clipCount, totalSeconds, newCast, flags }; flags: voice_only_speakers, lines_too_long, lines_missing, too_long, not_a_script, no_lines, several_speakers (3 or more on-screen speakers in a clip: a note only, kept as written). Fixes are made in the script; the AI's wording of each shot is not previewed. MCP: preview_script.

What a paid step still needs before it can run, from the same rules that step refuses with. ?target=clip_video|storyboard|cast_art|render (default clip_video), optional clipIds (comma-separated; default: the clips the step would run), videoModel, durationSeconds, storylineId, timelineMode. Answers { target, ready, items: [{ kind, subject, reason, clipIds, fix: { action, mcpTool, args, credits } }] } in the order to fix them. An item with severity: "warn" is a warning, never a blocker: clip_location, the clip's own Setting text names another place than the location it is linked to (details.place, details.scene); fix its sceneId or stillPrompt with the clip PATCH (MCP update_clip, free) or leave it; generation is not changed; a refused start (assets_required, dialogue_longer_than_video, clip_audio_review, clips_missing_video) carries the same list as error.readiness. MCP: check_readiness.

Everything on the episode that failed or waits on you, failures first: { count, items: [{ kind, subject, reason, status, clipIds, href, fix: { action, mcpTool, args, credits } }] }. Kinds: cast_art · look · look_stuck · clip_video · narration_missing · version_step · upload_lines · clip_speech: what a run left failed or wrong, plus one clip_check line when Check clips' free rules find something in clips without a video (fix check_clips). What a step still needs before it runs (and the location warning) is the readiness check's, never both. clip_speech is the voice check of a clip video: it says words the script does not have (fix remove_extra_words, free, while its sound can still be separated, else new_take; altFix keep_speech) or misses a line (fix revoice); narration_missing: the clip's narration is not in its sound. Each fix names the existing tool; try_grok runs the same step on Grok, and a priced fix (credits: null) quotes before it charges. Read it after any run. MCP: get_story_attention. The voice check judges the sound the user hears: a clip whose voice is replaced by re-voiced reads is not flagged (lineCheck.clearedBy: "voice_replaced"); captions can follow what is said (source-audio actions keepWithCaptions, captionFromSpeech, scriptCaptions; the script is unchanged). A delivered clip video always matches its quote; the clip GET's delivery.deliveryMismatch, when present, lists what differs (a bug signal, settled to the real cost).

Credits an episode used: { charged, refunded, used, charges, settling, steps: [{ step, charged, refunded, used }] }, steps being write · art · videos · audio · render · other. Every charge holds its maximum and settles down to the real cost, so used = charged − refunded; settling counts charges whose final can still go down. The whole story: GET /api/v1/series/:seriesId/spend, which adds episodes (most used first; each has kind: episode, version — with versionOf and locale — or archived) and storyWide (its characters and places). Credits only; owner and editors. MCP: get_story_spend.

Check clips before generating: the free rules over each clip's information (too many actions for its seconds, the place the text names vs the linked place, clothes vs the character's look, speakers, crowds set up as one character, time of day, a peak-moment first picture, off-frame people, continuity, lines longer than the clip) and kind method (the best way to make the clip, or a setting that does not fit). Optional clipIds (comma-separated). Answers { clipIds, issues: [{ id, clipId, clipIds, kind, severity, message, fix: { type, … }, selected, suggestion?, info? }], count, userScript }. MCP: check_clips.

The same check with the AI review: body { clipIds?, ai: true, quoteOnly?: true, language? }. quoteOnly answers ai: { status: "quote", credits, clips, batches, storyPass } (free, about 1-3 credits a clip); without it the review runs held to X-Max-Generation-Credits (send the quoted credits) and answers ai: { status: "done", quotedCredits, chargedCredits } — the charge settles to the real cost of its calls. Two or more clips add a story-logic pass over the whole episode (kind story_logic; on a user's own script these are suggestions, selected: false). MCP: check_clips with ai: true.

Apply the fixes the user picked: { issueIds } or { fixes: [{ issueId?, fix }] }. Text, place, length, voice-only and method changes go through the editor's own edits (locks, hires and collaborators respected); a fix whose text changed since the check is skipped. A new look's picture is a priced next step (next.mcpTool generate_all_asset_images). Answers { applied, outcomes: [{ issueId, fixType, status, reason?, next? }], recheck }. MCP: apply_clip_check_fixes.

A line whose speaker is a name nobody in the cast has (readiness kind dialogue_speaker, e.g. "announcer") gets a voice-only cast member with its own voice, and its lines are credited to it — what new stories get when they are written. Optional body clipIds. Answers { members: [{ id, name, created }], creditsCharged: 0 }. MCP: cast_voice_only_speakers.

The story's finished videos, newest first, with latestSuccessful called out so a failed render is never mistaken for the current cut. A story keeps every render. Optional ?limit (max 50). Each render has width, height and duration (seconds; API renders), aspectRatio, the story's locale and its fileName (API renders are named <title>_<aspect>_<language>.mp4, e.g. glow-cola_9x16_zh-TW.mp4). API renders run in their own pool (2 at once per account, 3 across accounts) and never take the app's export slots; a render past the pool waits its turn (the job reads queued, phase waiting_for_render_slot).

Rewrite a clip's existing video — video-to-video, so subject, composition and motion carry over. Send one of: prompt (an instruction: "make it night and rainy", "push the camera in slowly"); restyleStyleId (redraw the footage in a style preset, keeping its length); or switchAsset ({ target: { kind: "character" | "scene" | "item", id }, subject: { assetId } | { description }, updateCast? }: put the story's character, place or item named by target into the footage by its picture, in place of subject — an asset of the same kind, or a description of what to replace). restyleStyleId and switchAsset cannot be combined; with either one prompt is optional. Optional resolution (480p, 720p, 1080p — the edit dialog's pill; default the clip's, then the story's, then 720p, as in the editor). The edit keeps the source clip's length (durationSeconds is accepted for old callers and does not change it). The clip must already have a video, and the result becomes a new selectable version rather than replacing the old one. A restyle includes a frame review in its price. Runs as the clip panel's own video edit: answers 202 { runId, runUrl, estimatedCredits, durationSeconds, resolution }; poll GET /api/runs/:runId until it ends, then read result.status. A switch with updateCast (default true) points the clip's cast and speakers at the target when the edit lands.

GET lists the clip's versions as its Versions list shows them, newest first, each with kind (generate, regenerate, edit, restyle, switch, version, delivery, upload, image, hire_review), imageUrl / videoUrl, durationSeconds, active and selectable. POST { "generationId" } makes the clip show that version: its media, its delivered length (the old trim is cleared) and a timeline span to match — the clip panel's own switch. Refused with 409 and nothing changed: HIRE_REVIEW_NOT_LIVE, CASTING_STALE, VERSION_HAS_NO_MEDIA, VERSION_NOT_READY or approved_clip_locked. Series editors and a video job's creator may switch, as in the app. MCP: select_clip_version; the clip image's own versions: select_clip_image_version.

Edit a clip. Send only what you want to change: title, description, motionDescription, stillPrompt (the prompt the clip image is drawn from; null clears it; at most 4000 characters), duration, generationDuration, resolution, transitionStyle, sceneId, characterIds, itemIds, dialogue, audioFx, onScreenText (title cards, taglines and lower thirds shown over the video: [{ text, role: title|tagline|label|other, start, end, position: top|center|bottom|lower_third }]; [] clears it).

Media columns (imageUrl, videoUrl, generation history) are deliberately not writable — those belong to the pipelines. Use the clip's /image and /video endpoints to change them.

It is the editor's own save: new dialogue grows the clip when the speech grew (never shrinks it) and keeps the motion's quotes in step; a changed duration is pinned and held to the story's video model (past its maximum: 400 duration_exceeds_lane with allowed: { min, max, tiers }; within range snapped up to whole seconds, with generationDuration and the timed motion beats moved with it, as the clip panel's duration pill does); the answer, and GET on a clip or the clip list, carries resolutionMade: { target, value, adjusted, reason? } (the asked resolution against what the story's model makes); a visual edit on a clip that has an image or video answers scriptEdit (that media is out of date until you regenerate). Refusals, each 409 with nothing written: CLIP_IN_HIRE (the clip is in an unfinished hire and keeps its hired character; bookingId, characterId), approved_clip_locked (an approved collaboration version), DELIVERY_EDIT_CONFLICT (a delivered take's history), CASTING_STALE (made before the casting changed), story_locked (a job or template run holds the story).

Insert a clip. title and description required; place it with afterClipId or beforeClipId (omit both to append). Optional: the PATCH fields, plus storylineId (a branch of this story). Following clips shift down automatically and looks keep starting at their clip. The new clip has no image or video yet. 409 CLIP_WORKSPACE: a clip-hire workspace holds only its hired clip.

The editor's Duplicate: a copy right after the clip with its text, still prompt, cast, items, scene, storyline, dialogue, sound cues, on-screen text and its made image/video with their versions. Later positioned clips move right (shiftedClipIds). MCP: duplicate_clip.

A talking clip's audio sync, the clip panel's own read and actions. After a video lands the clip plays its own sound and separating voice and background is the user's choice (separate-audio below), except three automatic cases, platform-paid and never charged (an upload never): a talking clip from a model that takes no voice sample (Grok 1.5, Kling Omni) gets each character's own read (separation.reason voice_restored), words the voice check found that the script does not have are taken out (extra_words_removed), and a clip with narration placed over it keeps its background apart, lowered under the narrator (under_narrator). GET answers separation (state: original, separated, in_progress or no_sound; neededFor; nextStep when original), audioFinishing (status: queued, running, ready, needs_review or original; stage, error, errorCode, retryable, warnings, runId), revoice and, for needs_review, a candidate. POST { "action": "retry" | "accept" | "original" | "restore" | "background", "runId"?, "volume"? }: retry resumes a failed sync, accept uses the fitted dialogue a needs_review sync prepared, original plays the video's own audio (reversible), restore goes back to the fitted dialogue and background, background sets the separated background's volume (0–1). 409 with a code when the state does not allow it (story locked, result changed, nothing to retry, re-voice running). MCP: get_audio_sync, fix_audio_sync.

Separate voice and background (free) — the user's choice outside the three automatic cases above; ask first. Re-voicing a clip and changing the music under its voices need it: a re-voice of an unseparated clip answers 409 needs_separation (or, with separateFirst: true, starts the separation and answers 202 status: "separating"). Body { "clipId"? }: that clip, or without it every clip with video not yet separated (separated, separating and soundless clips are skipped). Answers started, skipped and results ([{ clipId, status: "started" | "skipped", reason? }]); each clip's separation.state (audio-sync GET) turns separated when its run ends. "Back to original sound" is audio-sync original. GET /api/v1/stories/:storyId/clips/:clipId answers the same separation and, for your own video, sourceAudio.result: whether its lines match, which line is missing, the narrator added for free, and its actions in order (keep, separate, revoice_missing, play_original). For every other clip video it answers lineCheck, the voice check of its own speech against its lines: status match · needs_review · needs_voice, reason missing_lines · extra_speech · wrong_speaker_unknown, extraSpeech (the words), missingLines, kept. Captions keep the script's words and follow measured words (at least 0.9 s on screen, script dashes not shown). MCP: clip_source_audio (action separate), separate_story_audio.

Reorder. Body: { "clips": [{ "id": "...", "order": 0 }, …] } — send every clip with a contiguous 0-based order. Looks (a running injury, a change of outfit) keep starting at the clip they started at.

Cut a clip; the remaining orders close up. A story keeps at least one clip (400 LAST_CLIP); a clip a storyline branches from stays (409 BRANCH_POINT, with its storylineId); a clip in an unfinished hire stays (409 CLIP_IN_HIRE).