Caution

Style instructions are not available at launch. The instruction parameter is not supported on the current Voxtral TTS 3 checkpoint. This page documents the intended behavior for when the feature is enabled in a future release.

Style instructions

A style instruction describes, in your own words, how to say the whole input, such as a calm and slow delivery. Use it to set one delivery for the whole output; to change the emotion or the pace of part of the text, use emotion and pace tags.

Information

For how instructions compare with the other ways to direct a voice, see Voices.

API reference — POST /v1/audio/speech

Give a delivery instruction

Add instruction to the speech request, next to input and the voice. The value is a short sentence in plain language:

import base64
import os
from pathlib import Path

import httpx

response = httpx.post(
    "https://api.mistral.ai/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['MISTRAL_API_KEY']}"},
    json={
        "model": "voxtral-mini-tts-3-0",
        "input": "Your order shipped this morning and should arrive on Thursday.",
        "voice_id": "gb_jane_neutral",
        "instruction": "A calm, slow delivery.",
        "response_format": "wav",
    },
    timeout=60,
)
response.raise_for_status()

output = Path("calm.wav")
output.write_bytes(base64.b64decode(response.json()["audio_data"]))
print(f"Saved {output.resolve()}")

import base64
import os
from pathlib import Path

import httpx

response = httpx.post(
    "https://api.mistral.ai/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['MISTRAL_API_KEY']}"},
    json={
        "model": "voxtral-mini-tts-3-0",
        "input": "Your order shipped this morning and should arrive on Thursday.",
        "voice_id": "gb_jane_neutral",
        "instruction": "A calm, slow delivery.",
        "response_format": "wav",
    },
    timeout=60,
)
response.raise_for_status()

output = Path("calm.wav")
output.write_bytes(base64.b64decode(response.json()["audio_data"]))
print(f"Saved {output.resolve()}")

Note

Style instructions are not available at launch. It changes how the voice speaks, not what it says or which voice speaks: keep choosing the voice with voice_id.

Instructions, tags, and expressiveness

Three request settings shape the delivery, at different levels:

Setting	Applies to	Details
`instruction`	The whole input	This page
Emotion and pace tags in `input`	Part of the text	Emotion and pace tags
`expressiveness`	Controls how expressive the speech is. Higher values trade voice similarity and stability for stronger delivery.	Generate speech

Style instructions are not available at launch.

Limits and errors

These errors come from the instruction field:

Error	Cause	Fix
422 `Extra inputs are not permitted`	A misspelled field name, such as `instructions`	Use `instruction`, singular.
422 with type `string_type`	`instruction` isn't a string	Send the instruction as text.
Style instructions are not available at launch.	The instruction is over the length limit. It isn't shortened for you.	Shorten the instruction.
Style instructions are not available at launch.	The model doesn't support style instructions.	Use a model that supports them.

For other speech generation errors, see Troubleshooting.

Going further

Emotion and pace tags

Voices (concept)

Voices

Troubleshooting