# API de metadados de filmes multilíngue

> Esta API multilíngue de metadados de filmes entrega títulos, sinopses, slogans, nomes de gêneros e biografias em 14 idiomas: inglês, russo, ucraniano, bielorrusso, chinês, português, búlgaro, hebraico, tcheco, romeno, francês, polonês, italiano e espanhol. Passe uma tag do TMDB como ru-RU no parâmetro language.

## Obtenha dados de filmes em 14 idiomas

`GET /3/movie/{movie_id}?language=ru-RU` retorna o título, a sinopse, o slogan e os nomes dos gêneros em russo. O parâmetro `language` aceita tags do TMDB como `ru-RU` ou `pt-BR` e funciona em todo endpoint que retorna texto. Os ids são os mesmos em todos os idiomas, então uma linha no seu banco de dados serve a todos eles.

Você recebe 14 idiomas com uma chave, o `original_title` de todo filme, um endpoint de traduções que lista todos os idiomas de um título e nomes de gêneros localizados. A lista completa está em [idiomas](https://amodb.dev/pt/languages/).

## Os 14 idiomas atendidos

| Idioma      | Código | Exemplo de tag |
| ----------- | ------ | -------------- |
| Inglês      | `en`   | `en-US`        |
| Russo       | `ru`   | `ru-RU`        |
| Ucraniano   | `uk`   | `uk-UA`        |
| Bielorrusso | `be`   | `be-BY`        |
| Chinês      | `zh`   | `zh-CN`        |
| Português   | `pt`   | `pt-BR`        |
| Búlgaro     | `bg`   | `bg-BG`        |
| Hebraico    | `he`   | `he-IL`        |
| Tcheco      | `cs`   | `cs-CZ`        |
| Romeno      | `ro`   | `ro-RO`        |
| Francês     | `fr`   | `fr-FR`        |
| Polonês     | `pl`   | `pl-PL`        |
| Italiano    | `it`   | `it-IT`        |
| Espanhol    | `es`   | `es-ES`        |

Qualquer outra tag volta para `en`. Japonês e coreano não são atendidos como idiomas de interface. Os títulos originais deles continuam voltando em `original_title` nos filmes e em `original_name` nas séries de TV.

## Quais dados você recebe

| Endpoint                                   | Conteúdo localizado                                                  |
| ------------------------------------------ | -------------------------------------------------------------------- |
| `GET /3/movie/{movie_id}`                  | `title`, `overview`, `tagline`, nomes de gêneros                     |
| `GET /3/tv/{tv_id}`                        | `name`, `overview`, `tagline`, nomes de gêneros                      |
| `GET /3/tv/{tv_id}/season/{season_number}` | `name` e `overview` da temporada e dos episódios                     |
| `GET /3/person/{person_id}`                | `biography`                                                          |
| `GET /3/genre/movie/list`                  | Nomes de gêneros para filtros e menus                                |
| `GET /3/movie/{movie_id}/translations`     | Todos os idiomas de um título em uma só resposta                     |
| `GET /3/movie/{movie_id}/images`           | Pôsteres marcados por idioma, filtrados com `include_image_language` |
| `GET /3/movie/{movie_id}/videos`           | Vídeos marcados por `iso_639_1`, todos os idiomas em uma só resposta |

## Comece em 3 passos

1. Escolha um plano em [preços](https://amodb.dev/pt/pricing/). O número de idiomas não muda com o plano, só a taxa de requisições.
2. Crie uma chave no painel da sua conta.
3. Chame qualquer endpoint com uma tag em `language` e envie a chave como `api_key` ou como header Bearer.

## Exemplo de requisição

O exemplo em bash imprime o título de Fight Club (id `550`) em três idiomas. Ele usa `jq` para imprimir um campo. O exemplo em PHP pede bielorrusso e volta para o inglês quando a sinopse está em branco.

```bash
for lang in en-US ru-RU he-IL; do
  curl -s "https://api.amodb.dev/3/movie/550?language=$lang" \
    -H "Authorization: Bearer $AMODB_KEY" | jq -r '.title'
done
```

```php
<?php
function amodb(string $path, array $query = []): array
{
    $url = 'https://api.amodb.dev/3' . $path . '?' . http_build_query($query);
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => 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");
    }
    return json_decode($body, true);
}

function localizedMovie(int $id, string $lang): array
{
    $movie = amodb("/movie/$id", ['language' => $lang]);
    $movie['text_language'] = $lang;
    if (trim($movie['overview'] ?? '') === '') {
        $fallback = amodb("/movie/$id", ['language' => 'en-US']);
        $movie['overview'] = $fallback['overview'] ?? '';
        $movie['text_language'] = 'en-US';
    }
    return $movie;
}

$movie = localizedMovie(550, 'be-BY');
echo $movie['title'], ' (', $movie['original_title'], ')', PHP_EOL;
echo '[', $movie['text_language'], '] ', $movie['overview'], PHP_EOL;
```

Resposta para `language=ru-RU`, reduzida a alguns campos. A chave `text_language` no exemplo em PHP é adicionada pelo seu código, não pela API.

```json
{
  "genres": [
    {
      "id": 18,
      "name": "драма"
    },
    {
      "id": 53,
      "name": "триллер"
    }
  ],
  "id": 550,
  "original_language": "en",
  "original_title": "Fight Club",
  "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из мучительно скучной жизни. Однажды в очередной командировке он...",
  "poster_path": "/66RvLrRJTm4J8l3uHXWF09AICol.jpg",
  "tagline": "«Интриги. Хаос. Мыло»",
  "title": "Бойцовский клуб"
}
```

## Alternativa quando um campo está vazio

Nem todo título tem texto em todos os idiomas. Uma `overview` pode voltar vazia quando não existe tradução, e um `title` ou `tagline` pode voltar em inglês. A API não inventa texto. Use uma ordem fixa para que a página sempre mostre algo:

1. Peça o idioma que você exibe.
2. Se um campo estiver vazio, peça `en-US` para o mesmo id ou leia a entrada em inglês da lista de traduções.
3. Se o título estiver vazio, mostre `original_title`.
4. Guarde de qual idioma cada campo veio, para poder tentar de novo depois.

O cache de borda guarda uma cópia por idioma para cada caminho em cache, então a alternativa em inglês de um título popular costuma ser servida do cache.

## Liste todas as traduções de um título

`GET /3/movie/{movie_id}/translations` retorna um array `translations`, com uma entrada por idioma que tem dados. A lista pode ser maior que os 14 idiomas atendidos: Fight Club tem 50 entradas. Use-a para montar um seletor de idioma ou para guardar todos os textos de um título em uma só linha.

| Campo                                                                      | Significado                               |
| -------------------------------------------------------------------------- | ----------------------------------------- |
| `iso_639_1`, `iso_3166_1`                                                  | Códigos de idioma e de país               |
| `english_name`                                                             | Nome do idioma em inglês                  |
| `data.title` (filmes) ou `data.name` (TV), `data.overview`, `data.tagline` | Texto localizado, o título pode vir vazio |
| `data.homepage`, `data.runtime`                                            | Valores opcionais dessa tradução          |

O mesmo endpoint existe para séries de TV e episódios. As entradas de TV trazem `data.name` e não têm `runtime`, e as entradas de episódio trazem só `name` e `overview`. As temporadas respondem com uma lista vazia, e pessoas e coleções não têm endpoint de traduções. Os detalhes estão em [traduções](https://amodb.dev/pt/translations/). Uma chamada de traduções substitui até 14 chamadas de detalhes quando você quer todos os idiomas de uma vez.

## Pôsteres e vídeos por idioma

Imagens e vídeos têm suas próprias tags de idioma em `iso_639_1`. Nos endpoints de imagens, passe uma lista separada por vírgulas e adicione `null` para itens sem idioma, como pôsteres sem texto. A resposta contém os itens correspondentes, então classifique-os no seu código.

| Parâmetro                | Usado em             | Exemplo      |
| ------------------------ | -------------------- | ------------ |
| `include_image_language` | Endpoints de imagens | `ru,en,null` |

Os endpoints de vídeos retornam todos os idiomas em uma só resposta e ignoram `include_video_language`, então filtre você mesmo por `iso_639_1`. Veja [imagens](https://amodb.dev/pt/images-api/) para tamanhos e a CDN.

## Hebraico e texto da direita para a esquerda

O hebraico é o único idioma da direita para a esquerda entre os 14. Trate isso na página, não nos dados:

- Defina `lang="he"` e `dir="rtl"` no elemento que contém o texto.
- Envolva títulos em alfabeto latino dentro de texto hebraico em um elemento `<bdi>`, para que a pontuação não pule para o lado errado.
- Use propriedades lógicas de CSS como `margin-inline-start` em vez de esquerda e direita.

## Como se compara

| Recurso                         | Fazer scraping das páginas            | Dataset só em inglês      | amodb                             |
| ------------------------------- | ------------------------------------- | ------------------------- | --------------------------------- |
| Idiomas                         | Uma localidade do site por requisição | Inglês                    | 14 idiomas com `language`         |
| Mesmo id entre idiomas          | URLs diferentes por localidade        | Não se aplica             | O mesmo id numérico em todo lugar |
| Todas as traduções de um título | Buscar a página de cada localidade    | Não se aplica             | Uma chamada `translations`        |
| Pôsteres localizados            | URLs de imagem por localidade         | Veja a documentação deles | Filtro `include_image_language`   |
| Título original                 | Extrair do texto da página            | Veja a documentação deles | `original_title`, `original_name` |

## Preços

O conjunto de idiomas é o mesmo em todos os planos, então você paga só pela taxa e pelo período. Compre 1, 3, 6, 12 ou 24 meses pré-pagos, com 0, 10, 20, 30 ou 40 por cento de desconto nos mais longos e sem renovação automática. Os planos de 20, 40 e 120 requisições por minuto incluem todos os idiomas e todos os endpoints. Um site em cinco idiomas precisa de até cinco chamadas de detalhes por título, e as requisições repetidas são servidas do cache de borda por 6 horas. Sem plano gratuito. Veja [preços](https://amodb.dev/pt/pricing/).

## Perguntas e respostas

### Quais idiomas a API atende?

Catorze: inglês, russo, ucraniano, bielorrusso, chinês, português, búlgaro, hebraico, tcheco, romeno, francês, polonês, italiano e espanhol, com os códigos en ru uk be zh pt bg he cs ro fr pl it es.

### O que acontece se eu enviar uma tag de idioma que não é atendida?

A resposta volta para o inglês. Uma tag como ja-JP retorna texto em inglês, enquanto o título original em japonês continua chegando em original_title nos filmes e em original_name nas séries de TV.

### Posso obter todas as traduções de um título em uma só requisição?

Sim. GET /3/movie/{movie_id}/translations lista uma entrada por idioma que tem dados, cada uma com title, overview, tagline, homepage e runtime. Séries de TV e episódios têm o mesmo endpoint, com name no lugar de title. Temporadas, pessoas e coleções não têm traduções.

### Como trato uma sinopse ausente no idioma escolhido?

Verifique se há uma string vazia, depois peça o mesmo id com en-US ou leia a entrada em inglês da lista de traduções. Mostre original_title como último recurso e marque o texto como inglês. Títulos e slogans já podem voltar em inglês.

### Os pôsteres também são localizados?

Os pôsteres têm uma tag de idioma. Peça-os com include_image_language, por exemplo ru,en,null, e classifique as correspondências no seu código. Os arquivos de imagem vêm de img.amodb.dev e não precisam de chave.

## Páginas relacionadas

- [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 traduções](https://amodb.dev/pt/translations/): API de traduções de filmes com caminhos do TMDB v3: leia todos os títulos, sinopses e taglines de um filme, série ou episódio em todos os idiomas.
- [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 imagens e host de imagens](https://amodb.dev/pt/images-api/): API de imagens de filmes com caminhos do TMDB v3: liste pôsteres, backdrops, logos e stills por título e carregue-os de img.amodb.dev em 10 tamanhos, sem chave.
- [Início rápido](https://amodb.dev/pt/quickstart/): Faça sua primeira chamada ao amodb: obtenha uma chave, peça um filme em curl, JavaScript, Python, PHP ou Go e carregue o pôster. Menos de 2 minutos.

Atualizado: 2026-10-18. Source: https://amodb.dev/pt/multilingual-movie-metadata-api/