Story video API

Turn an idea into an editable story, consistent animated scenes, native character dialogue or narration, and a finished MP4. The complete workflow accepts an API key; no dashboard session is needed.

Send Authorization: Bearer YOUR_API_KEY. Keys need jobs:write for mutations and jobs:read for polling, listing and estimates. Discover this contract at GET /api/v1/capabilities under storyVideo; full schemas are in OpenAPI.

curl https://www.vydra.ai/api/v1/remix/story \
  -H "Authorization: Bearer $VYDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idea":"A tiny robot learns to grow a garden on Mars","style":"Warm cinematic 3D animation","durationSec":30,"aspect":"9:16","audioMode":"native-dialogue","productionMode":"reviewed"}'

1. Automatic mode continues through generation and assembly on the server; poll until done or failed. No storyboard or approval actions are needed.
2. Create returns 202 and a project ID. Poll status every 5–10 seconds until ready; failed is terminal.
3. Review blueprint and estimate remaining credits. PATCH accepts {blueprint} with the full edited blueprint while ready/done.
4. Build with {"stage":"prepare"}; poll until ready and production.preparationReady is true.
5. For productionMode reviewed, build with {"stage":"storyboard"}. Inspect production.frames and PATCH approvedFrameUrl on each shot to approve its current URL. Changed inputs invalidate approval. Increment frameTake for another picture or take for another video; optional shotIds scopes build calls.
6. Estimate again, then build with {"stage":"build"}; poll until ready and production.buildReady is true.
7. New Cinema movies use pipelineVersion 2: preparation includes reusable character audio; shots are 4–8 seconds. Follow production.quality.next: create one opening frame, check it with stage review, generate its video, then review that video before the next frame. Continue until production.quality.passed equals total. A failed check stops production; use the quoted repair endpoint to retry.
8. For reviewed stories, watch each production.scenes video and PATCH its shot.approvedVideoUrl before rendering.
9. Render; poll until done, then use render.videoUrl. Inspect error and asset errors if a stage is ready without its readiness flag.

{"stage":"prepare"}

{"stage":"storyboard"}

{"stage":"build"}

Edit the blueprint

Read blueprint from the project and PATCH /api/v1/remix/{id}/blueprint with the complete {blueprint} object. Preserve IDs and metadata. Narrated stories use one narrator, up to 12 script lines with up to 26 words each, and one scene per line. Each scene has wordStart 0, wordEnd equal to its line’s whitespace-separated word count, and castIds listing visible characters (an empty array for scenery). Changing narration, style or cast can invalidate completed assets; estimate and prepare again.

Progress, costs and recovery

Planning and generation charge credits. Estimate is free; matching completed assets are reused. Estimate again after preparation because narration timing changes scene lengths. Creation is not idempotent. Do not blindly retry timed-out POSTs; recover via list/status first. Retry a failed build only after inspecting state and errors. List projects with GET /api/v1/remix?limit=20&offset=0. Projects and assets are scoped to the key’s workspace.

A ready status can include failed assets; always check production readiness flags and assets[].error. A 409 means the stage is not ready (including PREPARATION_REQUIRED or STORY_BUILD_INCOMPLETE); 402 means insufficient credits; 403 means missing scope; 404 means the project is unavailable to this workspace; 503 means a required service is unconfigured. Project completion uses polling, with no project webhooks. Native dialogue preserves each scene’s playback speed, generated speech and sound; automatic captions are not added in native-dialogue mode.

Speaking characters

Character dialogue is the default audioMode. The blueprint stores this as story.audioMode. Each scene includes durationSec (4–15 for Seedance 2.0, 4–30 for Seedance 2.5) and dialogue turns with castId and text. All speakers must appear in castIds, and scene durations must total the requested length. The matching script line joins those spoken texts in order. New Seedance 2.5 dialogue movies use story.pipelineVersion = 2: 4–8 second shots, at most two speaking turns, and staging with opening, action, closing and camera. Each speaker has a distinct voicePreset and a 15–35 word voiceSample. Preparation creates one reusable TTS reference per speaker, included in the estimate, and visual references. Audio references guide native dialogue; exact voice matching is still checked rather than guaranteed. No narrator is added.

Seedance 2.5 movies can set continuesFrom to the immediately preceding scene ID for uninterrupted action in the same location. Generation waits for that video, prepares it to the exact edit point, and extends its motion and audio. The returned continuation contains only the new segment. Omit continuesFrom for a new location or deliberate scene cut. A longer provider limit does not change the new pipeline’s 4–8 second shot limit.

Scene quality and repair

New movies check the plan for contradictory physical states before buying images or clips. They then check each opening frame for identity, composition and prop placement before animation, then alternate video generation with audiovisual screening (status reviewing). Voices, dialogue, identity, physics, continuity and pacing must pass before the next shot or final assembly. Automated screening can miss defects; it does not guarantee film quality. A failed or inconclusive check stops the project and preserves completed work. No paid takes retry automatically. POST /api/v1/remix/:id/build with stage review checks the next finished shot. On a stopped film, production.quality.repair provides kind (frame or video), shotId, retryMode and retryCredits. POST /api/v1/remix/:id/repair with shotId, mode and expectedCredits retries that check or authorizes one replacement take. Checks have no separate customer charge. Old projects retain their original pipeline.

MCP tools

Use create_story, get_story, list_stories, update_story_blueprint, estimate_story, build_story, repair_story and render_story. These call the same API with VYDRA_API_KEY. Build the MCP package from this release to use the new tools.