voice_profile
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
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
{
"$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
{
"$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
}