screenplay_generation_run
WRITE actual screenplay prose from existing structured story material. The verb is WRITE: turn already-built beats, scenes, or episodes into formatted screenplay text. `screenplay_writer` is chunk-scoped for feature movies and multi-act scene-oriented TV templates such as `tv_60`: call readiness first, then start one resolved chunk with `payload.granularity` and 1-based `payload.chunk_index`, then poll `job_get` until completion. Prefer `granularity="full"` with `chunk_index=1` when readiness/model capability allows it. Without chunk fields, the backend uses the project's remembered scope, or Full when no remembered scope exists and the model/template allows it, otherwise Sequence. Short-movie and one-scene projects may omit chunk fields (BeatBandit uses section 1). `episode_screenplay` is a backend-owned episode-list parent workflow for templates such as `single_scene` and `micro_drama`; start accepts 1-10 `payload.episode_ids` per call, with optional `payload.episodes_per_call` (default 10, max 10) to choose a smaller batch-size cap for that call. Split larger episode lists into batches. Use `payload.writing_voice` to opt into an exact saved Custom Voice revision. For `screenplay_writer`, `episode_screenplay`, and `scene_screenplay`, choose `preset` or `custom`. Episode Default is the visible preset whose ID is `default`. It controls page expression only and does not replace story structure, Story Style, canon, or production constraints. Use `scene_screenplay` for first-draft prose on one explicit scene or one small explicit scene batch only. `scene_screenplay` also supports `payload.generate_proposal=true` for Scene List Revision merge survivors: it produces a reviewable `diff_proposal` before mutating prose, so the caller can approve/apply survivor rewrites before Sync Screenplay ripple checks. It is not a substitute for the full feature pipeline (`treatment_wizard` → `sequence_wizard` → `screenplay_writer`). The structured outline must already exist; this tool does not build it.
When to use
The structured outline already exists and you want actual screenplay prose — the verb is WRITE.
Use `screenplay_writer` for movie or `tv_60` prose with `payload.granularity="full"` and `payload.chunk_index=1` when the selected model supports that scope.
Use smaller `screenplay_writer` chunks (`sequence`, movie `act`, or `half`) for focused reruns or when the selected model cannot support `full`.
Use `screenplay_writer` without `payload.sequence_number` for short-movie or one-scene projects; they default to section 1.
Use `episode_screenplay` for episode-list project prose generation across up to `payload.episodes_per_call` selected episodes per call (default 10, max 10).
Use `payload.writing_voice` when the draft should follow a saved Custom Voice revision instead of the mode's preset/default page expression.
Use `scene_screenplay` for first-draft prose on one scene or a small batch of up to 3 `payload.scene_codes`.
Use `scene_screenplay` with an exact saved Custom Voice revision when that scene should use the project's authored page expression.
Use `scene_screenplay` with `payload.generate_proposal=true` and `payload.authoring_context` when `story_review_run(continuity_audit readiness)` reports `scene_authoring_required` after a Scene List Revision merge.
When not to use
Do not use for precise screenplay edits.
Do not manually switch to `screenplay_edit_*` or `screenplay_snapshot_apply` while an active screenplay generation parent job is still running.
Do not use to **build** the underlying structured outline (cards, beats, scenes) — use `story_development_run` (story_bootstrap, beat_wizard, scene_wizard) first.
Do not use `scene_screenplay` to bypass missing treatment or sequence guidance for a feature screenplay; complete `treatment_wizard` and `sequence_wizard`, then use `screenplay_writer`.
Do not use to **change or polish** the story structure — use `story_revision_run` (change_wizard, polish_wizard, creative_canvas) instead.
Do not use to **read** the existing screenplay or one scene — use `screenplay_read` or the `screenplay_document` / `screenplay_scene` resources.
Do not run continuity audit before applying required scene-authoring proposals for merge survivors; author the survivor prose first, then run `story_review_run(workflow=continuity_audit)`.
Examples
“Generate the full screenplay draft from this project with `screenplay_writer` full scope.”
“Regenerate sequence 1 of a screenplay draft from this project.”
“Generate a batch of up to 10 episodic screenplays for selected episodes.”
“Write the screenplay with saved Custom Voice revision 3 while preserving the existing outline and Story Style.”
“Boundary - "Turn this finished outline into a full screenplay." Use `screenplay_writer` here because the structured outline already exists; we want prose now.”
“Boundary - "Write screenplay prose for one new scene I just outlined." Use `scene_screenplay` here.”
“Boundary - "Scene List Revision merged scenes and tells me survivor authoring is required." Use `scene_screenplay` with `payload.generate_proposal=true`, review the returned `diff_proposal`, then apply it.”
Anti-examples
- Read one screenplay scene.
- Outlining the story before any cards exist — that is `story_development_run` with `story_bootstrap`.
- Writing all scenes one-by-one with `scene_screenplay` because `screenplay_writer` readiness says treatment/sequence guidance is missing — finish those development stages instead.
- Sending more than 3 `scene_codes` in one `scene_screenplay` call — split into multiple focused batches.
- Sending more than `payload.episodes_per_call` episode IDs in one `episode_screenplay` call — split into batches.
- Polishing existing dialogue in a scene — that is `story_revision_run` with `polish_wizard`.
- Making a single surgical edit to existing screenplay prose — that is `screenplay_edit_propose` then `screenplay_edit_apply`.
Workflows
Switch behavior by setting the workflow input field.
screenplay_writer
episode_screenplay
scene_screenplay
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"oneOf": [
{
"type": "object",
"required": [
"workflow",
"phase",
"project_id"
],
"properties": {
"workflow": {
"const": "screenplay_writer"
},
"phase": {
"type": "string",
"enum": [
"readiness",
"start"
]
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"properties": {
"sequence_number": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"description": "Legacy alias for sequence scope. New callers should use granularity plus chunk_index."
},
"granularity": {
"type": "string",
"enum": [
"sequence",
"act",
"half",
"full"
]
},
"chunk_index": {
"type": "integer",
"minimum": 1
},
"template_id": {
"type": "string"
},
"writing_voice": {
"description": "Optional exclusive page-expression source. Use a visible preset ID or the exact saved Custom Voice revision.",
"oneOf": [
{
"type": "object",
"required": [
"kind",
"preset_id"
],
"properties": {
"kind": {
"const": "preset"
},
"preset_id": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"revision"
],
"properties": {
"kind": {
"const": "custom"
},
"revision": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
}
]
},
"custom_guidance": {
"type": "string"
},
"llm_identifier": {
"type": "string",
"minLength": 1
},
"options": {
"type": "object",
"properties": {
"indicate_scene_beats": {
"type": "boolean"
},
"target_duration_seconds": {
"type": "integer"
},
"screenplay_intent": {
"type": "string",
"enum": [
"reader_draft",
"low_budget",
"medium_budget",
"high_budget",
"genai_production"
]
}
},
"additionalProperties": false
}
},
"allOf": [
{
"if": {
"required": [
"writing_voice"
]
},
"then": {
"not": {
"required": [
"template_id"
]
}
}
}
],
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"workflow",
"phase",
"project_id"
],
"properties": {
"workflow": {
"const": "episode_screenplay"
},
"phase": {
"const": "readiness"
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"properties": {
"episode_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 10,
"description": "For start: write a batch of 1-10 canonical episode IDs."
},
"episodes_per_call": {
"type": "integer",
"minimum": 1,
"maximum": 10
},
"custom_guidance": {
"type": "string"
},
"writing_voice": {
"description": "Optional exclusive page-expression source. Use a visible preset ID or the exact saved Custom Voice revision.",
"oneOf": [
{
"type": "object",
"required": [
"kind",
"preset_id"
],
"properties": {
"kind": {
"const": "preset"
},
"preset_id": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"revision"
],
"properties": {
"kind": {
"const": "custom"
},
"revision": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
}
]
},
"llm_identifier": {
"type": "string",
"minLength": 1
},
"target_duration_seconds": {
"type": "integer"
},
"options": {
"type": "object",
"properties": {
"screenplay_intent": {
"type": "string",
"enum": [
"reader_draft",
"low_budget",
"medium_budget",
"high_budget",
"genai_production"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"workflow",
"phase",
"project_id",
"payload"
],
"properties": {
"workflow": {
"const": "episode_screenplay"
},
"phase": {
"const": "start"
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"properties": {
"episode_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 10,
"description": "For start: write a batch of 1-10 canonical episode IDs."
},
"episodes_per_call": {
"type": "integer",
"minimum": 1,
"maximum": 10
},
"custom_guidance": {
"type": "string"
},
"writing_voice": {
"description": "Optional exclusive page-expression source. Use a visible preset ID or the exact saved Custom Voice revision.",
"oneOf": [
{
"type": "object",
"required": [
"kind",
"preset_id"
],
"properties": {
"kind": {
"const": "preset"
},
"preset_id": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"revision"
],
"properties": {
"kind": {
"const": "custom"
},
"revision": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
}
]
},
"llm_identifier": {
"type": "string",
"minLength": 1
},
"target_duration_seconds": {
"type": "integer"
},
"options": {
"type": "object",
"properties": {
"screenplay_intent": {
"type": "string",
"enum": [
"reader_draft",
"low_budget",
"medium_budget",
"high_budget",
"genai_production"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"required": [
"episode_ids"
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"workflow",
"phase",
"project_id",
"payload"
],
"properties": {
"workflow": {
"const": "scene_screenplay"
},
"phase": {
"type": "string",
"enum": [
"readiness",
"start"
]
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"properties": {
"scene_id": {
"type": "string"
},
"scene_codes": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 3
},
"custom_guidance": {
"type": "string"
},
"template_id": {
"type": "string"
},
"writing_voice": {
"description": "Optional exclusive page-expression source. Use a visible preset ID or the exact saved Custom Voice revision.",
"oneOf": [
{
"type": "object",
"required": [
"kind",
"preset_id"
],
"properties": {
"kind": {
"const": "preset"
},
"preset_id": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"kind",
"revision"
],
"properties": {
"kind": {
"const": "custom"
},
"revision": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
}
]
},
"llm_identifier": {
"type": "string",
"minLength": 1
},
"generate_proposal": {
"type": "boolean"
},
"authoring_context": {
"type": "object"
}
},
"oneOf": [
{
"required": [
"scene_id"
],
"not": {
"required": [
"scene_codes"
]
}
},
{
"required": [
"scene_codes"
],
"not": {
"required": [
"scene_id"
]
}
}
],
"allOf": [
{
"not": {
"required": [
"regenerate"
]
}
},
{
"if": {
"required": [
"writing_voice"
]
},
"then": {
"not": {
"required": [
"template_id"
]
}
}
},
{
"if": {
"properties": {
"generate_proposal": {
"const": true
}
},
"required": [
"generate_proposal"
]
},
"then": {
"required": [
"scene_id"
]
}
}
],
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"workflow",
"phase"
],
"properties": {
"workflow": {
"type": "string"
},
"phase": {
"type": "string"
},
"async": {
"type": "boolean"
},
"job_id": {
"type": "string"
},
"readiness": {
"type": "object"
},
"result": {
"type": "object"
},
"recommended_action": {
"type": "string"
},
"screenplay_stage": {
"type": "string"
},
"project_id": {
"type": "integer"
},
"project_name": {
"type": "string"
},
"project_mode": {
"type": "string"
},
"proposal_id": {
"type": "string",
"description": "Saved diff proposal id when scene_screenplay runs in payload.generate_proposal mode."
},
"scene_authoring_segments": {
"type": "array",
"description": "Generated scene segments stored for review before explicit proposal apply.",
"items": {
"type": "object"
}
},
"base_screenplay_rev": {
"type": "integer",
"description": "Screenplay snapshot revision captured when the reviewable proposal was generated."
},
"sequence_number": {
"type": "integer"
},
"total_sequences": {
"type": [
"integer",
"null"
]
},
"valid_sequence_numbers": {
"type": "array",
"items": {
"type": "integer"
}
},
"structure_key": {
"type": [
"string",
"null"
]
},
"template_id": {
"type": [
"string",
"null"
],
"description": "Selected preset identity, or null when Custom Voice is the sole authorial-expression source."
},
"template_name": {
"type": [
"string",
"null"
],
"description": "Selected preset label, or null when Custom Voice is the sole authorial-expression source."
},
"target_card_code": {
"type": "string"
},
"resource_links": {
"type": "array",
"items": {
"type": "object"
}
},
"pipeline_state": {
"$ref": "./_common/pipeline_state.schema.json"
},
"next_actions": {
"type": "array",
"items": {
"$ref": "./_common/next_action.schema.json"
}
}
},
"additionalProperties": true
}