MCP / Tools / Shot / Media / Export / voice_profile

voice_profile

writebetaauth: project:writeapproval: suggeststatus: v1

List, create, update, archive, and attach reusable voice reference samples for Seed Audio workflows.

When to use

Use `operation=list` or `operation=get` to inspect available character/narrator voice profiles and selected voice samples.
Use `operation=add_reference` after `asset_upload(target_type=reference_audio_asset)` to attach a clean voice sample to a profile.
Use `operation=select_reference` to choose the active sample that should guide future voice generation.
Use `operation=archive` to retire a reusable voice profile without deleting its underlying media assets.

When not to use

Do not use for generated shot audio takes; use `media_generate(workflow=scene_audio)`.
Do not use for selecting which finished shot audio should feed video generation; use `shot_mutate(entity_type=shot_audio, operation=select)`.

Examples

“List reusable voice profiles for project 123.”
“Attach uploaded reference audio asset 456 to voice profile 12.”
“Select voice reference 78 for profile 12.”
“Archive voice profile 12 when it should no longer appear in default voice lists.”

Anti-examples

Generate a 20-second line of dialogue.
Use a shot audio take as the video reference.

Backend capabilities

voice_profile.manage

Linked resources

Tool calls may return resource_links pointing at these resource families.

media_catalog

Input schema

voice_profile input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "operation",
    "project_id"
  ],
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "list",
        "get",
        "create",
        "update",
        "archive",
        "add_reference",
        "select_reference"
      ]
    },
    "project_id": {
      "type": "integer"
    },
    "voice_profile_id": {
      "type": "integer",
      "description": "Required for get, update, archive, add_reference, and select_reference."
    },
    "reference_id": {
      "type": "integer",
      "description": "Required for select_reference."
    },
    "include_archived": {
      "type": "boolean",
      "default": false
    },
    "if_match_updated_at": {
      "type": "string"
    },
    "display_name": {
      "type": "string"
    },
    "profile_kind": {
      "type": "string",
      "enum": [
        "character",
        "narrator",
        "ambient_style",
        "other"
      ]
    },
    "character_card_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "shot_element_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "cue_aliases": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 20
    },
    "voice_description": {
      "type": [
        "string",
        "null"
      ]
    },
    "provider": {
      "type": [
        "string",
        "null"
      ]
    },
    "provider_voice": {
      "type": [
        "string",
        "null"
      ]
    },
    "seed_audio_voice": {
      "type": [
        "string",
        "null"
      ]
    },
    "prompt_guidance": {
      "type": [
        "string",
        "null"
      ]
    },
    "media_asset_id": {
      "type": "integer",
      "description": "Required for add_reference."
    },
    "reference_role": {
      "type": "string",
      "enum": [
        "voice_reference",
        "performance_reference",
        "style_reference"
      ],
      "default": "voice_reference"
    },
    "label": {
      "type": [
        "string",
        "null"
      ]
    },
    "is_selected": {
      "type": "boolean"
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "operation": {
            "const": "get"
          }
        }
      },
      "then": {
        "required": [
          "voice_profile_id"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "operation": {
            "const": "create"
          }
        }
      },
      "then": {
        "required": [
          "display_name"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "operation": {
            "const": "update"
          }
        }
      },
      "then": {
        "required": [
          "voice_profile_id"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "operation": {
            "const": "archive"
          }
        }
      },
      "then": {
        "required": [
          "voice_profile_id"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "operation": {
            "const": "add_reference"
          }
        }
      },
      "then": {
        "required": [
          "voice_profile_id",
          "media_asset_id"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "operation": {
            "const": "select_reference"
          }
        }
      },
      "then": {
        "required": [
          "voice_profile_id",
          "reference_id"
        ]
      }
    }
  ],
  "additionalProperties": false
}

Output schema

voice_profile output

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "operation",
    "project_id",
    "voice_profile_updated_at"
  ],
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "list",
        "get",
        "create",
        "update",
        "archive",
        "add_reference",
        "select_reference"
      ]
    },
    "project_id": {
      "type": "integer"
    },
    "profile": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true
    },
    "profiles": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "reference": {
      "type": "object",
      "additionalProperties": true
    },
    "voice_profile_updated_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Updated-at value for the returned voice profile/reference, when available."
    },
    "credits_skipped_reason": {
      "type": "string"
    }
  },
  "additionalProperties": true
}