# API de traduções > Os endpoints de traduções retornam todas as versões de idioma de um registro em uma resposta: título ou nome, sinopse, tagline e homepage para filmes e séries, nome e sinopse para episódios. Cada linha traz iso_639_1, iso_3166_1 e english_name. Use para ler idiomas que o parâmetro language não atende ou para montar uma cadeia de fallback. ## Endpoint `GET /3/movie/{movie_id}/translations` ```bash curl "https://api.amodb.dev/3/movie/550/translations" \ -H "Authorization: Bearer $AMODB_KEY" ``` Resposta: ```json { "id": 550, "translations": [ { "iso_3166_1": "AR", "iso_639_1": "ar", "name": "العربية", "english_name": "Arabic", "data": { "title": "نادي القتال", "overview": "يعيش موظف مكتبي يعاني من الأرق والملل حياة روتينية فارغة، إلى أن يلتقي بالرجل الغامض تايلر ديردن، الذي يختلف عنه تمامًا ويؤمن بأن التحرر من قيود المجتمع يبدأ برفض الحياة التقليدية. تنشأ بينهما صداقة غريبة تقودهما إلى تأسيس نادٍ سري يتجمع في...", "homepage": "", "tagline": "نادي القتال هو نادي يوجد في العقل الباطن لكل واحد منا !", "runtime": 0 } }, { "iso_3166_1": "AZ", "iso_639_1": "az", "name": "Azərbaycan", "english_name": "Azerbaijani", "data": { "title": "Döyüş Klubu", "overview": "Xəyalları olmayan bir gənc yuxusuzluğa qarşı mübarizə aparır, bəlkə də boz və gündəlik həyatı ilə cansıxıcılığının nəticəsidir. Təyyarə gəzintisində o, çox xüsusi bir fəlsəfəyə sahib olan xarizmatik sabun satıcısı Tyler Durden ilə tanış olu...", "homepage": "", "tagline": "", "runtime": 0 } }, { "iso_3166_1": "BY", "iso_639_1": "be", "name": "Беларуская", "english_name": "Belarusian", "data": { "title": "Байцоўскі клуб", "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy. Their concept catches on, with underground \"fight clubs\" forming in every town, until an eccentric gets in the wa...", "homepage": "", "tagline": "", "runtime": 0 } } ] } ``` ## Obter as traduções de um filme `GET /3/movie/{movie_id}/translations` retorna uma linha por idioma que tem texto para o filme. Cada linha traz um objeto `data` com os campos traduzidos. A chamada não aceita parâmetro de idioma, porque a ideia é justamente ver todos os idiomas de uma vez. O exemplo encontra a linha em russo e imprime o título e o começo da sinopse. ```bash curl -s "https://api.amodb.dev/3/movie/550/translations" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/movie/550/translations'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const { translations } = await res.json(); const ru = translations.find((t) => t.iso_639_1 === 'ru'); console.log(ru ? `${ru.data.title}: ${ru.data.overview.slice(0, 80)}` : 'no Russian row'); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/movie/550/translations", headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() ru = next((t for t in r.json()["translations"] if t["iso_639_1"] == "ru"), None) print(f"{ru['data']['title']}: {ru['data']['overview'][:80]}" if ru else "no Russian row") ``` ```php true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status !== 200) { throw new RuntimeException("amodb returned $status"); } foreach (json_decode($body, true)['translations'] as $t) { if ($t['iso_639_1'] === 'ru') { echo $t['data']['title'], ': ', mb_substr($t['data']['overview'], 0, 80), PHP_EOL; exit; } } echo 'no Russian row', PHP_EOL; ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Translations struct { Translations []struct { ISO6391 string `json:"iso_639_1"` Data struct { Title string `json:"title"` Overview string `json:"overview"` } `json:"data"` } `json:"translations"` } func main() { req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/550/translations", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var t Translations if err := json.NewDecoder(res.Body).Decode(&t); err != nil { panic(err) } for _, row := range t.Translations { if row.ISO6391 == "ru" { text := []rune(row.Data.Overview) if len(text) > 80 { text = text[:80] } fmt.Printf("%s: %s\n", row.Data.Title, string(text)) return } } fmt.Println("no Russian row") } ``` ### Parâmetros | Parâmetro | Em | Obrigatório | Descrição | | ---------- | -------- | ----------- | ------------------------------------------------------------------ | | `movie_id` | caminho | sim | Id numérico do filme, por exemplo `550`. | | `api_key` | consulta | um dos dois | Sua chave. Use este parâmetro ou o header `Authorization: Bearer`. | ### Campos da resposta | Campo | Tipo | Observações | | ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | inteiro | O id do filme. | | `translations` | array | Uma linha por idioma que tem texto, ordenada pelo código do idioma. O filme 550 retorna 50 linhas. | | `translations[].iso_3166_1` | string | Código do país que acompanha o idioma, como `US` para `en` ou `BR` para `pt`. Para idiomas fora dos 14 atendidos, repete o código do idioma em maiúsculas. | | `translations[].iso_639_1` | string | Código do idioma, como `ru` ou `pt`. Único no array. | | `translations[].name` | string | O idioma escrito nesse próprio idioma. | | `translations[].english_name` | string | O nome do idioma em inglês. | | `translations[].data` | objeto | Os campos traduzidos. As chaves dependem do recurso, veja a tabela abaixo. | ### Exemplo de resposta Duas das 50 linhas são mostradas, e as sinopses estão cortadas. ```json { "id": 550, "translations": [ { "iso_3166_1": "US", "iso_639_1": "en", "name": "English", "english_name": "English", "data": { "title": "Fight Club", "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy....", "homepage": "https://www.20thcenturystudios.com/movies/fight-club", "tagline": "Mischief. Mayhem. Soap.", "runtime": 0 } }, { "iso_3166_1": "RU", "iso_639_1": "ru", "name": "Русский", "english_name": "Russian", "data": { "title": "Бойцовский клуб", "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из мучительно скучной жизни. Однажд...", "homepage": "https://www.20thcenturystudios.com/movies/fight-club", "tagline": "«Интриги. Хаос. Мыло»", "runtime": 0 } } ] } ``` No amodb, `runtime` é sempre 0 em uma linha de tradução. Leia a duração no registro de [detalhes do filme](https://amodb.dev/pt/movies/). ## Endpoints de traduções e suas chaves de dados Todos os caminhos compartilham a base `https://api.amodb.dev/3`. Cada um retorna `id` e um array `translations` com o formato de linha acima. Só mudam as chaves dentro de `data`. | Método e caminho | Chaves de `data` | | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `GET /movie/{movie_id}/translations` | `title`, `overview`, `homepage`, `tagline`, `runtime` (sempre 0) | | `GET /tv/{series_id}/translations` | `name`, `overview`, `homepage`, `tagline` | | `GET /tv/{series_id}/season/{season_number}/translations` | nenhuma, o array vem sempre vazio | | `GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/translations` | `name`, `overview` | Os registros de séries listam quase tantos idiomas quanto os de filmes. As linhas de episódios cobrem só os idiomas atendidos que têm texto para aquele episódio, de 2 a 14 nas amostras verificadas. Trate uma chave ausente como um valor vazio e ignore as chaves que você não conhece. Veja [séries de TV](https://amodb.dev/pt/tv-series/) para os registros pai. O amodb não oferece traduções para pessoas nem para coleções. A biografia de uma pessoa segue o parâmetro `language` da chamada de detalhes da pessoa, e a sinopse de uma coleção vem como está guardada. ## Recorrer a outro idioma quando falta texto Um título pode existir em 14 idiomas e ainda assim ter a sinopse vazia no idioma que seu usuário escolheu. Percorra uma cadeia de idiomas, pegue o primeiro valor não vazio e lembre de qual idioma ele veio. ```js function pickText(translations, wanted, field) { for (const code of [...wanted, 'en']) { const row = translations.find((t) => t.iso_639_1 === code); const value = row?.data?.[field]; if (value) return { code, value }; } return null; } // Prefer Ukrainian, then Russian, then English. // const hit = pickText(translations, ['uk', 'ru'], 'overview'); ``` Para uma série, passe `'name'` como o campo no lugar de `'title'`. Marque na sua interface o texto vindo de um idioma de fallback, para o usuário entender por que uma página em ucraniano mostra uma sinopse em inglês. ## Traduções ou o parâmetro language | Necessidade | Use | | ---------------------------------------------------- | ---------------------------------------------- | | Mostrar um idioma a um usuário | `language` na chamada de detalhes | | Listar todos os idiomas de um título em um editor | Este endpoint | | Ler um idioma que `language` não atende, como `ja` | Este endpoint, escolha a linha por `iso_639_1` | | Ver quais dos 14 idiomas atendidos têm texto | Este endpoint, compare `iso_639_1` | | Montar links de idiomas alternativos para uma página | Este endpoint, leia os códigos presentes | Para as tags que `language` aceita, veja [idiomas](https://amodb.dev/pt/languages/). Qualquer outra tag volta para o inglês em uma chamada de detalhes. ## Erros | HTTP | status_code | Quando | | ---- | ----------- | --------------------------------------------------------------------------------------------------- | | 401 | 7 | A chave está ausente ou incorreta. | | 402 | 36 | O período do plano terminou. | | 404 | 34 | Nenhuma temporada ou episódio com esse id, ou um id que não é um número. | | 405 | 37 | Você usou um método de escrita em um caminho de traduções. | | 429 | 25 | Você passou do seu limite de requisições por minuto. Espere os segundos indicados em `Retry-After`. | Um id de filme ou de série que não existe não é um erro neste caminho: ele responde 200 com `"translations": []`, enquanto o caminho de detalhes responde 404. Mais em [erros](https://amodb.dev/pt/errors/) e [limites de requisições](https://amodb.dev/pt/rate-limits/). ## Notas práticas - Uma chamada substitui até 14 chamadas de detalhes. Use quando precisar de mais de dois idiomas do mesmo título. - As linhas são ordenadas pelo código do idioma, que não é uma ordem de prioridade. Escolha as linhas por `iso_639_1`, nunca pela posição no array. - Chamadas do tipo detalhes têm cache de borda de 6 horas, então um cache de cliente do mesmo tamanho não custa nada em atualidade. - Os títulos originais em outras escritas, como japonês ou coreano, estão sempre disponíveis em `original_title` e `original_name` no registro de detalhes. - Para juntar traduções a uma chamada de detalhes, passe `append_to_response=translations` e leia o mesmo array na resposta. Funciona para filmes, séries e episódios. O bloco acrescentado não tem `id`. ## Perguntas e respostas ### Quando devo usar translations em vez do parâmetro language? Use language quando mostrar um idioma a um usuário. Use translations quando precisar de vários idiomas de um título ao mesmo tempo, por exemplo em uma tela de edição, em páginas de idiomas alternativos ou em uma checagem de cobertura. Ele também retorna idiomas que language não atende, como ja (japonês) ou de (alemão). ### Qual é a diferença entre iso_639_1 e iso_3166_1? iso_639_1 é o código do idioma, como pt. iso_3166_1 é o país que o acompanha, como BR. Para idiomas fora dos 14 atendidos, ele repete o código do idioma em maiúsculas, por exemplo DA para da, então compare sempre por iso_639_1. ### Por que um campo está vazio dentro de data? Uma string vazia ou um zero significa que não existe texto para esse campo nesse idioma. Não o mostre. Recorra ao próximo idioma da sua cadeia, em geral o inglês, ou ao título original. ### Quais idiomas o endpoint cobre? Os registros de filmes e séries listam todos os idiomas que o catálogo tem, muitas vezes de 40 a 80 linhas. Isso inclui os 14 atendidos: en, ru, uk, be, zh, pt, bg, he, cs, ro, fr, pl, it e es. Os episódios listam só alguns desses 14. ## Páginas relacionadas - [API de detalhes de filmes](https://amodb.dev/pt/movies/): API de detalhes de filmes com caminhos e JSON do TMDB v3. Busque um filme por id e junte créditos, avaliações e moods com append_to_response, em 14 idiomas. - [API de séries de TV](https://amodb.dev/pt/tv-series/): API de séries de TV com os mesmos caminhos e JSON do TMDB v3. Busque uma série por id com temporadas, emissoras, próximo episódio e classificações. - [API de detalhes de pessoas](https://amodb.dev/pt/people/): API de detalhes de pessoas com os caminhos e o JSON do TMDB v3. Busque um ator ou membro da equipe por id, com biografia, filmografia e ids externos. - [API de coleções](https://amodb.dev/pt/collections/): API de coleções de filmes com caminhos do TMDB v3: busque uma franquia por id com todas as partes, leia belongs_to_collection de um filme e pesquise por nome. - [Idiomas](https://amodb.dev/pt/languages/): O amodb serve títulos, sinopses e nomes em 14 idiomas. Passe uma tag no estilo TMDB como ru-RU ou pt-BR em language; qualquer outra tag volta para o inglês. - [API de metadados de filmes multilíngue](https://amodb.dev/pt/multilingual-movie-metadata-api/): API de metadados de filmes com 14 idiomas. Use tags do TMDB, leia todas as traduções, volte ao inglês e trate o hebraico da direita para a esquerda. Atualizado: 2026-10-18. Source: https://amodb.dev/pt/translations/