Translation - AssemblyAI

Supported languages

Supported models

Supported regions

US & EU

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:

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
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.

Python
JavaScript
Python SDK
JavaScript SDK

import requests
import time

base_url = "https://api.assemblyai.com"

headers = {
  "authorization": "YOUR_API_KEY"
}

# Need to transcribe a local file? Learn more here: https://www.assemblyai.com/docs/getting-started/transcribe-an-audio-file
audio_url = "https://assembly.ai/wildfires.mp3"

# Configure transcription with translation
data = {
  "audio_url": audio_url,
  "speech_models": ["universal-3-pro", "universal-2"],
  "language_detection": True,
  "speaker_labels": True,  # Enable speaker labels
  "speech_understanding": {
    "request": {
      "translation": {
        "target_languages": ["es", "de"],  # Translate to Spanish and German
        "formal": True  # Use formal language style
      }
    }
  }
}

# Submit transcription request
response = requests.post(base_url + "/v2/transcript", headers=headers, json=data)
transcript_id = response.json()["id"]
polling_endpoint = base_url + f"/v2/transcript/{transcript_id}"

# Poll transcription results
while True:
  transcript = requests.get(polling_endpoint, headers=headers).json()

  if transcript["status"] == "completed":
    break

  elif transcript["status"] == "error":
    raise RuntimeError(f"Transcription failed: {transcript['error']}")

  else:
    time.sleep(3)

# Access and display results
print("\n--- Original Transcript ---")
print(transcript['text'][:200] + "...\n")

print("--- Translations ---")
for language_code, translated_text in transcript['translated_texts'].items():
  print(f"{language_code.upper()}:")
  print(translated_text[:200] + "...\n")

import fetch from "node-fetch";

const baseUrl = "https://api.assemblyai.com";
const headers = {
  authorization: "YOUR_API_KEY",
};

// Need to transcribe a local file? Learn more here: https://www.assemblyai.com/docs/getting-started/transcribe-an-audio-file
const audioUrl = "https://assembly.ai/wildfires.mp3";

// Configure transcription with translation
const data = {
  audio_url: audioUrl,
  speech_models: ["universal-3-pro", "universal-2"],
  language_detection: true,
  speaker_labels: true, // Enable speaker labels
  speech_understanding: {
    request: {
      translation: {
        target_languages: ["es", "de"], // Translate to Spanish and German
        formal: true, // Use formal language style
      },
    },
  },
};

// Submit transcription request
async function transcribeAndTranslate() {
  const response = await fetch(`${baseUrl}/v2/transcript`, {
    method: "POST",
    headers: {
      ...headers,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(data),
  });

  const transcript = await response.json();
  const transcriptId = transcript.id;
  const pollingEndpoint = `${baseUrl}/v2/transcript/${transcriptId}`;

  // Poll transcription results
  while (true) {
    const pollingResponse = await fetch(pollingEndpoint, { headers });
    const transcriptResult = await pollingResponse.json();

    if (transcriptResult.status === "completed") {
      // Access and display results
      console.log("\n--- Original Transcript ---");
      console.log(transcriptResult.text.substring(0, 200) + "...\n");

      console.log("--- Translations ---");
      for (const [languageCode, translatedText] of Object.entries(
        transcriptResult.translated_texts
      )) {
        console.log(`${languageCode.toUpperCase()}:`);
        console.log(translatedText.substring(0, 200) + "...\n");
      }
      break;
    } else if (transcriptResult.status === "error") {
      throw new Error(`Transcription failed: ${transcriptResult.error}`);
    } else {
      await new Promise((resolve) => setTimeout(resolve, 3000));
    }
  }
}

transcribeAndTranslate();

import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

audio_url = "https://assembly.ai/wildfires.mp3"

config = aai.TranscriptionConfig(
    speech_models=["universal-3-pro", "universal-2"],
    language_detection=True,
    speaker_labels=True,
    speech_understanding=aai.SpeechUnderstandingRequest(
        request=aai.SpeechUnderstandingFeatureRequests(
            translation=aai.TranslationRequest(
                target_languages=["es", "fr"],
            )
        )
    )
)

transcriber = aai.Transcriber()
transcript = transcriber.transcribe(audio_url, config)

# Print the translated texts
for lang, text in transcript.json_response["translated_texts"].items():
    print(f"\n[{lang}]:\n{text}")

import { AssemblyAI } from "assemblyai";

const client = new AssemblyAI({
  apiKey: "<YOUR_API_KEY>"
});

const audioUrl = "https://assembly.ai/wildfires.mp3";

const params = {
  audio: audioUrl,
  speech_models: ["universal-3-pro", "universal-2"],
  language_detection: true,
  speaker_labels: true,
  speech_understanding: {
    request: {
      translation: {
        target_languages: ["es", "fr"],
      }
    }
  }
};

const transcript = await client.transcripts.transcribe(params);

// Print the translated texts
for (const [lang, text] of Object.entries(transcript.translated_texts)) {
  console.log(`\n[${lang}]:\n${text}`);
}

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.

Python
JavaScript

import requests
import time

base_url = "https://api.assemblyai.com"

headers = {
  "authorization": "<YOUR_API_KEY>"
}

# Need to transcribe a local file? Learn more here: https://www.assemblyai.com/docs/getting-started/transcribe-an-audio-file
audio_url = "https://assembly.ai/wildfires.mp3"

# Submit transcription request (without translation)
data = {
  "audio_url": audio_url,
  "speech_models": ["universal-3-pro", "universal-2"],
  "language_detection": True,
  "speaker_labels": True,
}

# Transcribe file
response = requests.post(base_url + "/v2/transcript", headers=headers, json=data)
transcript_id = response.json()["id"]
polling_endpoint = base_url + f"/v2/transcript/{transcript_id}"

# Poll for transcription completion
while True:
  transcript = requests.get(polling_endpoint, headers=headers).json()

  if transcript["status"] == "completed":
    print("Transcription completed!")
    break

  elif transcript["status"] == "error":
    raise RuntimeError(f"Transcription failed: {transcript['error']}")

  else:
    time.sleep(3)

# Add translation configuration to the completed transcript
understanding_body = {
  "transcript_id": transcript_id,
  "speech_understanding": {
    "request": {
      "translation": {
      "target_languages": ["es", "de"],  # Translate to Spanish and German
      "formal": True  # Use formal language style
      }
    }
  }
}

# Send to Speech Understanding API for translation
result = requests.post(
  "https://llm-gateway.assemblyai.com/v1/understanding",
  headers=headers,
  json=understanding_body
).json()

# Access and display results
print("\n--- Original Transcript ---")
print(transcript['text'][:200] + "...\n")

print("--- Translations ---")
for language_code, translated_text in result['translated_texts'].items():
  print(f"{language_code.upper()}:")
  print(translated_text[:200] + "...\n")

const baseUrl = "https://api.assemblyai.com";

const headers = {
  authorization: "<YOUR_API_KEY>",
  "content-type": "application/json",
};

// Need to transcribe a local file? Learn more here: https://www.assemblyai.com/docs/getting-started/transcribe-an-audio-file
const audioUrl = "https://assembly.ai/wildfires.mp3";

// Helper function to sleep
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function main() {
  // Submit transcription request (without translation)
  const data = {
    audio_url: audioUrl,
    speech_models: ["universal-3-pro", "universal-2"],
    language_detection: true,
    speaker_labels: true,
  };

  // Transcribe file
  const response = await fetch(`${baseUrl}/v2/transcript`, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  });

  const responseData = await response.json();
  const transcriptId = responseData.id;
  const pollingEndpoint = `${baseUrl}/v2/transcript/${transcriptId}`;

  // Poll for transcription completion
  let transcript;
  while (true) {
    const pollResponse = await fetch(pollingEndpoint, {
      method: "GET",
      headers: headers,
    });

    transcript = await pollResponse.json();

    if (transcript.status === "completed") {
      console.log("Transcription completed!");
      break;
    } else if (transcript.status === "error") {
      throw new Error(`Transcription failed: ${transcript.error}`);
    } else {
      await sleep(3000);
    }
  }

  // Add translation configuration to the completed transcript
  const understandingBody = {
    transcript_id: transcriptId,
    speech_understanding: {
      request: {
        translation: {
          target_languages: ["es", "de"], // Translate to Spanish and German
          formal: true, // Use formal language style
        },
      },
    },
  };

  // Send to Speech Understanding API for translation
  const resultResponse = await fetch(
    "https://llm-gateway.assemblyai.com/v1/understanding",
    {
      method: "POST",
      headers: headers,
      body: JSON.stringify(understandingBody),
    }
  );

  const result = await resultResponse.json();

  // Access and display results
  console.log("\n--- Original Transcript ---");
  console.log(transcript.text.substring(0, 200) + "...\n");

  console.log("--- Translations ---");
  for (const [languageCode, translatedText] of Object.entries(
    result.translated_texts
  )) {
    console.log(`${languageCode.toUpperCase()}:`);
    console.log(translatedText.substring(0, 200) + "...\n");
  }
}

// Run the main function
main().catch((error) => {
  console.error("Error:", error);
});

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:

{
  "id": "735d90b6-2e8b-4748-b75d-d02b78eb7811",
  "status": "completed",
  "text": "Smoke from hundreds of wildfires in Canada is triggering air quality alerts...",
  "translated_texts": {
    "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..."
  },
  "speech_understanding": {
    "request": {
      "translation": {
        "formal": true,
        "target_languages": [
          "es",
          "de"
        ],
      }
    },
    "response": {
      "translation": {
        "status": "success"
      }
    }
  },
  "utterances": [
    {
      "speaker": "A",
      "text": "Smoke from hundreds of wildfires in Canada is triggering air quality alerts...",
      "confidence": 0.9815734,
      "start": 240,
      "end": 26560,
      "words": [
        {
          "text": "Smoke",
          "start": 240,
          "end": 640,
          "confidence": 0.90152997,
          "speaker": "A"
        },
        // ... more words
      ],
      "translated_texts": {
        "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..."
      }
    },
    // ... more utterances
  ],
  ...
}

Translation with speaker labels

When you use Translation with Speaker Labels, you can get translated text for each individual utterance by setting match_original_utterance to true. This is useful for creating speaker-specific subtitles or analyzing conversations in multiple languages while preserving speaker attribution.

Python
JavaScript

import requests
import time

base_url = "https://api.assemblyai.com"

headers = {
  "authorization": "YOUR_API_KEY"
}

audio_url = "https://assembly.ai/wildfires.mp3"

# Configure transcription with translation and speaker labels
data = {
  "audio_url": audio_url,
  "speech_models": ["universal-3-pro", "universal-2"],
  "language_detection": True,
  "speaker_labels": True,  # Enable speaker labels
  "speech_understanding": {
    "request": {
      "translation": {
        "target_languages": ["es"],
        "match_original_utterance": True,  # Get translated text per utterance
        "formal": True
      }
    }
  }
}

# Submit transcription request
response = requests.post(base_url + "/v2/transcript", headers=headers, json=data)
transcript_id = response.json()["id"]
polling_endpoint = base_url + f"/v2/transcript/{transcript_id}"

# Poll transcription results
while True:
  transcript = requests.get(polling_endpoint, headers=headers).json()

  if transcript["status"] == "completed":
    break

  elif transcript["status"] == "error":
    raise RuntimeError(f"Transcription failed: {transcript['error']}")

  else:
    time.sleep(3)

# Access translated utterances
for utterance in transcript["utterances"]:
  print(f"Speaker {utterance['speaker']}:")
  print(f"  Original: {utterance['text'][:100]}...")
  print(f"  Spanish: {utterance['translated_texts']['es'][:100]}...")
  print()

import fetch from "node-fetch";

const baseUrl = "https://api.assemblyai.com";
const headers = {
  authorization: "YOUR_API_KEY",
};

const audioUrl = "https://assembly.ai/wildfires.mp3";

// Configure transcription with translation and speaker labels
const data = {
  audio_url: audioUrl,
  speech_models: ["universal-3-pro", "universal-2"],
  language_detection: true,
  speaker_labels: true, // Enable speaker labels
  speech_understanding: {
    request: {
      translation: {
        target_languages: ["es"],
        match_original_utterance: true, // Get translated text per utterance
        formal: true,
      },
    },
  },
};

async function transcribeWithTranslatedUtterances() {
  const response = await fetch(`${baseUrl}/v2/transcript`, {
    method: "POST",
    headers: {
      ...headers,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(data),
  });

  const transcript = await response.json();
  const transcriptId = transcript.id;
  const pollingEndpoint = `${baseUrl}/v2/transcript/${transcriptId}`;

  // Poll transcription results
  while (true) {
    const pollingResponse = await fetch(pollingEndpoint, { headers });
    const transcriptResult = await pollingResponse.json();

    if (transcriptResult.status === "completed") {
      // Access translated utterances
      for (const utterance of transcriptResult.utterances) {
        console.log(`Speaker ${utterance.speaker}:`);
        console.log(`  Original: ${utterance.text.substring(0, 100)}...`);
        console.log(
          `  Spanish: ${utterance.translated_texts.es.substring(0, 100)}...`
        );
        console.log();
      }
      break;
    } else if (transcriptResult.status === "error") {
      throw new Error(`Transcription failed: ${transcriptResult.error}`);
    } else {
      await new Promise((resolve) => setTimeout(resolve, 3000));
    }
  }
}

transcribeWithTranslatedUtterances();

Example response: Each utterance in the utterances array includes a translated_texts object with the translation for that specific speaker’s utterance:

{
  "utterances": [
    {
      "speaker": "A",
      "text": "Smoke from hundreds of wildfires in Canada is triggering air quality alerts...",
      "confidence": 0.9815734,
      "start": 240,
      "end": 26560,
      "words": [...],
      "translated_texts": {
        "es": "El humo de cientos de incendios forestales en Canadá está activando alertas de calidad del aire..."
      }
    },
    {
      "speaker": "B",
      "text": "Good morning.",
      "confidence": 0.98217773,
      "start": 28060,
      "end": 28620,
      "words": [...],
      "translated_texts": {
        "es": "Buenos días."
      }
    }
  ]
}

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,
    "language_detection": 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
        }
      }
    }
  }'

Key	Type	Required?	Description
`speech_understanding`	object	Yes	Container for speech understanding requests.
`speech_understanding.request`	object	Yes	The understanding request configuration.
`speech_understanding.request.translation`	object	Yes	Translation configuration.
`translation.target_languages`	array	Yes	Array of language codes to translate the transcript into. See the supported languages table for available language codes.
`translation.formal`	boolean	No	Whether to use formal language in translations. Defaults to `false`. When `true`, uses formal pronouns and grammatical forms.
`translation.match_original_utterance`	boolean	No	Whether to include translated texts for each utterance. Defaults to `false`. When `true`, returns a `translated_texts` key within each utterance in the `utterances` array. Requires `speaker_labels` to be set to `true` in the request.

Response

The Translation API returns your original transcript response with an additional translated_texts key containing the translations. When match_original_utterance is enabled with speaker_labels, each utterance in the utterances array will also include its own translated_texts key.

{
  "id": "735d90b6-2e8b-4748-b75d-d02b78eb7811",
  "status": "completed",
  "text": "Smoke from hundreds of wildfires in Canada is triggering air quality alerts throughout the US...",
  "translated_texts": {
    "es": "El humo de cientos de incendios forestales en Canadá está provocando alertas de calidad del aire en todo Estados Unidos...",
    "de": "Rauch von Hunderten von Waldbränden in Kanada löst in den gesamten USA Luftqualitätswarnungen aus..."
  },
  "speech_understanding": {
    "request": {
      "translation": {
        "formal": true,
        "target_languages": ["es", "de"]
      }
    },
    "response": {
      "translation": {
        "status": "success"
      }
    }
  }
}

Key	Type	Description
`translated_texts`	object	An object containing the translated texts, where each key is a language code and each value is the full translated transcript text.
`utterances[].translated_texts`	object	(When `match_original_utterance` is `true`) An object containing the translations for this specific utterance, with language codes as keys.
`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

Field	Standard Transcription	With Translation
`translated_texts`	Not present	Object with language codes as keys and translated texts as values
`speech_understanding`	Not present	Object containing the translation request and response details

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

Documentation Index

​Overview

​Quickstart

​Method 1: Transcribe and translate in one request

​Method 2: Transcribe and translate in separate requests

​Output format

​Translation with speaker labels

​API reference

​Request

​Method 1: Transcribe and translate in one request

​Method 2: Add translation to existing transcripts

​Response

​Key differences from standard transcription

Overview

Quickstart

Method 1: Transcribe and translate in one request

Method 2: Transcribe and translate in separate requests

Output format

Translation with speaker labels

API reference

Request

Method 1: Transcribe and translate in one request

Method 2: Add translation to existing transcripts

Response

Key differences from standard transcription