The shortdrama.script.v1 format

shortdrama.script.v1 is one JSON document that holds a whole short drama: its settings, the story bible, the characters and their looks, the places, the props, and every episode with its scene-by-scene script. Agents use it to write a season in one go, and you can use it to move a drama between ShortDrama Studio and your own tools.

Import: the import_script tool (MCP or POST https://api.shortdrama.studio/v2/tools/import_script) reads a document into a drama.
Export: export_script writes one, as JSON or as Fountain, the plain-text screenplay format.
JSON Schema: api.shortdrama.studio/v2/schemas/shortdrama.script.v1.json (JSON Schema 2020-12), generated from the same rules the server checks with.

Writing and importing a story never costs credits. Credits are spent only when you generate images, video and music, or render an episode.

A minimal document

{
  "format": "shortdrama.script.v1",
  "drama": { "title": "The Contract Bride", "language": "id", "genre": "billionaire_ceo", "episode_target_count": 60, "episode_target_seconds": 90 },
  "bible": { "premise": "A broke florist signs a one-year marriage contract with the CEO who ruined her father.", "central_question": "Will she take her revenge or her chance at love?" },
  "characters": [
    { "name": "Nadia", "role": "protagonist", "appearance": "Late 20s, long wavy hair, small scar on her chin", "voice_key": "female_adult_cool", "looks": [{ "name": "Florist", "outfit": "denim apron over a white tee" }] },
    { "name": "Raka", "role": "love_interest", "appearance": "Early 30s, sharp jaw, short black hair", "voice_key": "male_adult_deep_calm" }
  ],
  "locations": [{ "name": "Flower shop", "description": "Narrow shop crowded with buckets of roses", "interior": true }],
  "props": [{ "name": "Contract", "description": "A thick folder with a gold clip" }],
  "episodes": [
    {
      "number": 1,
      "title": "The Signature",
      "hook": "A stranger pays her debts in cash.",
      "cliffhanger": "The contract names her father's killer as the groom.",
      "scenes": [
        {
          "beat": "hook",
          "action": "Raka drops the contract on Nadia's counter, crushing a rose.",
          "duration_seconds": 8,
          "location": "Flower shop",
          "characters": [{ "character": "Nadia", "look": "Florist" }, { "character": "Raka" }],
          "props": ["Contract"],
          "camera": { "shot_size": "mcu", "move": "push_in" },
          "dialogue": [
            { "character": "Raka", "text": "Sign it, and your debts are gone.", "delivery": "flat, certain" },
            { "character": "Nadia", "text": "And if I don't?", "delivery": "quiet, shaking" }
          ]
        }
      ]
    }
  ]
}

How the parts fit

Part	What it holds
`format`	Always `"shortdrama.script.v1"`.
`drama`	Title, logline, `format` (`series`, `short_film`, `drama_ads`, `film_trailer`, `music_video`), genre, tropes, `language` (a BCP 47 tag like `id` or `en`), `aspect_ratio` (`9:16` by default), target episode count and seconds per episode, visual style, default models.
`bible`	Premise, structural conflict, central question, theme, tone references, world, the engine of satisfaction, the season arc and production notes.
`characters`	Name and `role` (`protagonist`, `antagonist`, `love_interest`, `supporting`, `extra`), the character sheet (want, need, wound, flaw, stakes, arc), a fixed `appearance`, `voice_key` and `voice_style`, and `looks` (outfits).
`locations`, `props`	Name and description; locations say whether they are interior and which times of day they appear in.
`episodes`	`number`, title, summary, `hook`, `cliffhanger`, `connect_back` (how it pays off the last cliffhanger), `is_paywall_gate`, and `scenes`.
`scenes`	`beat` (`hook`, `friction`, `spike`, `button`, `other`), `action`, `duration_seconds`, `location`, `time_of_day`, `mood`, `camera` (shot size, angle, move, lens), `characters` (with their `look`), `props`, `dialogue` (`character`, `text`, `delivery`) and `director_notes`.

Allowed values for genres, visual styles, shot sizes, camera moves, moods and voices come from the catalogs: ask your agent to call get_catalog, or see them in the studio. Custom values are allowed where the drama's spec says so (get_drama_spec).

Rules that matter

References are by exact name. A scene's location, its characters[].character, look and props must match names defined in the same document (or already in the drama).
Episodes merge by number. Importing updates the episodes you send and leaves the others alone. When an episode has scenes, they replace that episode's script; without scenes, only its outline changes.
Characters, places and props merge by name. Send a name that exists to update it, a new name to add it.
Every import is one change in History, so it can be undone in the studio.
Limits: 200 episodes, 40 scenes per episode, 60 characters, 100 locations and 100 props per document. A dialogue line is at most 600 characters; scene action at most 2,500.
Dialogue is spoken by the video model in the character's locked voice, so keep lines short: about 2.5 words a second fits the scene. lint_drama warns when a scene is too dense.

Fountain

export_script with format: "fountain" writes a screenplay any Fountain app opens: sections are episodes, scene headings are scenes, and character cues are dialogue. Our own exports carry the full data in Fountain notes, so exporting and importing again changes nothing. Plain screenplays from elsewhere are read by their structure: sections become episodes, headings become scenes and locations, cues become characters.

For agents

Connect your agent first (Connect your agent), then load the shortdrama-workflow skill. The full tool list, with scopes and input schemas, is at api.shortdrama.studio/v2/schemas/tools.json.