Tavus Pronunciation Dictionaries API
The Pronunciation Dictionaries API from Tavus — 2 operation(s) for pronunciation dictionaries.
OpenAPI Specification
openapi: 3.0.3
info:
title: Tavus Developer API Collection Conversations Pronunciation Dictionaries API
version: 1.0.0
contact: {}
servers:
- url: https://tavusapi.com
security:
- apiKey: []
tags:
- name: Pronunciation Dictionaries
paths:
/v2/pronunciation-dictionaries:
post:
tags:
- Pronunciation Dictionaries
summary: Create Pronunciation Dictionary
description: 'Create a [pronunciation dictionary](/sections/conversational-video-interface/persona/pronunciation-dictionaries) with custom rules for controlling how words are spoken. Rules are automatically synced to both Cartesia and ElevenLabs so they work regardless of which TTS engine your persona uses.
'
operationId: createPronunciationDictionary
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name of the pronunciation dictionary. Max 255 characters.
example: Brand Terms
rules:
type: array
description: List of pronunciation rules. Duplicate `text` values are not allowed. You can omit rules at creation and add them later via [Update Pronunciation Dictionary](/api-reference/pronunciation-dictionaries/update-pronunciation-dictionary).
items:
type: object
properties:
text:
type: string
description: The word or phrase to match. Max 200 characters.
example: Tavus
pronunciation:
type: string
description: How the text should be pronounced. For `alias` type, this is the replacement text. For `ipa` type, this is an IPA string (raw or pipe-delimited). Max 500 characters.
example: TAH-vus
type:
type: string
description: Rule type. One of `alias` or `ipa`.
enum:
- alias
- ipa
example: alias
case_sensitive:
type: boolean
description: Whether matching is case-sensitive.
default: false
example: false
word_boundaries:
type: boolean
description: Whether to match only whole words.
default: true
example: true
required:
- text
- pronunciation
- type
example:
- text: Tavus
pronunciation: TAH-vus
type: alias
required:
- name
responses:
'201':
description: Pronunciation dictionary created successfully
content:
application/json:
schema:
type: object
properties:
pronunciation_dictionary_id:
type: string
description: Unique identifier for the pronunciation dictionary.
example: pd_abc123def456gh
name:
type: string
description: Name of the pronunciation dictionary.
example: Brand Terms
rules:
type: array
description: List of pronunciation rules.
items:
type: object
properties:
text:
type: string
example: Tavus
pronunciation:
type: string
example: TAH-vus
type:
type: string
enum:
- alias
- ipa
example: alias
case_sensitive:
type: boolean
example: false
word_boundaries:
type: boolean
example: true
rules_count:
type: integer
description: Number of rules in the dictionary.
example: 1
created_at:
type: string
description: ISO 8601 timestamp of when the dictionary was created.
example: '2025-01-15T10:30:00Z'
updated_at:
type: string
description: ISO 8601 timestamp of when the dictionary was last updated.
example: '2025-01-15T10:30:00Z'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message
example: 'Invalid request: name is required'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: Invalid access token
security:
- apiKey: []
get:
tags:
- Pronunciation Dictionaries
summary: List Pronunciation Dictionaries
description: 'List all pronunciation dictionaries for the authenticated user with pagination.
'
operationId: listPronunciationDictionaries
parameters:
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 100
default: 10
description: 'Number of results per page. Range: 1-100.'
example: 10
- in: query
name: page
schema:
type: integer
default: 0
description: Zero-based page number.
example: 0
- in: query
name: sort
schema:
type: string
enum:
- asc
- desc
default: desc
description: Sort order by creation date.
example: desc
responses:
'200':
description: List of pronunciation dictionaries
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: Dictionaries for the current page; use `total_count`, `page`, and `limit` with the query parameters for pagination.
items:
type: object
properties:
pronunciation_dictionary_id:
type: string
description: Unique identifier for the pronunciation dictionary.
example: pd_abc123def456gh
name:
type: string
description: Name of the pronunciation dictionary.
example: Brand Terms
rules_count:
type: integer
description: Number of rules in the dictionary. List responses omit the full `rules` array; use [Get Pronunciation Dictionary](/api-reference/pronunciation-dictionaries/get-pronunciation-dictionary) to retrieve rules.
example: 3
created_at:
type: string
description: ISO 8601 timestamp of when the dictionary was created.
example: '2025-01-15T10:30:00Z'
updated_at:
type: string
description: ISO 8601 timestamp of when the dictionary was last updated.
example: '2025-01-15T10:30:00Z'
total_count:
type: integer
description: Total number of pronunciation dictionaries for the user
example: 2
page:
type: integer
description: Current page number
example: 0
limit:
type: integer
description: Number of dictionaries per page
example: 10
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: Invalid access token
security:
- apiKey: []
/v2/pronunciation-dictionaries/{dictionary_id}:
get:
tags:
- Pronunciation Dictionaries
summary: Get Pronunciation Dictionary
description: 'Retrieve a pronunciation dictionary by its ID, including all rules.
'
operationId: getPronunciationDictionary
parameters:
- in: path
name: dictionary_id
required: true
schema:
type: string
description: The unique identifier of the pronunciation dictionary.
example: pd_abc123def456gh
responses:
'200':
description: Pronunciation dictionary details
content:
application/json:
schema:
type: object
properties:
pronunciation_dictionary_id:
type: string
description: Unique identifier for the pronunciation dictionary.
example: pd_abc123def456gh
name:
type: string
description: Name of the pronunciation dictionary.
example: Brand Terms
rules:
type: array
description: List of pronunciation rules.
items:
type: object
properties:
text:
type: string
example: Tavus
pronunciation:
type: string
example: TAH-vus
type:
type: string
enum:
- alias
- ipa
example: alias
case_sensitive:
type: boolean
example: false
word_boundaries:
type: boolean
example: true
rules_count:
type: integer
description: Number of rules in the dictionary.
example: 1
created_at:
type: string
description: ISO 8601 timestamp of when the dictionary was created.
example: '2025-01-15T10:30:00Z'
updated_at:
type: string
description: ISO 8601 timestamp of when the dictionary was last updated.
example: '2025-01-15T10:30:00Z'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: Invalid access token
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: Pronunciation dictionary not found
security:
- apiKey: []
patch:
tags:
- Pronunciation Dictionaries
summary: Update Pronunciation Dictionary
description: 'Update a pronunciation dictionary''s name or rules using [JSON Patch](https://jsonpatch.com/) format (RFC 6902). Supported mutable fields are `name` and `rules`.
'
operationId: patchPronunciationDictionary
parameters:
- in: path
name: dictionary_id
required: true
schema:
type: string
description: The unique identifier of the pronunciation dictionary.
example: pd_abc123def456gh
requestBody:
description: "Read-only fields like `pronunciation_dictionary_id`, `created_at`, and `updated_at` are silently ignored. If all operations target read-only fields or result in no changes, the endpoint returns `304`.\n\nWhen rules are updated, all personas referencing this dictionary are automatically updated with the new provider-specific pronunciation data.\n\n**Note:** Updating rules replaces the entire rules array. There is no way to add or remove individual rules — provide the complete updated list.\n\nFor example:\n\n```json\n[\n { \"op\": \"replace\", \"path\": \"/name\", \"value\": \"Updated Brand Terms\" },\n { \"op\": \"replace\", \"path\": \"/rules\", \"value\": [\n { \"text\": \"Tavus\", \"pronunciation\": \"TAH-vus\", \"type\": \"alias\" }\n ]}\n]\n```\n"
content:
application/json:
schema:
type: array
items:
type: object
properties:
op:
type: string
description: 'The operation to perform. Must be one of: add, remove, replace, copy, move, test'
enum:
- add
- remove
- replace
- copy
- move
- test
example: replace
path:
type: string
description: 'A JSON Pointer string that references a location within the target document where the operation is performed. Supported paths: `/name`, `/rules`.'
example: /name
value:
description: The value to be used within the operation. Required unless using `remove`.
required:
- op
- path
examples:
Update name:
value:
- op: replace
path: /name
value: Updated Brand Terms
Update rules:
value:
- op: replace
path: /rules
value:
- text: Tavus
pronunciation: TAH-vus
type: alias
- text: CVI
pronunciation: conversational video interface
type: alias
Update both:
value:
- op: replace
path: /name
value: Updated Brand Terms
- op: replace
path: /rules
value:
- text: Tavus
pronunciation: TAH-vus
type: alias
responses:
'200':
description: Pronunciation dictionary updated successfully
content:
application/json:
schema:
type: object
properties:
pronunciation_dictionary_id:
type: string
description: Unique identifier for the pronunciation dictionary.
example: pd_abc123def456gh
name:
type: string
description: Name of the pronunciation dictionary.
example: Updated Brand Terms
rules:
type: array
description: List of pronunciation rules.
items:
type: object
properties:
text:
type: string
example: Tavus
pronunciation:
type: string
example: TAH-vus
type:
type: string
enum:
- alias
- ipa
example: alias
case_sensitive:
type: boolean
example: false
word_boundaries:
type: boolean
example: true
rules_count:
type: integer
description: Number of rules in the dictionary.
example: 1
created_at:
type: string
description: ISO 8601 timestamp of when the dictionary was created.
example: '2025-01-15T10:30:00Z'
updated_at:
type: string
description: ISO 8601 timestamp of when the dictionary was last updated.
example: '2025-01-15T12:00:00Z'
'304':
description: No changes were made to the pronunciation dictionary
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message
example: 'Invalid request: duplicate text values in rules'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: Invalid access token
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: Pronunciation dictionary not found
'422':
description: Invalid JSON patch format
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: Invalid JSON patch format
security:
- apiKey: []
delete:
tags:
- Pronunciation Dictionaries
summary: Delete Pronunciation Dictionary
description: 'Permanently delete a pronunciation dictionary and remove it from all linked personas.
'
operationId: deletePronunciationDictionary
parameters:
- in: path
name: dictionary_id
required: true
schema:
type: string
description: 'The unique identifier of the pronunciation dictionary to delete.
**Warning:** This action is permanent. The dictionary is deleted from both Cartesia and ElevenLabs, and all personas referencing it will have their `pronunciation_dictionary_id` set to `null` and provider-specific pronunciation settings removed from `voice_settings`.
'
example: pd_abc123def456gh
responses:
'204':
description: NO CONTENT - Pronunciation dictionary deleted successfully
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: Invalid access token
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: Pronunciation dictionary not found
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key