screenplay_generation_run
Use when an existing outline is ready for screenplay prose: a movie/TV draft, selected episodes, a scene, or dependent pages for a saved story revision. Build missing outlines with story_development_run; revise existing prose with screenplay_edit_propose or screenplay_rewrite_run. Check readiness, quote, obtain acceptance, then Start with payload.billing_quote_id and payload.billing_request_id; reuse both IDs and the quoted scope on retries. Follow job_get's completion/finalize actions. Revision-linked generation produces reviewable page proposals; review and explicitly apply them through their parent story_revision_run. Dependent pages cannot be applied alone.
When to use
- For screenplay_writer, omitted chunk fields use the project's remembered scope, or Full when supported, otherwise Sequence. Short-movie and one-scene projects default to section 1.
- For uncommitted story changes, inspect phase=source with revision_id and source_selection, then use its returned scene_id with the same selection for readiness, quote and accepted Start. An episodic source ID targets the whole episode, including its nested scenes.
- Revision-linked scene_screenplay captures source without changing current pages. Follow job_get's finalize action, review the saved diff_proposal, and apply the page candidate with its parent revision's selected operations or choices.
- A source_selection with empty operation_ids continues an already accepted plan. Accepted page ancestors remain read evidence when current pages match; do not select them for another write.
- Writing Voice controls page expression while preserving story structure, Story Style, canon and production constraints. Episode Default uses preset_id=default.
- 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 the saved `payload.revision_id` and `payload.followup_id` to propose dependent pages after a structural decision.
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 the saved revision/follow-up IDs, finalize its job, review the shared `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.
| Workflow | Phases | Calls |
|---|---|---|
screenplay_writer | readiness, quote, start | screenplay_writer.start |
episode_screenplay | readiness, quote, start | episode_screenplay.run |
scene_screenplay | readiness, quote, start, finalize | scene_screenplay.run |
Linked resources
Tool calls may return resource_links pointing at these resource families.
project_canon_summaryscreenplay_documentproject_diff_proposalsdiff_proposalepisode_screenplay_result
Input schema
screenplay_generation_run input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"oneOf": [
{
"type": "object",
"required": [
"workflow",
"phase",
"project_id"
],
"properties": {
"workflow": {
"const": "screenplay_writer",
"description": "screenplay_writer writes movie or scene-oriented TV chunks; episode_screenplay writes selected episodes; scene_screenplay writes one scene/small batch or revision-dependent pages. Complete treatment/sequence guidance before a feature draft."
},
"phase": {
"type": "string",
"enum": [
"readiness",
"quote",
"start"
],
"description": "Check readiness, then quote and accepted Start. Follow job_get completion actions. source inspects proposed story/pages without edits; source and finalize are scene_screenplay only."
},
"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"
],
"description": "screenplay_writer scope. Prefer full with chunk_index=1 when readiness/model supports it; use smaller chunks for focused reruns. Omitted scope uses remembered settings, otherwise Full when supported, else Sequence."
},
"chunk_index": {
"type": "integer",
"minimum": 1,
"description": "1-based index within the selected granularity. Full uses 1; short-movie and one-scene projects may omit chunk fields and use section 1."
},
"template_id": {
"type": "string"
},
"writing_voice": {
"description": "Choose a visible preset ID or exact saved Custom Voice revision. Episode Default uses preset_id=default. Controls page expression while preserving story structure, Story Style and canon.",
"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
},
"billing_quote_id": {
"type": "string",
"format": "uuid",
"description": "Accepted quote identity from the returned Start action; required on Start only. Reuse unchanged on retries."
},
"billing_request_id": {
"type": "string",
"format": "uuid",
"description": "Start request UUID from the accepted quote action; required on Start only. Reuse with the same quote and scope on retries."
}
},
"allOf": [
{
"if": {
"required": [
"writing_voice"
]
},
"then": {
"not": {
"required": [
"template_id"
]
}
}
}
],
"additionalProperties": false
}
},
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"phase": {
"const": "start"
}
}
},
"then": {
"required": [
"payload"
],
"properties": {
"payload": {
"required": [
"billing_quote_id",
"billing_request_id"
]
}
}
},
"else": {
"properties": {
"payload": {
"not": {
"anyOf": [
{
"required": [
"billing_quote_id"
]
},
{
"required": [
"billing_request_id"
]
}
]
}
}
}
}
}
]
},
{
"type": "object",
"required": [
"workflow",
"phase",
"project_id"
],
"properties": {
"workflow": {
"const": "episode_screenplay",
"description": "screenplay_writer writes movie or scene-oriented TV chunks; episode_screenplay writes selected episodes; scene_screenplay writes one scene/small batch or revision-dependent pages. Complete treatment/sequence guidance before a feature draft."
},
"phase": {
"const": "readiness",
"description": "Check readiness, then quote and accepted Start. Follow job_get completion actions. source inspects proposed story/pages without edits; source and finalize are scene_screenplay only."
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"properties": {
"episode_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 10,
"description": "episode_screenplay targets: 1-10 observed episode IDs. Split larger lists into batches; each call must also respect episodes_per_call."
},
"episodes_per_call": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "episode_screenplay batch cap, default 10 and maximum 10. Select no more episode_ids than this cap."
},
"custom_guidance": {
"type": "string"
},
"writing_voice": {
"description": "Choose a visible preset ID or exact saved Custom Voice revision. Episode Default uses preset_id=default. Controls page expression while preserving story structure, Story Style and canon.",
"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",
"description": "screenplay_writer writes movie or scene-oriented TV chunks; episode_screenplay writes selected episodes; scene_screenplay writes one scene/small batch or revision-dependent pages. Complete treatment/sequence guidance before a feature draft."
},
"phase": {
"const": "start",
"description": "Check readiness, then quote and accepted Start. Follow job_get completion actions. source inspects proposed story/pages without edits; source and finalize are scene_screenplay only."
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"properties": {
"episode_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 10,
"description": "episode_screenplay targets: 1-10 observed episode IDs. Split larger lists into batches; each call must also respect episodes_per_call."
},
"episodes_per_call": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "episode_screenplay batch cap, default 10 and maximum 10. Select no more episode_ids than this cap."
},
"custom_guidance": {
"type": "string"
},
"writing_voice": {
"description": "Choose a visible preset ID or exact saved Custom Voice revision. Episode Default uses preset_id=default. Controls page expression while preserving story structure, Story Style and canon.",
"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
},
"billing_quote_id": {
"type": "string",
"format": "uuid",
"description": "Accepted quote identity from the returned Start action; required on Start only. Reuse unchanged on retries."
},
"billing_request_id": {
"type": "string",
"format": "uuid",
"description": "Start request UUID from the accepted quote action; required on Start only. Reuse with the same quote and scope on retries."
}
},
"additionalProperties": false,
"required": [
"episode_ids",
"billing_quote_id",
"billing_request_id"
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"workflow",
"phase",
"project_id",
"payload"
],
"properties": {
"workflow": {
"const": "episode_screenplay",
"description": "screenplay_writer writes movie or scene-oriented TV chunks; episode_screenplay writes selected episodes; scene_screenplay writes one scene/small batch or revision-dependent pages. Complete treatment/sequence guidance before a feature draft."
},
"phase": {
"const": "quote",
"description": "Check readiness, then quote and accepted Start. Follow job_get completion actions. source inspects proposed story/pages without edits; source and finalize are scene_screenplay only."
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"properties": {
"episode_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 10,
"description": "episode_screenplay targets: 1-10 observed episode IDs. Split larger lists into batches; each call must also respect episodes_per_call."
},
"episodes_per_call": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "episode_screenplay batch cap, default 10 and maximum 10. Select no more episode_ids than this cap."
},
"custom_guidance": {
"type": "string"
},
"writing_voice": {
"description": "Choose a visible preset ID or exact saved Custom Voice revision. Episode Default uses preset_id=default. Controls page expression while preserving story structure, Story Style and canon.",
"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",
"description": "screenplay_writer writes movie or scene-oriented TV chunks; episode_screenplay writes selected episodes; scene_screenplay writes one scene/small batch or revision-dependent pages. Complete treatment/sequence guidance before a feature draft."
},
"phase": {
"type": "string",
"enum": [
"readiness",
"quote",
"start"
],
"description": "Check readiness, then quote and accepted Start. Follow job_get completion actions. source inspects proposed story/pages without edits; source and finalize are scene_screenplay only."
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"properties": {
"scene_id": {
"type": "string",
"description": "scene_screenplay target. For proposed source, use the ID returned by phase=source with the same revision/selection; an episodic source ID targets the whole episode including nested scenes."
},
"scene_codes": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 3,
"description": "scene_screenplay first-draft targets: up to 3 observed scene codes. Choose scene_id or scene_codes, not both."
},
"custom_guidance": {
"type": "string"
},
"template_id": {
"type": "string"
},
"writing_voice": {
"description": "Choose a visible preset ID or exact saved Custom Voice revision. Episode Default uses preset_id=default. Controls page expression while preserving story structure, Story Style and canon.",
"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
},
"billing_quote_id": {
"type": "string",
"format": "uuid",
"description": "Accepted quote identity from the returned Start action; required on Start only. Reuse unchanged on retries."
},
"billing_request_id": {
"type": "string",
"format": "uuid",
"description": "Start request UUID from the accepted quote action; required on Start only. Reuse with the same quote and scope on retries."
}
},
"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"
]
}
}
}
],
"additionalProperties": false
}
},
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"phase": {
"const": "start"
}
}
},
"then": {
"required": [
"payload"
],
"properties": {
"payload": {
"required": [
"billing_quote_id",
"billing_request_id"
]
}
}
},
"else": {
"properties": {
"payload": {
"not": {
"anyOf": [
{
"required": [
"billing_quote_id"
]
},
{
"required": [
"billing_request_id"
]
}
]
}
}
}
}
}
]
},
{
"type": "object",
"required": [
"workflow",
"phase",
"project_id",
"payload"
],
"properties": {
"workflow": {
"const": "scene_screenplay",
"description": "screenplay_writer writes movie or scene-oriented TV chunks; episode_screenplay writes selected episodes; scene_screenplay writes one scene/small batch or revision-dependent pages. Complete treatment/sequence guidance before a feature draft."
},
"phase": {
"type": "string",
"enum": [
"readiness",
"quote",
"start"
],
"description": "Check readiness, then quote and accepted Start. Follow job_get completion actions. source inspects proposed story/pages without edits; source and finalize are scene_screenplay only."
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"properties": {
"custom_guidance": {
"type": "string"
},
"template_id": {
"type": "string"
},
"writing_voice": {
"description": "Choose a visible preset ID or exact saved Custom Voice revision. Episode Default uses preset_id=default. Controls page expression while preserving story structure, Story Style and canon.",
"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
},
"revision_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Saved parent revision for scene_screenplay. Use with followup_id for a saved structural decision, or source_selection for proposed material. Retain the identity through finalize and parent Apply."
},
"followup_id": {
"type": "string",
"minLength": 3,
"maxLength": 64,
"pattern": "^\\d+:\\d+quot;,
"description": "Saved structural decision target; use with revision_id instead of scene_id/scene_codes. Generates a reviewable proposal without changing current pages."
},
"billing_quote_id": {
"type": "string",
"format": "uuid",
"description": "Accepted quote identity from the returned Start action; required on Start only. Reuse unchanged on retries."
},
"billing_request_id": {
"type": "string",
"format": "uuid",
"description": "Start request UUID from the accepted quote action; required on Start only. Reuse with the same quote and scope on retries."
}
},
"allOf": [
{
"not": {
"required": [
"regenerate"
]
}
},
{
"if": {
"required": [
"writing_voice"
]
},
"then": {
"not": {
"required": [
"template_id"
]
}
}
}
],
"additionalProperties": false,
"required": [
"revision_id",
"followup_id"
]
}
},
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"phase": {
"const": "start"
}
}
},
"then": {
"required": [
"payload"
],
"properties": {
"payload": {
"required": [
"billing_quote_id",
"billing_request_id"
]
}
}
},
"else": {
"properties": {
"payload": {
"not": {
"anyOf": [
{
"required": [
"billing_quote_id"
]
},
{
"required": [
"billing_request_id"
]
}
]
}
}
}
}
}
]
},
{
"type": "object",
"required": [
"workflow",
"phase",
"project_id",
"job_id"
],
"properties": {
"workflow": {
"const": "scene_screenplay",
"description": "screenplay_writer writes movie or scene-oriented TV chunks; episode_screenplay writes selected episodes; scene_screenplay writes one scene/small batch or revision-dependent pages. Complete treatment/sequence guidance before a feature draft."
},
"phase": {
"const": "finalize",
"description": "Check readiness, then quote and accepted Start. Follow job_get completion actions. source inspects proposed story/pages without edits; source and finalize are scene_screenplay only."
},
"project_id": {
"type": "integer"
},
"job_id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"payload": {
"type": "object",
"properties": {
"revision_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Saved parent revision for scene_screenplay. Use with followup_id for a saved structural decision, or source_selection for proposed material. Retain the identity through finalize and parent Apply."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"workflow",
"phase",
"project_id",
"payload"
],
"properties": {
"workflow": {
"const": "scene_screenplay",
"description": "screenplay_writer writes movie or scene-oriented TV chunks; episode_screenplay writes selected episodes; scene_screenplay writes one scene/small batch or revision-dependent pages. Complete treatment/sequence guidance before a feature draft."
},
"phase": {
"type": "string",
"enum": [
"readiness",
"quote",
"start"
],
"description": "Check readiness, then quote and accepted Start. Follow job_get completion actions. source inspects proposed story/pages without edits; source and finalize are scene_screenplay only."
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"properties": {
"custom_guidance": {
"type": "string"
},
"template_id": {
"type": "string"
},
"writing_voice": {
"description": "Choose a visible preset ID or exact saved Custom Voice revision. Episode Default uses preset_id=default. Controls page expression while preserving story structure, Story Style and canon.",
"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
},
"revision_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Saved parent revision for scene_screenplay. Use with followup_id for a saved structural decision, or source_selection for proposed material. Retain the identity through finalize and parent Apply."
},
"source_selection": {
"type": "object",
"required": [
"proposal_id",
"operation_ids"
],
"properties": {
"proposal_id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"operation_ids": {
"type": "array",
"minItems": 0,
"maxItems": 500,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"edited_fields": {
"type": "object",
"maxProperties": 500,
"additionalProperties": {
"type": "object",
"additionalProperties": true
}
}
},
"additionalProperties": false,
"description": "Parent proposal_id and exact selected operation_ids (planning suggestion IDs for planning_revision). Inspect with phase=source first, then retain the selection for readiness/quote/Start. Empty operation_ids can continue an accepted plan."
},
"scene_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "scene_screenplay target. For proposed source, use the ID returned by phase=source with the same revision/selection; an episodic source ID targets the whole episode including nested scenes."
},
"page_proposal_ids": {
"type": "array",
"maxItems": 20,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"description": "Existing page candidates used as proposed-source evidence. Keep selection through readiness/quote/Start. Accepted ancestors are read evidence when current pages match; do not select them for another write."
},
"billing_quote_id": {
"type": "string",
"format": "uuid",
"description": "Accepted quote identity from the returned Start action; required on Start only. Reuse unchanged on retries."
},
"billing_request_id": {
"type": "string",
"format": "uuid",
"description": "Start request UUID from the accepted quote action; required on Start only. Reuse with the same quote and scope on retries."
}
},
"allOf": [
{
"not": {
"required": [
"regenerate"
]
}
},
{
"if": {
"required": [
"writing_voice"
]
},
"then": {
"not": {
"required": [
"template_id"
]
}
}
}
],
"additionalProperties": false,
"required": [
"revision_id",
"source_selection",
"scene_id"
]
}
},
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"phase": {
"const": "start"
}
}
},
"then": {
"required": [
"payload"
],
"properties": {
"payload": {
"required": [
"billing_quote_id",
"billing_request_id"
]
}
}
},
"else": {
"properties": {
"payload": {
"not": {
"anyOf": [
{
"required": [
"billing_quote_id"
]
},
{
"required": [
"billing_request_id"
]
}
]
}
}
}
}
}
]
},
{
"type": "object",
"required": [
"workflow",
"phase",
"project_id",
"payload"
],
"properties": {
"workflow": {
"const": "scene_screenplay",
"description": "screenplay_writer writes movie or scene-oriented TV chunks; episode_screenplay writes selected episodes; scene_screenplay writes one scene/small batch or revision-dependent pages. Complete treatment/sequence guidance before a feature draft."
},
"phase": {
"const": "source",
"description": "Check readiness, then quote and accepted Start. Follow job_get completion actions. source inspects proposed story/pages without edits; source and finalize are scene_screenplay only."
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"required": [
"revision_id",
"source_selection"
],
"properties": {
"revision_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Saved parent revision for scene_screenplay. Use with followup_id for a saved structural decision, or source_selection for proposed material. Retain the identity through finalize and parent Apply."
},
"source_selection": {
"type": "object",
"required": [
"proposal_id",
"operation_ids"
],
"properties": {
"proposal_id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"operation_ids": {
"type": "array",
"minItems": 0,
"maxItems": 500,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"edited_fields": {
"type": "object",
"maxProperties": 500,
"additionalProperties": {
"type": "object",
"additionalProperties": true
}
}
},
"additionalProperties": false,
"description": "Parent proposal_id and exact selected operation_ids (planning suggestion IDs for planning_revision). Inspect with phase=source first, then retain the selection for readiness/quote/Start. Empty operation_ids can continue an accepted plan."
},
"page_proposal_ids": {
"type": "array",
"maxItems": 20,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"description": "Existing page candidates used as proposed-source evidence. Keep selection through readiness/quote/Start. Accepted ancestors are read evidence when current pages match; do not select them for another write."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
}Output schema
screenplay_generation_run output
{
"$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"
},
"source_proposal_id": {
"type": "string"
},
"source_selection": {
"type": "object"
},
"source_fingerprint": {
"type": "string"
},
"parent_source_fingerprint": {
"type": "string"
},
"review_page_proposal_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"scenes": {
"type": "array",
"items": {
"type": "object"
},
"description": "Proposed-source targets with stable scene IDs, current text and suggested status. Read these IDs before generation; newly proposed scenes are not yet canonical."
},
"proposal_id": {
"type": "string",
"description": "Saved shared diff proposal id when scene_screenplay targets a revision follow-up."
},
"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",
"null"
]
},
"granularity": {
"type": "string"
},
"effective_granularity": {
"type": "string",
"description": "Backend-resolved generation scope; do not infer a single sequence from sequence_number."
},
"chunk_index": {
"type": [
"integer",
"null"
]
},
"covered_sequence_numbers": {
"type": "array",
"items": {
"type": "integer"
}
},
"target_cards": {
"type": "array",
"items": {
"type": "object"
}
},
"writing_voice": {
"type": [
"object",
"null"
]
},
"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",
"null"
]
},
"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
}← All toolsv1 · workflow_runner