<!-- generated: do not edit. source: content/docs/stt/translation.md -->

# Speech translation

`POST /v1/audio/translations` takes a finished audio file and returns its
content as text in another language. It follows the OpenAI translations shape.
`target_language` sets the language of the returned text.
[Models](/docs/stt/models) lists the models that translate. The examples use
`symphony` and abbreviate `usage`.

## Translate a file

Upload the audio as `multipart/form-data`. Without `target_language`, the text
comes back in English.

```bash
curl https://api.sprag.ai/v1/audio/translations \
  -H "Authorization: Bearer $SPRAG_API_KEY" \
  -F file=@reservation.wav \
  -F model=symphony
```

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.sprag.ai/v1",
    api_key=os.environ["SPRAG_API_KEY"],
)

with open("reservation.wav", "rb") as audio:
    translation = client.audio.translations.create(
        model="symphony",
        file=audio,
    )

print(translation.text)
```

```json
{
  "text": "Hello, I would like to reserve a table for four people on Friday evening at around eight o'clock.",
  "usage": { "input": { "audio": { "duration": "6.08" } } }
}
```

## Choose the output language

To get text in a language other than English, send its tag as
`target_language`. To send it from the OpenAI Python client, pass it in
`extra_body`.

```bash
curl https://api.sprag.ai/v1/audio/translations \
  -H "Authorization: Bearer $SPRAG_API_KEY" \
  -F file=@reservation.wav \
  -F model=symphony \
  -F target_language=de
```

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.sprag.ai/v1",
    api_key=os.environ["SPRAG_API_KEY"],
)

with open("reservation.wav", "rb") as audio:
    translation = client.audio.translations.create(
        model="symphony",
        file=audio,
        extra_body={"target_language": "de"},
    )

print(translation.text)
```

```json
{
  "text": "Guten Tag, ich hätte gerne einen Tisch für vier Personen am Freitagabend gegen zwanzig Uhr.",
  "usage": { "input": { "audio": { "duration": "6.08" } } }
}
```

## Name the spoken language

If you know the spoken language, send its tag as `source_languages`.

```bash
curl https://api.sprag.ai/v1/audio/translations \
  -H "Authorization: Bearer $SPRAG_API_KEY" \
  -F file=@reservation.wav \
  -F model=symphony \
  -F source_languages=fr \
  -F target_language=es
```

```json
{
  "text": "Hola, me gustaría reservar una mesa para cuatro personas el viernes por la noche, alrededor de las ocho.",
  "usage": { "input": { "audio": { "duration": "6.08" } } }
}
```

If the request carries one tag, the audio is translated from that language. If
it carries several, the spoken language is detected from among them. Send the
field once per tag. Without `source_languages`, the spoken language is detected
from the audio.

## Request fields

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `file` | Yes | file | The audio to translate. Common containers such as MP3, WAV, FLAC, M4A, OGG, AAC, AIFF, and WebM are accepted. |
| `model` | Yes | string | A model that translates, such as `symphony`. |
| `target_language` | No | string | ISO-639 tag of the language to return, such as `de`. English when omitted. |
| `source_languages` | No | string, repeatable | ISO-639 tag of a language the audio may be spoken in, such as `fr`. |
| `response_format` | No | string | `json`, the only accepted value. |

## Target languages

`target_language` accepts the tags below. Two- and three-letter ISO-639 tags
are both accepted, so `fr` and `fra` name the same language.

| Tag | Language | Tag | Language |
| --- | --- | --- | --- |
| `ar` | Arabic | `ms` | Malay |
| `de` | German | `nl` | Dutch |
| `en` | English | `pt` | Portuguese |
| `es` | Spanish | `ru` | Russian |
| `fr` | French | `tr` | Turkish |
| `hi` | Hindi | `ur` | Urdu |
| `id` | Indonesian | `vi` | Vietnamese |
| `it` | Italian | `yue` | Cantonese |
| `ja` | Japanese | `zh` | Chinese |
| `ko` | Korean | | |

If `target_language` names a language outside this list, the request returns
HTTP 400, and the error message lists the accepted tags.

## Response fields

| Field | Type | Notes |
| --- | --- | --- |
| `text` | string | The translated text. |
| `usage` | object | Measured per-modality usage and cost. |

## Errors

| Status | Meaning |
| --- | --- |
| `400` | Sent when `target_language` is not an accepted tag. Also sent when `response_format` is not `json`. Also sent with the code `model_not_supported` when the model does not translate. Also sent with the code `unsupported_media` when the audio cannot be decoded. |
| `401` | Missing, invalid, or expired credentials. |
| `402` | No payment method on the account. |
| `403` | Not a member of the requested organization. |
| `404` | Unknown model id. |
| `413` | Request too large. |
| `429` | Rate limit exceeded. Wait `Retry-After` seconds. |
| `500` | Unhandled server error. |
| `503` | Temporarily unavailable. Retry after `Retry-After` when it is set. |

Full schemas are in the [translations reference](/docs/api/audio/translations).
For transcripts in the spoken language, see [REST](/docs/stt/api/rest).