> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supadata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Translation

> Use this API endpoint to fetch text transcript from a YouTube video in various formats and languages.

Translation extends Supadata's [YouTube Transcript API](https://supadata.ai/youtube-transcript-api), letting you return a video's transcript in a different language.

## Quick Start

### Request

<CodeGroup>
  ```js Node theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
  import {
    Supadata,
    Transcript
  } from '@supadata/js';

  // Initialize the client
  const supadata = new Supadata({
    apiKey: 'YOUR_API_KEY',
  });

  const translated: Transcript = await supadata.youtube.translate({
    videoId: 'dQw4w9WgXcQ',
    lang: 'es',
  });
  ```

  ```python Python theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
  from supadata import Supadata, SupadataError

  # Initialize the client
  supadata = Supadata(api_key="YOUR_API_KEY")

  translated = supadata.youtube.translate(
      video_id="dQw4w9WgXcQ",
      lang="es"
  )
  print(f"Got translated transcript in {translated.lang}")
  ```

  ```bash cURL theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
  curl -X GET 'https://api.supadata.ai/v1/youtube/transcript/translate?videoId=dQw4w9WgXcQ&lang=es&text=true' \
    -H 'x-api-key: YOUR_API_KEY'
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "content": "Nunca voy a abandonarte, nunca voy a decepcionarte…",
  "lang": "es"
}
```

<Info>
  This endpoint has longer than usual response times. See [Latency](#latency)
  for more details.
</Info>

## Specification

### Endpoint

`GET https://api.supadata.ai/v1/youtube/transcript/translate`

Each request requires an `x-api-key` header with your API key available after signing up. Get your API key [here](https://dash.supadata.ai/organizations/api-key).

### Query Parameters

| Parameter | Type    | Required | Description                                                                             |
| --------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| url       | string  | Yes\*    | YouTube video URL. See [Supported YouTube URL Formats](#supported-youtube-url-formats). |
| videoId   | string  | Yes\*    | YouTube video ID. Alternative to URL.                                                   |
| lang      | string  | Yes      | ISO 639-1 language code of the translation                                              |
| text      | boolean | No       | When true, returns plain text transcript. Default: false                                |
| chunkSize | number  | No       | Maximum characters per transcript chunk (only when text=false)                          |

\* Either `url` or `videoId` must be provided

### Response Format

**When `text=true`:**

```typescript theme={null}
{
  "content": string,
  "lang": string    // ISO 639-1 language code
}
```

**When `text=false`:**

```typescript theme={null}
{
  "content": [
    {
      "text": string,     // Transcript segment
      "offset": number,   // Start time in milliseconds
      "duration": number, // Duration in milliseconds
      "lang": string      // ISO 639-1 language code of chunk
    }
  ],
  "lang": string          // ISO 639-1 language code of transcript
}
```

### Latency

Due to the duration of transcript translation tasks, the endpoint may take 20 or more seconds to complete. Please make sure to increase the request timeout in your application.

### Error Codes

The API returns HTTP status codes and error codes. See this [page](/errors) for more details.

### Supported YouTube URL Formats

`url` parameter supports various YouTube URL formats. See this [page](/youtube/supported-url-formats) for more details.

## Pricing

* 1 minute of transcript = 30 credits