API reference

Workflows API

Workflows are durable, asynchronous jobs. A prepare workflow structures text into narration and dialogue; a Create Audio workflow casts voices and generates multi-voice audio. Poll a workflow until it reaches a terminal status. A provider-account limit is reported as a failed step with `STUDIO_WORKFLOW_PROVIDER_QUOTA_EXCEEDED`; generation-batch targets use `PROVIDER_QUOTA_EXCEEDED`. Completed audio remains available. For a shared provider limit, contact us to restore provider access before explicitly resuming. When the failure message says the account's monthly ElevenLabs voice preparation allowance is used up, choose a cached ElevenLabs voice or another engine, or wait for the allowance to reset on the first of the month (UTC). Do not automatically resubmit quota failures.

BetaUpdated October 4, 2026

Markdown Ask ChatGPT Ask Claude

Base URL: https://lyricwinter.com/api/v1
Authentication: Authorization: Bearer lw_…
Contract: openapi.json

Start a workflow

POST/studio/projects/{projectId}/workflows

Scope studio:writeRetry with the same client_mutation_id

Starts a prepare_sections workflow, which structures text into narration and dialogue, or a create_audio workflow, which prepares text, casts voices, directs performances, adds sound effects, and generates audio. Returns 202 with data: { run, steps }; poll the returned run ID until it reaches a terminal status. Replaying the same client_mutation_id returns the same workflow instead of starting another.

Path parameters

projectIdstringrequireduuid

Request body application/json

One of 2 shapes:

schema_version: 1, workflow_kind: "prepare_sections"

Start ordered section preparation.

schema_version1required
workflow_kind"prepare_sections"required
actor_session_idstringrequireduuid
Client session that issued the request.
client_mutation_idstringrequireduuid
Idempotency key; the workflow ID is derived from it. Reusing it for different content returns 409.
section_idsarray of stringrequired1–100 itemsunique
Sections to prepare, in order; values must be unique.

schema_version: 2, workflow_kind: "create_audio"

Create Audio v2. Generated sound effects and automatic placement of linked project sounds are independent; when both run, project sounds are placed first. Section limit: 12 with both sound lanes enabled (the default), 14 with one, 16 with none. A target_scope requires exactly one section and both lanes set to false.

schema_version2required
workflow_kind"create_audio"required
actor_session_idstringrequireduuid
Client session that issued the request.
client_mutation_idstringrequireduuid
Idempotency key; the workflow ID is derived from it. Reusing it for different content returns 409.
section_idsarray of stringrequired1–16 itemsunique
Sections to create audio for; values must be unique.
include_generated_sfxbooleandefault true
Enables the generated-SFX authoring lane.
place_project_soundsbooleandefault true
Enables automatic matching and placement from ready, accessible sounds explicitly linked to this project.
direct_emotionbooleandefault true
Enables automatic emotion: a direct_emotion step adds provider delivery directions to spoken blocks that have none for their engine. Direction text sent to the provider is billed (ElevenLabs v4 audio tags). For pre-run estimates, clients add about 18 ElevenLabs v4 tokens per untagged ElevenLabs v4 block while this is on; the charge is the tokens actually sent. Omitted means true.
target_scopeobject | null
Optional focused source-block scope. Null or omitted targets the selected sections. Focused requests must set both optional sound lanes to false.
2 child attributes
- kind"source_blocks"required
- blocksarray of objectrequired1–250 itemsunique
  Focused source blocks; block_id values must be unique.
  4 item attributes
  block_idstringrequireduuid
  base_block_versionintegerrequired≥ 1
  text_length_utf16integerrequired1–1000000
  text_hashstringrequiredpattern ^[0-9a-f]{64}$

Response 202

Durable project workflow accepted and first advancement attempted. Replaying the same client_mutation_id with the same request returns the same workflow. Fields below are inside data.

runobjectrequired
Durable Studio project workflow run.
21 child attributes
- idstringrequireduuid
  Workflow run ID.
- project_idstringrequireduuid
- requested_by_user_idstringrequireduuid
- payer_user_idstring | nullrequireduuid
  User billed for Create Audio work; null for prepare_sections workflows.
- workflow_kindstringrequired
  One ofprepare_sectionscreate_audio
- automation_profilestring | nullrequired
  Create Audio profile label from profile_snapshot.profile; null for prepare_sections.
  One ofquickbalanceddirected
- profile_snapshotobjectrequired
  Empty object for prepare_sections workflows; the frozen Create Audio options for create_audio workflows.
- statusstringrequired
  Workflow run status, recomputed from step statuses after every step transition. Non-terminal: queued (unfinished steps remain and none is active), running (at least one step is active), canceling (cancellation was requested and unfinished steps remain). Terminal (completed_at is set and the status no longer changes): completed (every step succeeded or was skipped), partially_completed (at least one failed or conflict step and at least one succeeded or skipped step), failed (failed or conflict steps and no succeeded or skipped step), cancelled (all steps finished after cancellation was requested).
  One ofqueuedrunningcompletedpartially_completedfailedcancelingcancelled
- current_stagestring | nullrequired
  Stage of the next unfinished step while the run is queued, running, or canceling. Null once the run is terminal, or when the next unfinished step is render_section.
  One ofpreparing_sectionsassigning_speakerscasting_voicesplanning_emotiondirecting_deliveryplacing_project_soundsdirecting_sfxpreparing_voicesgenerating_audio
- step_countintegerrequired1–100
- completed_step_countintegerrequired0–100
  Steps in a terminal status (succeeded, skipped, failed, conflict, cancelled).
- progressobjectrequired
  Step counts by status. Currently contains integer counts pending, active, succeeded (succeeded or skipped), failed (failed or conflict), cancelled, completed (all terminal), and total; treat unknown keys as additive.
  7 child attributes
  pendinginteger≥ 0
  activeinteger≥ 0
  succeededinteger≥ 0
  failedinteger≥ 0
  cancelledinteger≥ 0
  completedinteger≥ 0
  totalinteger≥ 0
- error_summaryarray of objectrequiredmax 100 items
  One entry per failed or conflict step in step order. Entries currently contain step_id, section_id, step_kind, code, and message; treat unknown keys as additive.
  5 item attributes
  step_idstringuuid
  section_idstringuuid
  step_kindstring
  Kind of work a step performs. prepare_sections workflows contain only prepare_section steps. direct_section_delivery and render_section come from older Create Audio profiles (and successors resumed from them); new workflows do not plan them.
  One ofprepare_sectionassign_speakerscast_voicesdirect_emotiondirect_section_deliveryplace_project_soundsdirect_sfxprepare_voicesgenerate_stale_audiorender_section
  codestring | null
  messagestring | null
- cancel_requested_atstring | nullrequireddate-time
  When cancellation was first requested.
- cancel_acknowledged_atstring | nullrequireddate-time
  When the run reached cancelled.
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
- started_atstring | nullrequireddate-time
  When execution first started; null before then.
- completed_atstring | nullrequireddate-time
  Set when the run reaches a terminal status (completed, partially_completed, failed, cancelled); null otherwise.
- resumes_workflow_run_idstring | nullrequireduuid
  Predecessor run this run resumes; null for an original run.
- resumablebooleanrequired
  True when status is failed or partially_completed and at least one step is failed or conflict. Only resumable runs can be resumed.
stepsarray of objectrequired1–100 items
All steps in ascending step_index order.
19 item attributes
- idstringrequireduuid
- workflow_run_idstringrequireduuid
- section_idstringrequireduuid
- step_keystringrequired1–200 chars
  Stable key of the step within its workflow.
- step_indexintegerrequired0–99
  Zero-based position; steps are returned in ascending step_index order.
- step_kindstringrequired
  Kind of work a step performs. prepare_sections workflows contain only prepare_section steps. direct_section_delivery and render_section come from older Create Audio profiles (and successors resumed from them); new workflows do not plan them.
  One ofprepare_sectionassign_speakerscast_voicesdirect_emotiondirect_section_deliveryplace_project_soundsdirect_sfxprepare_voicesgenerate_stale_audiorender_section
- statusstringrequired
  Step status. pending and active are non-terminal; succeeded, skipped, failed, conflict, and cancelled are terminal. The run counts skipped as success and conflict as failure. conflict means the section document changed underneath the step.
  One ofpendingactivesucceededskippedfailedconflictcancelled
- requested_document_versionintegerrequired≥ 1
  Section document version the step was planned against.
- execution_document_versioninteger | nullrequired≥ 1
  Section document version the step executed against, when recorded.
- assistant_batch_idstring | nullrequireduuid
  Child assistant batch started by an assistant-driven step.
- render_run_idstring | nullrequireduuid
  Render run started by a render_section step.
- result_summaryobjectrequired
  Step-specific result data, typed by the contract as an open JSON object. generate_stale_audio steps may carry the StudioWorkflowAudioResultSummary fields; steps cancelled before starting carry cancelled_before_start: true.
- issue_kindstring | nullrequired
  Set for failed and conflict steps; null for every other status.
  One ofdocument_changedservice_out_of_syncassistant_failedworkflow_failed
- error_codestring | nullrequired1–200 chars
- error_messagestring | nullrequiredmax 10000 chars
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
- started_atstring | nullrequireddate-time
- completed_atstring | nullrequireddate-time

Errors 400, 401, 403, 404, 409, 500, 503 use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/workflows" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": 1,
  "workflow_kind": "prepare_sections",
  "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
  "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
  "section_ids": [
    "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30"
  ]
}'

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/workflows`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schema_version": 1,
    "workflow_kind": "prepare_sections",
    "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "section_ids": [
      "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30"
    ]
  }),
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/workflows",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={
      "schema_version": 1,
      "workflow_kind": "prepare_sections",
      "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "section_ids": [
        "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30"
      ]
    },
)
payload = response.json()

Response 202 (example)

{
  "data": {
    "run": {
      "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "requested_by_user_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "payer_user_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "workflow_kind": "prepare_sections",
      "automation_profile": "quick",
      "profile_snapshot": {},
      "status": "queued",
      "current_stage": "preparing_sections",
      "step_count": 1,
      "completed_step_count": 1,
      "progress": {
        "pending": 1,
        "active": 1,
        "succeeded": 1,
        "failed": 1,
        "cancelled": 1,
        "completed": 1,
        "total": 1
      },
      "error_summary": [
        {
          "step_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
          "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
          "step_kind": "prepare_section",
          "code": "string",
          "message": "string"
        }
      ],
      "cancel_requested_at": "2026-09-30T17:00:00.000Z",
      "cancel_acknowledged_at": "2026-09-30T17:00:00.000Z",
      "created_at": "2026-09-30T17:00:00.000Z",
      "updated_at": "2026-09-30T17:00:00.000Z",
      "started_at": "2026-09-30T17:00:00.000Z",
      "completed_at": "2026-09-30T17:00:00.000Z",
      "resumes_workflow_run_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "resumable": true
    },
    "steps": [
      {
        "id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "workflow_run_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
        "step_key": "string",
        "step_index": 1,
        "step_kind": "prepare_section",
        "status": "pending",
        "requested_document_version": 1,
        "execution_document_version": 1,
        "assistant_batch_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
        "render_run_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "result_summary": {},
        "issue_kind": "document_changed",
        "error_code": "string",
        "error_message": "string",
        "created_at": "2026-09-30T17:00:00.000Z",
        "updated_at": "2026-09-30T17:00:00.000Z",
        "started_at": "2026-09-30T17:00:00.000Z",
        "completed_at": "2026-09-30T17:00:00.000Z"
      }
    ]
  },
  "request_id": "req_01J9Z3K8QF4"
}

Get the latest project workflow

GET/studio/projects/{projectId}/workflows

Scope studio:read

Returns the project's most recent workflow with its steps, or null if none has run. Pass section_id to get the most recent workflow that includes that section.

Path parameters

projectIdstringrequireduuid

Query parameters

section_idstringuuid
Restrict to the workflow that most recently added a step for this section. Returns null when none exists or that workflow belongs to another project.

Response 200

Latest project workflow or null when none exists. Fields below are inside data.

runobjectrequired
Durable Studio project workflow run.
21 child attributes
- idstringrequireduuid
  Workflow run ID.
- project_idstringrequireduuid
- requested_by_user_idstringrequireduuid
- payer_user_idstring | nullrequireduuid
  User billed for Create Audio work; null for prepare_sections workflows.
- workflow_kindstringrequired
  One ofprepare_sectionscreate_audio
- automation_profilestring | nullrequired
  Create Audio profile label from profile_snapshot.profile; null for prepare_sections.
  One ofquickbalanceddirected
- profile_snapshotobjectrequired
  Empty object for prepare_sections workflows; the frozen Create Audio options for create_audio workflows.
- statusstringrequired
  Workflow run status, recomputed from step statuses after every step transition. Non-terminal: queued (unfinished steps remain and none is active), running (at least one step is active), canceling (cancellation was requested and unfinished steps remain). Terminal (completed_at is set and the status no longer changes): completed (every step succeeded or was skipped), partially_completed (at least one failed or conflict step and at least one succeeded or skipped step), failed (failed or conflict steps and no succeeded or skipped step), cancelled (all steps finished after cancellation was requested).
  One ofqueuedrunningcompletedpartially_completedfailedcancelingcancelled
- current_stagestring | nullrequired
  Stage of the next unfinished step while the run is queued, running, or canceling. Null once the run is terminal, or when the next unfinished step is render_section.
  One ofpreparing_sectionsassigning_speakerscasting_voicesplanning_emotiondirecting_deliveryplacing_project_soundsdirecting_sfxpreparing_voicesgenerating_audio
- step_countintegerrequired1–100
- completed_step_countintegerrequired0–100
  Steps in a terminal status (succeeded, skipped, failed, conflict, cancelled).
- progressobjectrequired
  Step counts by status. Currently contains integer counts pending, active, succeeded (succeeded or skipped), failed (failed or conflict), cancelled, completed (all terminal), and total; treat unknown keys as additive.
  7 child attributes
  pendinginteger≥ 0
  activeinteger≥ 0
  succeededinteger≥ 0
  failedinteger≥ 0
  cancelledinteger≥ 0
  completedinteger≥ 0
  totalinteger≥ 0
- error_summaryarray of objectrequiredmax 100 items
  One entry per failed or conflict step in step order. Entries currently contain step_id, section_id, step_kind, code, and message; treat unknown keys as additive.
  5 item attributes
  step_idstringuuid
  section_idstringuuid
  step_kindstring
  Kind of work a step performs. prepare_sections workflows contain only prepare_section steps. direct_section_delivery and render_section come from older Create Audio profiles (and successors resumed from them); new workflows do not plan them.
  One ofprepare_sectionassign_speakerscast_voicesdirect_emotiondirect_section_deliveryplace_project_soundsdirect_sfxprepare_voicesgenerate_stale_audiorender_section
  codestring | null
  messagestring | null
- cancel_requested_atstring | nullrequireddate-time
  When cancellation was first requested.
- cancel_acknowledged_atstring | nullrequireddate-time
  When the run reached cancelled.
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
- started_atstring | nullrequireddate-time
  When execution first started; null before then.
- completed_atstring | nullrequireddate-time
  Set when the run reaches a terminal status (completed, partially_completed, failed, cancelled); null otherwise.
- resumes_workflow_run_idstring | nullrequireduuid
  Predecessor run this run resumes; null for an original run.
- resumablebooleanrequired
  True when status is failed or partially_completed and at least one step is failed or conflict. Only resumable runs can be resumed.
stepsarray of objectrequired1–100 items
All steps in ascending step_index order.
19 item attributes
- idstringrequireduuid
- workflow_run_idstringrequireduuid
- section_idstringrequireduuid
- step_keystringrequired1–200 chars
  Stable key of the step within its workflow.
- step_indexintegerrequired0–99
  Zero-based position; steps are returned in ascending step_index order.
- step_kindstringrequired
  Kind of work a step performs. prepare_sections workflows contain only prepare_section steps. direct_section_delivery and render_section come from older Create Audio profiles (and successors resumed from them); new workflows do not plan them.
  One ofprepare_sectionassign_speakerscast_voicesdirect_emotiondirect_section_deliveryplace_project_soundsdirect_sfxprepare_voicesgenerate_stale_audiorender_section
- statusstringrequired
  Step status. pending and active are non-terminal; succeeded, skipped, failed, conflict, and cancelled are terminal. The run counts skipped as success and conflict as failure. conflict means the section document changed underneath the step.
  One ofpendingactivesucceededskippedfailedconflictcancelled
- requested_document_versionintegerrequired≥ 1
  Section document version the step was planned against.
- execution_document_versioninteger | nullrequired≥ 1
  Section document version the step executed against, when recorded.
- assistant_batch_idstring | nullrequireduuid
  Child assistant batch started by an assistant-driven step.
- render_run_idstring | nullrequireduuid
  Render run started by a render_section step.
- result_summaryobjectrequired
  Step-specific result data, typed by the contract as an open JSON object. generate_stale_audio steps may carry the StudioWorkflowAudioResultSummary fields; steps cancelled before starting carry cancelled_before_start: true.
- issue_kindstring | nullrequired
  Set for failed and conflict steps; null for every other status.
  One ofdocument_changedservice_out_of_syncassistant_failedworkflow_failed
- error_codestring | nullrequired1–200 chars
- error_messagestring | nullrequiredmax 10000 chars
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
- started_atstring | nullrequireddate-time
- completed_atstring | nullrequireddate-time

Errors 400, 401, 403, 500, 503 use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/workflows" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/workflows`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/workflows",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "run": {
      "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "requested_by_user_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "payer_user_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "workflow_kind": "prepare_sections",
      "automation_profile": "quick",
      "profile_snapshot": {},
      "status": "queued",
      "current_stage": "preparing_sections",
      "step_count": 1,
      "completed_step_count": 1,
      "progress": {
        "pending": 1,
        "active": 1,
        "succeeded": 1,
        "failed": 1,
        "cancelled": 1,
        "completed": 1,
        "total": 1
      },
      "error_summary": [
        {
          "step_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
          "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
          "step_kind": "prepare_section",
          "code": "string",
          "message": "string"
        }
      ],
      "cancel_requested_at": "2026-09-30T17:00:00.000Z",
      "cancel_acknowledged_at": "2026-09-30T17:00:00.000Z",
      "created_at": "2026-09-30T17:00:00.000Z",
      "updated_at": "2026-09-30T17:00:00.000Z",
      "started_at": "2026-09-30T17:00:00.000Z",
      "completed_at": "2026-09-30T17:00:00.000Z",
      "resumes_workflow_run_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "resumable": true
    },
    "steps": [
      {
        "id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "workflow_run_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
        "step_key": "string",
        "step_index": 1,
        "step_kind": "prepare_section",
        "status": "pending",
        "requested_document_version": 1,
        "execution_document_version": 1,
        "assistant_batch_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
        "render_run_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "result_summary": {},
        "issue_kind": "document_changed",
        "error_code": "string",
        "error_message": "string",
        "created_at": "2026-09-30T17:00:00.000Z",
        "updated_at": "2026-09-30T17:00:00.000Z",
        "started_at": "2026-09-30T17:00:00.000Z",
        "completed_at": "2026-09-30T17:00:00.000Z"
      }
    ]
  },
  "request_id": "req_01J9Z3K8QF4"
}

Get a workflow

GET/studio/workflows/{workflowRunId}

Scope studio:read

Returns data: { run, steps } with a workflow run and its ordered steps, the same payload shape as workflow creation and resume. Poll this endpoint until data.run.status is completed, partially_completed, failed, or cancelled. For each section's current per-block audio freshness, activity, errors, and playback URLs, read GET /studio/sections/{sectionId}/media and join by block_id; generation eligibility is a separate check.

Path parameters

workflowRunIdstringrequireduuid

Response 200

Current workflow and ordered section steps. Poll until run.status is terminal (completed, partially_completed, failed, cancelled). Fields below are inside data.

runobjectrequired
Durable Studio project workflow run.
21 child attributes
- idstringrequireduuid
  Workflow run ID.
- project_idstringrequireduuid
- requested_by_user_idstringrequireduuid
- payer_user_idstring | nullrequireduuid
  User billed for Create Audio work; null for prepare_sections workflows.
- workflow_kindstringrequired
  One ofprepare_sectionscreate_audio
- automation_profilestring | nullrequired
  Create Audio profile label from profile_snapshot.profile; null for prepare_sections.
  One ofquickbalanceddirected
- profile_snapshotobjectrequired
  Empty object for prepare_sections workflows; the frozen Create Audio options for create_audio workflows.
- statusstringrequired
  Workflow run status, recomputed from step statuses after every step transition. Non-terminal: queued (unfinished steps remain and none is active), running (at least one step is active), canceling (cancellation was requested and unfinished steps remain). Terminal (completed_at is set and the status no longer changes): completed (every step succeeded or was skipped), partially_completed (at least one failed or conflict step and at least one succeeded or skipped step), failed (failed or conflict steps and no succeeded or skipped step), cancelled (all steps finished after cancellation was requested).
  One ofqueuedrunningcompletedpartially_completedfailedcancelingcancelled
- current_stagestring | nullrequired
  Stage of the next unfinished step while the run is queued, running, or canceling. Null once the run is terminal, or when the next unfinished step is render_section.
  One ofpreparing_sectionsassigning_speakerscasting_voicesplanning_emotiondirecting_deliveryplacing_project_soundsdirecting_sfxpreparing_voicesgenerating_audio
- step_countintegerrequired1–100
- completed_step_countintegerrequired0–100
  Steps in a terminal status (succeeded, skipped, failed, conflict, cancelled).
- progressobjectrequired
  Step counts by status. Currently contains integer counts pending, active, succeeded (succeeded or skipped), failed (failed or conflict), cancelled, completed (all terminal), and total; treat unknown keys as additive.
  7 child attributes
  pendinginteger≥ 0
  activeinteger≥ 0
  succeededinteger≥ 0
  failedinteger≥ 0
  cancelledinteger≥ 0
  completedinteger≥ 0
  totalinteger≥ 0
- error_summaryarray of objectrequiredmax 100 items
  One entry per failed or conflict step in step order. Entries currently contain step_id, section_id, step_kind, code, and message; treat unknown keys as additive.
  5 item attributes
  step_idstringuuid
  section_idstringuuid
  step_kindstring
  Kind of work a step performs. prepare_sections workflows contain only prepare_section steps. direct_section_delivery and render_section come from older Create Audio profiles (and successors resumed from them); new workflows do not plan them.
  One ofprepare_sectionassign_speakerscast_voicesdirect_emotiondirect_section_deliveryplace_project_soundsdirect_sfxprepare_voicesgenerate_stale_audiorender_section
  codestring | null
  messagestring | null
- cancel_requested_atstring | nullrequireddate-time
  When cancellation was first requested.
- cancel_acknowledged_atstring | nullrequireddate-time
  When the run reached cancelled.
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
- started_atstring | nullrequireddate-time
  When execution first started; null before then.
- completed_atstring | nullrequireddate-time
  Set when the run reaches a terminal status (completed, partially_completed, failed, cancelled); null otherwise.
- resumes_workflow_run_idstring | nullrequireduuid
  Predecessor run this run resumes; null for an original run.
- resumablebooleanrequired
  True when status is failed or partially_completed and at least one step is failed or conflict. Only resumable runs can be resumed.
stepsarray of objectrequired1–100 items
All steps in ascending step_index order.
19 item attributes
- idstringrequireduuid
- workflow_run_idstringrequireduuid
- section_idstringrequireduuid
- step_keystringrequired1–200 chars
  Stable key of the step within its workflow.
- step_indexintegerrequired0–99
  Zero-based position; steps are returned in ascending step_index order.
- step_kindstringrequired
  Kind of work a step performs. prepare_sections workflows contain only prepare_section steps. direct_section_delivery and render_section come from older Create Audio profiles (and successors resumed from them); new workflows do not plan them.
  One ofprepare_sectionassign_speakerscast_voicesdirect_emotiondirect_section_deliveryplace_project_soundsdirect_sfxprepare_voicesgenerate_stale_audiorender_section
- statusstringrequired
  Step status. pending and active are non-terminal; succeeded, skipped, failed, conflict, and cancelled are terminal. The run counts skipped as success and conflict as failure. conflict means the section document changed underneath the step.
  One ofpendingactivesucceededskippedfailedconflictcancelled
- requested_document_versionintegerrequired≥ 1
  Section document version the step was planned against.
- execution_document_versioninteger | nullrequired≥ 1
  Section document version the step executed against, when recorded.
- assistant_batch_idstring | nullrequireduuid
  Child assistant batch started by an assistant-driven step.
- render_run_idstring | nullrequireduuid
  Render run started by a render_section step.
- result_summaryobjectrequired
  Step-specific result data, typed by the contract as an open JSON object. generate_stale_audio steps may carry the StudioWorkflowAudioResultSummary fields; steps cancelled before starting carry cancelled_before_start: true.
- issue_kindstring | nullrequired
  Set for failed and conflict steps; null for every other status.
  One ofdocument_changedservice_out_of_syncassistant_failedworkflow_failed
- error_codestring | nullrequired1–200 chars
- error_messagestring | nullrequiredmax 10000 chars
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
- started_atstring | nullrequireddate-time
- completed_atstring | nullrequireddate-time

Errors 400, 401, 403, 404, 500, 503 use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/workflows/$WORKFLOW_RUN_ID" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const workflowRunId = "<workflowRunId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/workflows/${workflowRunId}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

workflow_run_id = "<workflowRunId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/workflows/{workflow_run_id}",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "run": {
      "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "requested_by_user_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "payer_user_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "workflow_kind": "prepare_sections",
      "automation_profile": "quick",
      "profile_snapshot": {},
      "status": "queued",
      "current_stage": "preparing_sections",
      "step_count": 1,
      "completed_step_count": 1,
      "progress": {
        "pending": 1,
        "active": 1,
        "succeeded": 1,
        "failed": 1,
        "cancelled": 1,
        "completed": 1,
        "total": 1
      },
      "error_summary": [
        {
          "step_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
          "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
          "step_kind": "prepare_section",
          "code": "string",
          "message": "string"
        }
      ],
      "cancel_requested_at": "2026-09-30T17:00:00.000Z",
      "cancel_acknowledged_at": "2026-09-30T17:00:00.000Z",
      "created_at": "2026-09-30T17:00:00.000Z",
      "updated_at": "2026-09-30T17:00:00.000Z",
      "started_at": "2026-09-30T17:00:00.000Z",
      "completed_at": "2026-09-30T17:00:00.000Z",
      "resumes_workflow_run_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "resumable": true
    },
    "steps": [
      {
        "id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "workflow_run_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
        "step_key": "string",
        "step_index": 1,
        "step_kind": "prepare_section",
        "status": "pending",
        "requested_document_version": 1,
        "execution_document_version": 1,
        "assistant_batch_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
        "render_run_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "result_summary": {},
        "issue_kind": "document_changed",
        "error_code": "string",
        "error_message": "string",
        "created_at": "2026-09-30T17:00:00.000Z",
        "updated_at": "2026-09-30T17:00:00.000Z",
        "started_at": "2026-09-30T17:00:00.000Z",
        "completed_at": "2026-09-30T17:00:00.000Z"
      }
    ]
  },
  "request_id": "req_01J9Z3K8QF4"
}

Get workflow audio progress

GET/studio/workflows/{workflowRunId}/progress

Scope studio:read

Returns ready/total audio clip counts. The default schema_version=1 response is unchanged. Request ?schema_version=2 for failed-block issues with section_id, stable block_id, legacy one-based block_number, and zero-based block_index in the full document order captured when the issue was recorded. Use IDs to locate blocks after edits, not old indexes or text-chunk counters. Inspect each block's current freshness, activity, errors, and playback URL through GET /studio/sections/{sectionId}/media; generation-availability does not report current audio.

Path parameters

workflowRunIdstringrequireduuid

Query parameters

schema_versionintegerdefault 1
1 (default) returns counts only. 2 adds failed-block issues using stable IDs and captured-document zero-based indexes.
One of12

Response 200

Current workflow audio counts. Fields below are inside data.

One of 2 shapes:

schema_version: 1

schema_version1required
workflow_run_idstringrequireduuid
readyintegerrequired≥ 0
totalintegerrequired≥ 0

schema_version: 2

schema_version2required
workflow_run_idstringrequireduuid
readyintegerrequired≥ 0
totalintegerrequired≥ 0
block_issuesarray of objectrequiredmax 2000 items
8 item attributes
- block_idstringrequireduuid
- block_numberintegerrequired1–50000
- block_kindstringrequired
  One ofspeechnarrationsfxunparsedexcluded
- speaker_namestring | nullrequired1–200 chars
- reasonstringrequired1–1000 chars
- recoverystringrequired1–1000 chars
- section_idstringrequireduuid
- block_indexintegerrequired0–49999
  Zero-based position in the full document order captured when the issue was recorded. Join current resources using block_id, not an index after edits.

Errors 400, 401, 403, 404, 500 use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/workflows/$WORKFLOW_RUN_ID/progress" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const workflowRunId = "<workflowRunId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/workflows/${workflowRunId}/progress`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

workflow_run_id = "<workflowRunId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/workflows/{workflow_run_id}/progress",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "workflow_run_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "ready": 1,
    "total": 1
  },
  "request_id": "req_01J9Z3K8QF4"
}

Cancel a workflow

POST/studio/workflows/{workflowRunId}/cancel

Scope studio:write

Requests cancellation of a prepare or Create Audio workflow. Pending steps are cancelled immediately; running steps stop cooperatively and their late results are discarded. A finished workflow is returned unchanged. Send no request body.

Path parameters

workflowRunIdstringrequireduuid

Response 200

Current workflow state, normally canceling or cancelled. Fields below are inside data.

runobjectrequired
Durable Studio project workflow run.
21 child attributes
- idstringrequireduuid
  Workflow run ID.
- project_idstringrequireduuid
- requested_by_user_idstringrequireduuid
- payer_user_idstring | nullrequireduuid
  User billed for Create Audio work; null for prepare_sections workflows.
- workflow_kindstringrequired
  One ofprepare_sectionscreate_audio
- automation_profilestring | nullrequired
  Create Audio profile label from profile_snapshot.profile; null for prepare_sections.
  One ofquickbalanceddirected
- profile_snapshotobjectrequired
  Empty object for prepare_sections workflows; the frozen Create Audio options for create_audio workflows.
- statusstringrequired
  Workflow run status, recomputed from step statuses after every step transition. Non-terminal: queued (unfinished steps remain and none is active), running (at least one step is active), canceling (cancellation was requested and unfinished steps remain). Terminal (completed_at is set and the status no longer changes): completed (every step succeeded or was skipped), partially_completed (at least one failed or conflict step and at least one succeeded or skipped step), failed (failed or conflict steps and no succeeded or skipped step), cancelled (all steps finished after cancellation was requested).
  One ofqueuedrunningcompletedpartially_completedfailedcancelingcancelled
- current_stagestring | nullrequired
  Stage of the next unfinished step while the run is queued, running, or canceling. Null once the run is terminal, or when the next unfinished step is render_section.
  One ofpreparing_sectionsassigning_speakerscasting_voicesplanning_emotiondirecting_deliveryplacing_project_soundsdirecting_sfxpreparing_voicesgenerating_audio
- step_countintegerrequired1–100
- completed_step_countintegerrequired0–100
  Steps in a terminal status (succeeded, skipped, failed, conflict, cancelled).
- progressobjectrequired
  Step counts by status. Currently contains integer counts pending, active, succeeded (succeeded or skipped), failed (failed or conflict), cancelled, completed (all terminal), and total; treat unknown keys as additive.
  7 child attributes
  pendinginteger≥ 0
  activeinteger≥ 0
  succeededinteger≥ 0
  failedinteger≥ 0
  cancelledinteger≥ 0
  completedinteger≥ 0
  totalinteger≥ 0
- error_summaryarray of objectrequiredmax 100 items
  One entry per failed or conflict step in step order. Entries currently contain step_id, section_id, step_kind, code, and message; treat unknown keys as additive.
  5 item attributes
  step_idstringuuid
  section_idstringuuid
  step_kindstring
  Kind of work a step performs. prepare_sections workflows contain only prepare_section steps. direct_section_delivery and render_section come from older Create Audio profiles (and successors resumed from them); new workflows do not plan them.
  One ofprepare_sectionassign_speakerscast_voicesdirect_emotiondirect_section_deliveryplace_project_soundsdirect_sfxprepare_voicesgenerate_stale_audiorender_section
  codestring | null
  messagestring | null
- cancel_requested_atstring | nullrequireddate-time
  When cancellation was first requested.
- cancel_acknowledged_atstring | nullrequireddate-time
  When the run reached cancelled.
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
- started_atstring | nullrequireddate-time
  When execution first started; null before then.
- completed_atstring | nullrequireddate-time
  Set when the run reaches a terminal status (completed, partially_completed, failed, cancelled); null otherwise.
- resumes_workflow_run_idstring | nullrequireduuid
  Predecessor run this run resumes; null for an original run.
- resumablebooleanrequired
  True when status is failed or partially_completed and at least one step is failed or conflict. Only resumable runs can be resumed.
stepsarray of objectrequired1–100 items
All steps in ascending step_index order.
19 item attributes
- idstringrequireduuid
- workflow_run_idstringrequireduuid
- section_idstringrequireduuid
- step_keystringrequired1–200 chars
  Stable key of the step within its workflow.
- step_indexintegerrequired0–99
  Zero-based position; steps are returned in ascending step_index order.
- step_kindstringrequired
  Kind of work a step performs. prepare_sections workflows contain only prepare_section steps. direct_section_delivery and render_section come from older Create Audio profiles (and successors resumed from them); new workflows do not plan them.
  One ofprepare_sectionassign_speakerscast_voicesdirect_emotiondirect_section_deliveryplace_project_soundsdirect_sfxprepare_voicesgenerate_stale_audiorender_section
- statusstringrequired
  Step status. pending and active are non-terminal; succeeded, skipped, failed, conflict, and cancelled are terminal. The run counts skipped as success and conflict as failure. conflict means the section document changed underneath the step.
  One ofpendingactivesucceededskippedfailedconflictcancelled
- requested_document_versionintegerrequired≥ 1
  Section document version the step was planned against.
- execution_document_versioninteger | nullrequired≥ 1
  Section document version the step executed against, when recorded.
- assistant_batch_idstring | nullrequireduuid
  Child assistant batch started by an assistant-driven step.
- render_run_idstring | nullrequireduuid
  Render run started by a render_section step.
- result_summaryobjectrequired
  Step-specific result data, typed by the contract as an open JSON object. generate_stale_audio steps may carry the StudioWorkflowAudioResultSummary fields; steps cancelled before starting carry cancelled_before_start: true.
- issue_kindstring | nullrequired
  Set for failed and conflict steps; null for every other status.
  One ofdocument_changedservice_out_of_syncassistant_failedworkflow_failed
- error_codestring | nullrequired1–200 chars
- error_messagestring | nullrequiredmax 10000 chars
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
- started_atstring | nullrequireddate-time
- completed_atstring | nullrequireddate-time

Errors 400, 401, 403, 404, 409, 500, 503 use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/workflows/$WORKFLOW_RUN_ID/cancel" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const workflowRunId = "<workflowRunId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/workflows/${workflowRunId}/cancel`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

workflow_run_id = "<workflowRunId>"
response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/workflows/{workflow_run_id}/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "run": {
      "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "requested_by_user_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "payer_user_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "workflow_kind": "prepare_sections",
      "automation_profile": "quick",
      "profile_snapshot": {},
      "status": "queued",
      "current_stage": "preparing_sections",
      "step_count": 1,
      "completed_step_count": 1,
      "progress": {
        "pending": 1,
        "active": 1,
        "succeeded": 1,
        "failed": 1,
        "cancelled": 1,
        "completed": 1,
        "total": 1
      },
      "error_summary": [
        {
          "step_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
          "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
          "step_kind": "prepare_section",
          "code": "string",
          "message": "string"
        }
      ],
      "cancel_requested_at": "2026-09-30T17:00:00.000Z",
      "cancel_acknowledged_at": "2026-09-30T17:00:00.000Z",
      "created_at": "2026-09-30T17:00:00.000Z",
      "updated_at": "2026-09-30T17:00:00.000Z",
      "started_at": "2026-09-30T17:00:00.000Z",
      "completed_at": "2026-09-30T17:00:00.000Z",
      "resumes_workflow_run_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "resumable": true
    },
    "steps": [
      {
        "id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "workflow_run_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
        "step_key": "string",
        "step_index": 1,
        "step_kind": "prepare_section",
        "status": "pending",
        "requested_document_version": 1,
        "execution_document_version": 1,
        "assistant_batch_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
        "render_run_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "result_summary": {},
        "issue_kind": "document_changed",
        "error_code": "string",
        "error_message": "string",
        "created_at": "2026-09-30T17:00:00.000Z",
        "updated_at": "2026-09-30T17:00:00.000Z",
        "started_at": "2026-09-30T17:00:00.000Z",
        "completed_at": "2026-09-30T17:00:00.000Z"
      }
    ]
  },
  "request_id": "req_01J9Z3K8QF4"
}

Resume a failed workflow

POST/studio/workflows/{workflowRunId}/resume

Scope studio:writeRetry with the same client_mutation_id

Starts a new workflow linked to a failed or partially completed run and returns 202 with data: { run, steps }, the same shape as creation and polling. It picks up from each section's first failed stage instead of redoing finished work. Only runs with resumable: true can be resumed. If recovery returns a retryable error, retry the same body and client_mutation_id to preserve the original recovery request.

Path parameters

workflowRunIdstringrequireduuid

Request body application/json

schema_version1required
actor_session_idstringrequireduuid
Client session that issued the request.
client_mutation_idstringrequireduuid
Idempotency key; the successor workflow ID is derived from it. Reusing it for different content returns 409.

Response 202

The linked successor workflow and its recovery steps. Fields below are inside data.

runobjectrequired
Durable Studio project workflow run.
21 child attributes
- idstringrequireduuid
  Workflow run ID.
- project_idstringrequireduuid
- requested_by_user_idstringrequireduuid
- payer_user_idstring | nullrequireduuid
  User billed for Create Audio work; null for prepare_sections workflows.
- workflow_kindstringrequired
  One ofprepare_sectionscreate_audio
- automation_profilestring | nullrequired
  Create Audio profile label from profile_snapshot.profile; null for prepare_sections.
  One ofquickbalanceddirected
- profile_snapshotobjectrequired
  Empty object for prepare_sections workflows; the frozen Create Audio options for create_audio workflows.
- statusstringrequired
  Workflow run status, recomputed from step statuses after every step transition. Non-terminal: queued (unfinished steps remain and none is active), running (at least one step is active), canceling (cancellation was requested and unfinished steps remain). Terminal (completed_at is set and the status no longer changes): completed (every step succeeded or was skipped), partially_completed (at least one failed or conflict step and at least one succeeded or skipped step), failed (failed or conflict steps and no succeeded or skipped step), cancelled (all steps finished after cancellation was requested).
  One ofqueuedrunningcompletedpartially_completedfailedcancelingcancelled
- current_stagestring | nullrequired
  Stage of the next unfinished step while the run is queued, running, or canceling. Null once the run is terminal, or when the next unfinished step is render_section.
  One ofpreparing_sectionsassigning_speakerscasting_voicesplanning_emotiondirecting_deliveryplacing_project_soundsdirecting_sfxpreparing_voicesgenerating_audio
- step_countintegerrequired1–100
- completed_step_countintegerrequired0–100
  Steps in a terminal status (succeeded, skipped, failed, conflict, cancelled).
- progressobjectrequired
  Step counts by status. Currently contains integer counts pending, active, succeeded (succeeded or skipped), failed (failed or conflict), cancelled, completed (all terminal), and total; treat unknown keys as additive.
  7 child attributes
  pendinginteger≥ 0
  activeinteger≥ 0
  succeededinteger≥ 0
  failedinteger≥ 0
  cancelledinteger≥ 0
  completedinteger≥ 0
  totalinteger≥ 0
- error_summaryarray of objectrequiredmax 100 items
  One entry per failed or conflict step in step order. Entries currently contain step_id, section_id, step_kind, code, and message; treat unknown keys as additive.
  5 item attributes
  step_idstringuuid
  section_idstringuuid
  step_kindstring
  Kind of work a step performs. prepare_sections workflows contain only prepare_section steps. direct_section_delivery and render_section come from older Create Audio profiles (and successors resumed from them); new workflows do not plan them.
  One ofprepare_sectionassign_speakerscast_voicesdirect_emotiondirect_section_deliveryplace_project_soundsdirect_sfxprepare_voicesgenerate_stale_audiorender_section
  codestring | null
  messagestring | null
- cancel_requested_atstring | nullrequireddate-time
  When cancellation was first requested.
- cancel_acknowledged_atstring | nullrequireddate-time
  When the run reached cancelled.
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
- started_atstring | nullrequireddate-time
  When execution first started; null before then.
- completed_atstring | nullrequireddate-time
  Set when the run reaches a terminal status (completed, partially_completed, failed, cancelled); null otherwise.
- resumes_workflow_run_idstring | nullrequireduuid
  Predecessor run this run resumes; null for an original run.
- resumablebooleanrequired
  True when status is failed or partially_completed and at least one step is failed or conflict. Only resumable runs can be resumed.
stepsarray of objectrequired1–100 items
All steps in ascending step_index order.
19 item attributes
- idstringrequireduuid
- workflow_run_idstringrequireduuid
- section_idstringrequireduuid
- step_keystringrequired1–200 chars
  Stable key of the step within its workflow.
- step_indexintegerrequired0–99
  Zero-based position; steps are returned in ascending step_index order.
- step_kindstringrequired
  Kind of work a step performs. prepare_sections workflows contain only prepare_section steps. direct_section_delivery and render_section come from older Create Audio profiles (and successors resumed from them); new workflows do not plan them.
  One ofprepare_sectionassign_speakerscast_voicesdirect_emotiondirect_section_deliveryplace_project_soundsdirect_sfxprepare_voicesgenerate_stale_audiorender_section
- statusstringrequired
  Step status. pending and active are non-terminal; succeeded, skipped, failed, conflict, and cancelled are terminal. The run counts skipped as success and conflict as failure. conflict means the section document changed underneath the step.
  One ofpendingactivesucceededskippedfailedconflictcancelled
- requested_document_versionintegerrequired≥ 1
  Section document version the step was planned against.
- execution_document_versioninteger | nullrequired≥ 1
  Section document version the step executed against, when recorded.
- assistant_batch_idstring | nullrequireduuid
  Child assistant batch started by an assistant-driven step.
- render_run_idstring | nullrequireduuid
  Render run started by a render_section step.
- result_summaryobjectrequired
  Step-specific result data, typed by the contract as an open JSON object. generate_stale_audio steps may carry the StudioWorkflowAudioResultSummary fields; steps cancelled before starting carry cancelled_before_start: true.
- issue_kindstring | nullrequired
  Set for failed and conflict steps; null for every other status.
  One ofdocument_changedservice_out_of_syncassistant_failedworkflow_failed
- error_codestring | nullrequired1–200 chars
- error_messagestring | nullrequiredmax 10000 chars
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
- started_atstring | nullrequireddate-time
- completed_atstring | nullrequireddate-time

Errors 400, 401, 403, 404, 409, 500, 503 use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/workflows/$WORKFLOW_RUN_ID/resume" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": 1,
  "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
  "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20"
}'

const workflowRunId = "<workflowRunId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/workflows/${workflowRunId}/resume`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schema_version": 1,
    "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20"
  }),
});
const { data, error, request_id } = await response.json();

import os
import requests

workflow_run_id = "<workflowRunId>"
response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/workflows/{workflow_run_id}/resume",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={
      "schema_version": 1,
      "actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20"
    },
)
payload = response.json()

Response 202 (example)

{
  "data": {
    "run": {
      "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "requested_by_user_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "payer_user_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "workflow_kind": "prepare_sections",
      "automation_profile": "quick",
      "profile_snapshot": {},
      "status": "queued",
      "current_stage": "preparing_sections",
      "step_count": 1,
      "completed_step_count": 1,
      "progress": {
        "pending": 1,
        "active": 1,
        "succeeded": 1,
        "failed": 1,
        "cancelled": 1,
        "completed": 1,
        "total": 1
      },
      "error_summary": [
        {
          "step_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
          "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
          "step_kind": "prepare_section",
          "code": "string",
          "message": "string"
        }
      ],
      "cancel_requested_at": "2026-09-30T17:00:00.000Z",
      "cancel_acknowledged_at": "2026-09-30T17:00:00.000Z",
      "created_at": "2026-09-30T17:00:00.000Z",
      "updated_at": "2026-09-30T17:00:00.000Z",
      "started_at": "2026-09-30T17:00:00.000Z",
      "completed_at": "2026-09-30T17:00:00.000Z",
      "resumes_workflow_run_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "resumable": true
    },
    "steps": [
      {
        "id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "workflow_run_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
        "step_key": "string",
        "step_index": 1,
        "step_kind": "prepare_section",
        "status": "pending",
        "requested_document_version": 1,
        "execution_document_version": 1,
        "assistant_batch_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
        "render_run_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "result_summary": {},
        "issue_kind": "document_changed",
        "error_code": "string",
        "error_message": "string",
        "created_at": "2026-09-30T17:00:00.000Z",
        "updated_at": "2026-09-30T17:00:00.000Z",
        "started_at": "2026-09-30T17:00:00.000Z",
        "completed_at": "2026-09-30T17:00:00.000Z"
      }
    ]
  },
  "request_id": "req_01J9Z3K8QF4"
}