> Revox API docs for developers and AI agents. Index: https://www.getrevox.com/docs/api/llms.txt · Everything in one file: https://www.getrevox.com/docs/api/llms-full.txt · OpenAPI 3.1: https://www.getrevox.com/openapi.json · MCP server: https://www.getrevox.com/api/mcp-servers/generic/mcp
> Base URL https://www.getrevox.com/api · Auth: `Authorization: Bearer $REVOX_API_KEY`

# Suggest versions of a word to choose by ear

`POST https://www.getrevox.com/api/assistants/{id}/pronunciations/suggest`

Hears how the word must sound (a recording of someone saying it, or `sounds_like`), writes up to five ways to spell it for the assistant's voice, the word as written first, and returns each one said by that voice in `sentence`.

## Before you call

- Nothing is saved: play the versions to the user, then send the one they keep to [`PUT /assistants/{id}/pronunciations`](https://www.getrevox.com/docs/api/assistants/set-how-the-voice-says-a-word.md).
- Send a recording of the word (a few seconds, WAV, MP3, OGG, FLAC or AAC; a browser records WebM, convert it to WAV first), or `sounds_like` as text.
- Takes about 5 to 10 seconds: one Gemini call, then every version synthesized at once.

## Request

### Example: From a recording

audio_base64 is the recording (shortened here): someone saying the word the way the voice must say it.

```bash
curl -X POST "https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34/pronunciations/suggest" \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "term": "Swile",
    "sentence": "Je vous appelle de la part de Swile.",
    "audio_base64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "mime_type": "audio/wav"
  }'
```

### Example: From a typed description

```json
{
  "term": "Lefebvre",
  "sentence": "Vous avez rendez-vous avec Maître Lefebvre.",
  "sounds_like": "le-fèvre, le b est muet"
}
```

## Path parameters

- `id` (string, required): ID of the assistant, as returned by [`GET /assistants`](https://www.getrevox.com/docs/api/assistants/get-assistants.md).

## Body

JSON.

- `term` (string, required): The word or name as it is written in the prompt and as the assistant writes it, e.g. "Swile" or "Thibault Lhuillier". Matched whole-word and case-sensitively. 1 to 100 characters. Example: `"Swile"`.
- `sentence` (string, optional): A sentence holding the word, as the assistant says it (e.g. the prompt's sentence that mentions it), to hear each version in context. Defaults to the word alone. At most 300 characters.
- `audio_base64` (string, optional): A recording of someone saying the word the way the voice must say it, base64-encoded without a data: prefix. A few seconds is enough. Send it with `mime_type`, or send `sounds_like` instead. 1 to 3000000 characters.
- `mime_type` (enum (5 values), optional): Format of the recording. Values: `"audio/wav"`, `"audio/mpeg"`, `"audio/ogg"`, `"audio/flac"`, `"audio/aac"`.
- `sounds_like` (string, optional): How it must sound, typed instead of a recording: a respelling in the call's language and any note on silent letters or English reading. 1 to 300 characters. Example: `"swaïle, une seule syllabe, à l'anglaise"`.

## Response 200

```json
{
  "sounds_like": "swaïle, une seule syllabe, à l'anglaise",
  "versions": [
    {
      "text": "Hello, this is Julie from Acme.",
      "audio_base64": "audio base64"
    }
  ]
}
```

- `sounds_like` (string): How the word must sound, from the recording or as sent. Send it back to POST /assistants/{id}/pronunciations. 1 to 300 characters. Example: `"swaïle, une seule syllabe, à l'anglaise"`.
- `versions` (array of object): Up to 5 ways to write the word for the assistant's voice, each with its audio, to listen to and choose from.
  - `versions.text` (string): The text that would be sent to the voice in place of the word. The first version is the word as written.
  - `versions.audio_base64` (string): The assistant's voice saying `sentence` with this text, base64-encoded WAV.

## Errors

- `400` Invalid request: a field or parameter failed validation: `{"message":"Request validation failed","bodyErrors":{"issues":[{"path":["term"],"message":"Invalid input: expected string, received undefined","code":"invalid_type"}]}}`
- `404` Not found in your organization: `{"error":"Not found"}`
- Every status is explained under Errors in https://www.getrevox.com/docs/api.md#errors.