> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threetone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice and language

> Prepare compatible speech-recognition, voice, and response-language settings in a server draft while voice publication remains unavailable.

A voice configuration connects an input-language policy, a speech-recognition model, a response language, and a speech-generation model with a saved voice. Choose these together so the configuration supports the languages you intend to use.

<Note>
  The dashboard's **Voices**, **Language**, and **ASR** sections are labelled previews whose changes are not saved. Additional-language first messages and translation are also previews. Use the API workflow below for draft authoring. Voice publication and live conversation execution remain [gated](/agents-platform/overview#current-availability).
</Note>

## Before you begin

You need an agent you can update, the intended `branch_id`, a server-side [API key](/overview/administration/workspaces/api-keys) with the required access, and a saved voice in the same workspace. To create a complete voice configuration from the start, follow the [API quickstart](/agents-platform/get-started/api-quickstart).

## Choose and save compatible settings

<Steps>
  <Step title="Read the branch and model catalog" id="voice-read-model-catalog">
    Read the selected branch with [Get agent](/api-reference/agents-platform/get-agent). Keep the current document so you can preserve fields you are not changing.

    Use [List available AI models](/api-reference/agents-platform/list-available-ai-models) and [Get available AI model](/api-reference/agents-platform/get-available-ai-model) to inspect available ASR and TTS models. Check language coverage, recognition modes, and supported options instead of copying an identifier from a screenshot.
  </Step>

  <Step title="Configure input recognition" id="voice-configure-recognition">
    Set `conversation_config.asr.model_id` to the selected catalog model. Supply its required `recognition` configuration using a mode that model supports.

    Choose the caller's input language independently from the response language. If you add `keyterms`, use distinct, nonblank terms within the model's limits. Only supply `options` that match the selected model's parameter schema.
  </Step>

  <Step title="Configure speech generation and response language" id="voice-configure-response">
    Use [List my voices](/api-reference/voices/list-my-voices) to choose an accessible saved `voice_id`. Set `conversation_config.tts.model_id` and `conversation_config.tts.voice_id`, then check compatibility with the intended languages.

    Set `conversation_config.agent.language` for the base response language. Review `conversation_config.agent.response_language_policy`: `base_language` is the default; `recognized_language` requests responses in a language identified by compatible ASR.
  </Step>

  <Step title="Save and inspect a server draft" id="voice-publish-read-back">
    Use [Create agent draft](/api-reference/agents-platform/create-agent-draft) with an explicit `branch_id` and the complete snapshot. Follow [versions and drafts](/agents-platform/deploy/versioning) and preserve unrelated fields.

    Read the selected branch's draft back and confirm ASR mode, model IDs, voice ID, base language, and response policy. Do not use Update agent to publish this voice configuration: the runtime projection is unavailable, even with compatible speech settings.
  </Step>
</Steps>

## Input-language modes

All fields below are inside `conversation_config.asr.recognition`.

| `mode` | Required fields | What to check |
| - | - | - |
| `fixed` | `language` | The model supports the selected input language. |
| `automatic_provider_languages` | No language list | The model supports automatic recognition across its available languages. |
| `automatic_selected_languages` | Nonempty `languages` list | The model supports candidate selection and any required `primary_language`. |

Selected languages must be distinct. When a `primary_language` is supplied, it must appear in `languages`. Some model contracts require that field; others do not accept it. The presence of a mode in the request schema does not mean every model offers it.

The ASR `task` currently accepts only `transcribe`. A response-language policy does not turn speech recognition into a translation task.

## Response language and localized copy

`conversation_config.agent.language` defaults to `en`. ASR input-language selection does not replace this field.

| Response policy | Configuration requirement |
| - | - |
| `base_language` | Use the configured base response language. This is the default. |
| `recognized_language` | Requires speech input and an ASR model and options that provide compatible recognized-language information. It is rejected for text-only configurations or absent ASR. |

`conversation_config.language_presets` can store localized first-message and duration-limit copy, localized soft-timeout settings, and compatible voice overrides. Presets do not switch the ASR model, TTS model, language model, or tool set. Their saved copy does not prove automatic translation or runtime language switching.

## Speech fields to review

These paths are relative to `conversation_config`.

| Field | Authoring requirement or default |
| - | - |
| `asr` | May be `null` while authoring. When supplied, `model_id` and `recognition` are required. |
| `asr.task` | `transcribe`. |
| `asr.keyterms` | Empty list; support and limits vary by model. |
| `asr.options` | `null` or the selected model's matching options. |
| `tts` | May be `null` while authoring. When supplied, `model_id` and a nonempty `voice_id` are required. |
| `tts.options` | `null` or the selected model's matching options. |
| `tts.pronunciation_dictionary_locators` | Empty list; use only when supported by the model. |
| `tts.enable_phoneme_tags` | `false`; use only when supported by the model. |

ASR and TTS compatibility is necessary for a future voice publication path, but does not make that path available today. A configuration with `conversation.text_only: true` does not require speech settings, but it cannot use `recognized_language` as its response policy.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why did my dashboard language or voice selection not save?" id="faq-voice-dashboard-preview">
    The visible speech and language pickers currently hold preview values. Use the API to save a server draft, then inspect that draft. The dashboard's LLM editor is a separate control; persisting its change still requires an eligible publication.
  </Accordion>

  <Accordion title="Can I use a provider's public voice ID?" id="faq-voice-saved-id">
    Use an accessible saved workspace voice returned by List my voices. A public provider identifier is not automatically a saved workspace voice, and model compatibility still needs to be checked.
  </Accordion>

  <Accordion title="Why is an automatic recognition mode rejected?" id="faq-voice-recognition-mode">
    Recognition modes and primary-language requirements vary by model. Inspect the selected model's catalog entry and the returned validation error. Do not assume that every alternative in the public schema is supported by that model.
  </Accordion>

  <Accordion title="Does publishing confirm that the voice sounds correct?" id="faq-voice-runtime-verification">
    Voice publication is currently unavailable. A future publication would still require a separate supported runtime test to establish audio quality, language detection, and conversation behavior. Keep the assessed version ID with that evidence.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.