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

# Speech-to-Speech Settings

> Configure S2S: voice, translation target, inner models, and audio formats

A Speech-to-Speech request translates spoken audio into another
language. It is configured through the `setup` message: some fields
select the pipeline (models, voice, formats), and the translation
target is passed through `json_config`. In the Python SDK `json_config`
is a dict; the SDK serializes it to a JSON string on the wire for you.

These options apply to the [WebSocket](/guides/speech-to-speech) API
across all three SDK entry points (`s2s_realtime`, `s2s_stream`, and the
buffered `s2s`). For the STT-only and TTS-only knobs, see
[Transcription Settings](/guides/transcription-settings) and
[Voice Settings](/guides/voice-settings).

## Setup fields

| Field             | Type             | Required | Effect                                                                                                                                       |
| ----------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `model_name`      | string           | Yes      | S2S model alias. Use `"s2s-translate"` for live translation, the only currently supported model.                                             |
| `stt_model_name`  | string           | No       | Speech-to-text model used to transcribe the input. Set to `"stt-translate"` for live translation.                                            |
| `tts_model_name`  | string           | No       | Text-to-speech model used to synthesize the output. Set to `"default"` for live translation.                                                 |
| `voice_id`        | string           | Yes      | Voice UID for the synthesized output. Must be a voice in the same language as `target_language`. See [Voices](/guides/voices/overview).      |
| `input_format`    | string           | Yes      | `pcm`, `wav`, `opus`, `ulaw_8000`, `alaw_8000`, or an explicit PCM rate such as `pcm_24000`. For `pcm`, input is 24 kHz, 16-bit signed mono. |
| `output_format`   | string           | Yes      | Same value set as `input_format`. For `pcm`, output is 48 kHz, 16-bit signed mono.                                                           |
| `json_config`     | object or string | No       | Advanced pipeline settings, see below.                                                                                                       |
| `client_req_id`   | string           | No       | Correlates multiplexed requests. See [Multiplexing](/guides/multiplexing).                                                                   |
| `close_ws_on_eos` | boolean          | No       | Defaults to `true`; set `false` to keep the socket open after `end_of_stream`.                                                               |

## `json_config` options

| Option            | Type   | Allowed values                         | Effect                                                  |
| ----------------- | ------ | -------------------------------------- | ------------------------------------------------------- |
| `target_language` | string | `"en"`, `"fr"`, `"de"`, `"es"`, `"pt"` | Language to translate the speech into before synthesis. |

The transcribed text is translated into `target_language` before the
output audio is generated, and the `text` messages you receive back
carry the translated text. The `voice_id` you choose must be a voice in
this same language.

## Passing `json_config`

The same `json_config` payload is sent regardless of which SDK entry
point you use; only the call shape differs:

```python theme={null}
config = {"target_language": "en"}

# Real-time: setup is keyword arguments; json_config stays nested.
async with client.s2s_realtime(
    model_name="s2s-translate",
    stt_model_name="stt-translate",
    tts_model_name="default",
    input_format="pcm",
    output_format="pcm",
    voice_id="YTpq7expH9539ERJ",
    json_config=config,
) as s2s:
    ...

# Pull-based / buffered: setup is a dict containing json_config.
setup = {
    "model_name": "s2s-translate",
    "stt_model_name": "stt-translate",
    "tts_model_name": "default",
    "input_format": "pcm",
    "output_format": "wav",
    "voice_id": "YTpq7expH9539ERJ",
    "json_config": config,
}
stream = await client.s2s_stream(setup, audio_generator(audio_data))
```

## Next steps

<CardGroup cols={2}>
  <Card title="S2S WebSocket guide" icon="waveform-lines" href="/guides/speech-to-speech">
    Real-time, pull-based, and buffered S2S with the Python SDK.
  </Card>

  <Card title="S2S WebSocket reference" icon="code" href="/api-reference/endpoint/s2s-websocket">
    Complete wire-level schema: every message type, every field, every
    error code.
  </Card>

  <Card title="Voices" icon="microphone" href="/guides/voices/overview">
    Pick the voice used for the synthesized output.
  </Card>

  <Card title="Voice settings" icon="sliders" href="/guides/voice-settings">
    TTS-side options for the synthesis stage.
  </Card>
</CardGroup>