MCP / Tools / Shot / Media / Export / media_generate

media_generate

orchestrationbetaauth: media:writeapproval: suggeststatus: v1

Generate music, speech, dialogue, sound effects, or shot-scoped scene audio.

When to use

Use for non-visual media generation workflows.
Use `workflow=scene_audio` for Seed Audio shot/scene mixes that may include dialogue, ambience, Foley, and selected voice references.
`phase=start` returns an async `job_id`: poll `job_get(job_id, include_result=true)` until it completes. BeatBandit stores the audio asset and settles credits automatically when the job completes, so `phase=finalize` is optional and only works on a completed job.

When not to use

Do not use for still images or videos.
Do not use to upload or attach reusable voice samples; use `asset_upload(target_type=reference_audio_asset)` and `voice_profile`.
Do not call `phase=start` again while a returned `job_id` is still pending or processing; poll `job_get` instead.

Examples

“Generate suspense music for this scene.”
“Generate 30 seconds of shot audio for shot 101 with Mira's selected voice reference.”

Anti-examples

Generate a storyboard image.
Attach an existing voice sample to a character profile.

Workflows

Switch behavior by setting the workflow input field.

Workflow	Phases	Calls
`music`	readiness, start, finalize	`media.generate`
`speech`	readiness, start, finalize	`media.generate`
`dialogue`	readiness, start, finalize	`media.generate`
`sound_effect`	readiness, start, finalize	`media.generate`
`scene_audio`	readiness, start, finalize	`media.generate`

Input schema

media_generate input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "workflow",
    "phase",
    "project_id"
  ],
  "properties": {
    "workflow": {
      "type": "string",
      "enum": [
        "music",
        "speech",
        "dialogue",
        "sound_effect",
        "scene_audio"
      ]
    },
    "phase": {
      "type": "string",
      "enum": [
        "readiness",
        "start",
        "finalize"
      ]
    },
    "project_id": {
      "type": "integer"
    },
    "job_id": {
      "type": "string",
      "minLength": 1
    },
    "payload": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "minLength": 1,
          "description": "Selected media model id from readiness; required for start."
        }
      },
      "additionalProperties": true
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "phase": {
            "const": "start"
          }
        }
      },
      "then": {
        "required": [
          "payload"
        ],
        "properties": {
          "payload": {
            "required": [
              "model_id"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "phase": {
            "const": "finalize"
          }
        }
      },
      "then": {
        "required": [
          "job_id"
        ]
      }
    }
  ],
  "additionalProperties": false
}

Output schema

media_generate output

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "resource_updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Generic updated_at value for read/propose outputs that need a round-trippable optimistic-concurrency timestamp."
    },
    "credits_charged": {
      "type": "integer",
      "minimum": 0,
      "description": "Credits charged for this capability call when credit_metered=true."
    },
    "credits_skipped_reason": {
      "type": "string",
      "description": "Present instead of credits_charged when the capability intentionally skipped billing (e.g. cache hit, no-op, failed_before_llm)."
    },
    "pipeline_state": {
      "$ref": "./_common/pipeline_state.schema.json"
    },
    "next_actions": {
      "type": "array",
      "items": {
        "$ref": "./_common/next_action.schema.json"
      }
    }
  },
  "additionalProperties": true
}