Translation

Overview

The Translation feature automatically converts your transcribed audio content from one language to another, enabling you to reach global audiences without manual translation work. You can translate transcripts into over 100 languages with a single API request.

Key capabilities:

• Translate to multiple target languages simultaneously
• Choose between formal and informal translation styles
• Translate during transcription or add translations to existing transcripts
• Get full-text translations that preserve the original meaning and context
• Get per-speaker translated utterances when using Speaker Labels

Common use cases:

• Creating multilingual subtitles for video content
• Translating customer support calls for international teams
• Localizing podcast episodes for different markets
• Making educational content accessible in multiple languages
• Generating multilingual meeting summaries

Quickstart

There are two ways to use Translation:

1. Transcribe and translate in one request - Best when you’re starting a new transcription and want to automatically translate the transcript text as part of that process
2. Transcribe and translate in separate requests - Best when you already have text that you would like to translate or for more complicated workflows where you want to separate the transcription and translation tasks

Method 1: Transcribe and translate in one request

This method is ideal when you’re starting fresh and want both transcription and translation in a single workflow.

1
import requests
2
import time
3
4
base_url = "https://api.assemblyai.com"
5
6
headers = {
7
  "authorization": "YOUR_API_KEY"
8
}
9
10
# Need to transcribe a local file? Learn more here: https://www.assemblyai.com/docs/getting-started/transcribe-an-audio-file
11
audio_url = "https://assembly.ai/wildfires.mp3"
12
13
# Configure transcription with translation
14
data = {
15
  "audio_url": audio_url,
16
  "speaker_labels": True,  # Enable speaker labels
17
  "speech_understanding": {
18
    "request": {
19
      "translation": {
20
        "target_languages": ["es", "de"],  # Translate to Spanish and German
21
        "formal": True  # Use formal language style
22
      }
23
    }
24
  }
25
}
26
27
# Submit transcription request
28
response = requests.post(base_url + "/v2/transcript", headers=headers, json=data)
29
transcript_id = response.json()["id"]
30
polling_endpoint = base_url + f"/v2/transcript/{transcript_id}"
31
32
# Poll transcription results
33
while True:
34
  transcript = requests.get(polling_endpoint, headers=headers).json()
35
36
  if transcript["status"] == "completed":
37
    break
38
39
  elif transcript["status"] == "error":
40
    raise RuntimeError(f"Transcription failed: {transcript['error']}")
41
42
  else:
43
    time.sleep(3)
44
45
# Access and display results
46
print("\n--- Original Transcript ---")
47
print(transcript['text'][:200] + "...\n")
48
49
print("--- Translations ---")
50
for language_code, translated_text in transcript['translated_texts'].items():
51
  print(f"{language_code.upper()}:")
52
  print(translated_text[:200] + "...\n")

Method 2: Transcribe and translate in separate requests

This method is useful when you already have text that you would like to translate or for more complicated workflows where you want to separate the transcription and translation tasks.

1
import requests
2
import time
3
4
base_url = "https://api.assemblyai.com"
5
6
headers = {
7
  "authorization": "<YOUR_API_KEY>"
8
}
9
10
# Need to transcribe a local file? Learn more here: https://www.assemblyai.com/docs/getting-started/transcribe-an-audio-file
11
audio_url = "https://assembly.ai/wildfires.mp3"
12
13
# Submit transcription request (without translation)
14
data = {
15
  "audio_url": audio_url,
16
  "speaker_labels": True
17
}
18
19
# Transcribe file
20
response = requests.post(base_url + "/v2/transcript", headers=headers, json=data)
21
transcript_id = response.json()["id"]
22
polling_endpoint = base_url + f"/v2/transcript/{transcript_id}"
23
24
# Poll for transcription completion
25
while True:
26
  transcript = requests.get(polling_endpoint, headers=headers).json()
27
28
  if transcript["status"] == "completed":
29
    print("Transcription completed!")
30
    break
31
32
  elif transcript["status"] == "error":
33
    raise RuntimeError(f"Transcription failed: {transcript['error']}")
34
35
  else:
36
    time.sleep(3)
37
38
# Add translation configuration to the completed transcript
39
understanding_body = {
40
  "transcript_id": transcript_id,
41
  "speech_understanding": {
42
    "request": {
43
      "translation": {
44
      "target_languages": ["es", "de"],  # Translate to Spanish and German
45
      "formal": True  # Use formal language style
46
      }
47
    }
48
  }
49
}
50
51
# Send to Speech Understanding API for translation
52
result = requests.post(
53
  "https://llm-gateway.assemblyai.com/v1/understanding",
54
  headers=headers,
55
  json=understanding_body
56
).json()
57
58
# Access and display results
59
print("\n--- Original Transcript ---")
60
print(transcript['text'][:200] + "...\n")
61
62
print("--- Translations ---")
63
for language_code, translated_text in result['translated_texts'].items():
64
  print(f"{language_code.upper()}:")
65
  print(translated_text[:200] + "...\n")

Expected output:

--- Original Transcript ---
Smoke from hundreds of wildfires in Canada is triggering air quality alerts throughout the US...
--- Translations ---
ES:
El humo de cientos de incendios forestales en Canadá está provocando alertas de calidad del aire...
DE:
Rauch von Hunderten von Waldbränden in Kanada löst in den gesamten USA Luftqualitätswarnungen aus...

Output format

The Translation API returns translations in the translated_texts key of the response. This key contains an object where each property is a language code corresponding to one of your target languages, and the value is the full translated text.

Example response structure:

1
{
2
  "id": "735d90b6-2e8b-4748-b75d-d02b78eb7811",
3
  "status": "completed",
4
  "text": "Smoke from hundreds of wildfires in Canada is triggering air quality alerts...",
5
  "translated_texts": {
6
    "es": "El humo de cientos de incendios forestales en Canadá está provocando alertas de calidad del aire...",
7
    "de": "Rauch von Hunderten von Waldbränden in Kanada löst in den gesamten USA Luftqualitätswarnungen aus..."
8
  },
9
  "speech_understanding": {
10
    "request": {
11
      "translation": {
12
        "formal": true,
13
        "target_languages": [
14
          "es",
15
          "de"
16
        ],
17
      }
18
    },
19
    "response": {
20
      "translation": {
21
        "status": "success"
22
      }
23
    }
24
  },
25
  "utterances": [
26
    {
27
      "speaker": "A",
28
      "text": "Smoke from hundreds of wildfires in Canada is triggering air quality alerts...",
29
      "confidence": 0.9815734,
30
      "start": 240,
31
      "end": 26560,
32
      "words": [
33
        {
34
          "text": "Smoke",
35
          "start": 240,
36
          "end": 640,
37
          "confidence": 0.90152997,
38
          "speaker": "A"
39
        },
40
        // ... more words
41
      ],
42
      "translated_texts": {
43
        "es": "El humo de cientos de incendios forestales en Canadá está provocando alertas de calidad del aire...",
44
        "de": "Rauch von Hunderten von Waldbränden in Kanada löst in den gesamten USA Luftqualitätswarnungen aus..."
45
      }
46
    },
47
    // ... more utterances
48
  ],
49
  ...
50
}

API reference

Request

Method 1: Transcribe and translate in one request

When creating a new transcription, include the speech_understanding parameter directly in your transcription request:

$
curl -X POST \
>
  "https://api.assemblyai.com/v2/transcript" \
>
  -H "Authorization: YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "audio_url": "https://assembly.ai/wildfires.mp3",
>
    "speaker_labels": true,
>
    "speech_understanding": {
>
      "request": {
>
        "translation": {
>
          "target_languages": ["es", "de"],
>
          "formal": true
>
        }
>
      }
>
    }
>
  }'

Method 2: Add translation to existing transcripts

For existing transcripts, retrieve the completed transcript and send it to the Speech Understanding API:

$
# Step 1: Get the completed transcript
>
transcript=$(curl -s -X GET \
>
  "https://api.assemblyai.com/v2/transcript/YOUR_TRANSCRIPT_ID" \
>
  -H "Authorization: YOUR_API_KEY")
>
>
# Step 2: Add translation and send to Speech Understanding API
>
curl -X POST \
>
  "https://llm-gateway.assemblyai.com/v1/understanding" \
>
  -H "Authorization: YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "transcript_id": "{transcript_id}",
>
    "speech_understanding": {
>
      "request": {
>
        "translation": {
>
          "target_languages": ["es", "de"],
>
          "formal": true
>
        }
>
      }
>
    }
>
  }'

Response

The Translation API returns your original transcript response with an additional translated_texts key containing the translations.

1
{
2
  "id": "735d90b6-2e8b-4748-b75d-d02b78eb7811",
3
  "status": "completed",
4
  "text": "Smoke from hundreds of wildfires in Canada is triggering air quality alerts throughout the US...",
5
  "translated_texts": {
6
    "es": "El humo de cientos de incendios forestales en Canadá está provocando alertas de calidad del aire en todo Estados Unidos...",
7
    "de": "Rauch von Hunderten von Waldbränden in Kanada löst in den gesamten USA Luftqualitätswarnungen aus..."
8
  },
9
  "speech_understanding": {
10
    "request": {
11
      "translation": {
12
        "formal": true,
13
        "target_languages": ["es", "de"]
14
      }
15
    },
16
    "response": {
17
      "translation": {
18
        "status": "success"
19
      }
20
    }
21
  }
22
}

| speech_understanding | object | Container for speech understanding request and response information. | | speech_understanding.request | object | The original translation request configuration that was submitted. | | speech_understanding.request.translation | object | The translation parameters that were used. | | speech_understanding.response | object | The response information from the translation process. | | speech_understanding.response.translation | object | Status information about the translation. | | speech_understanding.response.translation.status | string | The status of the translation. Will be "success" when translation completes successfully. |

Key differences from standard transcription

All other fields from the original transcript (text, words, utterances, confidence, etc.) remain unchanged.