Storyboards API, MCP & CLI

A storyboard is a short video built scene by scene. Each scene has a beat (title, purpose, dialogue) and one or more shots labelled 3b (scene 3, second shot). The same operations are available in Moss chat, over MCP, from the mostly CLI and over REST.

Writing and editing are free. Rendering and exporting spend credits. Any call that would spend credits needs maxCredits: without it, or when the estimate is higher, nothing is spent and the response has "status": "needs_confirmation" with estimatedCredits.

Workflow

1. Write: POST /api/v1/storyboards with prompt and optionally beats (one per scene, in order). Scenes appear in about a minute.
2. Review: GET /api/v1/storyboards/:id (add ?format=full for whole prompts and the @[Name](image:id) mentions of your cast and products).
3. Render: POST /api/v1/storyboards/:id/render with {} to get the price, then again with maxCredits.
4. Edit: change shots and beats, then render again with scope: "stale". Only edited shots re-render; earlier renders stay as alternative takes.
5. Export: POST /api/v1/storyboards/:id/export with maxCredits, then poll GET /api/v1/storyboards/:id/exports/:exportId for videoUrl.

Endpoints

All endpoints take Authorization: Bearer mst_live_... and an optional x-mostly-brand-id header.

Editing with a spec

GET ?format=spec returns every scene in order with its beat, narration and shots. Edit it and PUT it back:

• a scene or shot without id is created,
• the order of scenes (and of each scene's shots) becomes the play order,
• with prune: true, scenes and shots you left out are hidden (nothing is deleted),
• dryRun: true lists the changes without applying them.

Webhooks

Pass webhookUrl (public https) when creating or updating a storyboard. The response includes a webhookSecret once. Events are POSTed as JSON with an x-mostly-event header and x-mostly-signature: sha256=<HMAC-SHA256 of the raw body with the secret>:

• storyboard.scenes_ready, storyboard.failed
• storyboard.renders_settled (no render left running)
• storyboard.export_completed, storyboard.export_failed

Delivery is best-effort with one attempt, and you may receive an event more than once, so re-read the storyboard rather than relying on the payload alone.

MCP tools

list_storyboards, get_storyboard, generate_storyboard, update_storyboard, create_storyboard_scene, update_storyboard_scene, move_storyboard_scene, delete_storyboard_scene, generate_scene_content, update_storyboard_shot, add_storyboard_shot, delete_storyboard_shot, render_storyboard, review_storyboard (returns rendered frames as images), export_storyboard, get_storyboard_export, apply_storyboard_spec.

CLI

mostly storyboard create --prompt "UGC ad for our serum" --duration 30 --lens UGC --wait
mostly storyboard render <id>                      # prints the price, exit code 2
mostly storyboard render <id> --max-credits 150 --wait
mostly storyboard pull <id> --out sb.json && mostly storyboard apply sb.json --render changed --max-credits 100
mostly storyboard export <id> --max-credits 20 --out ad.mp4