API de traduções

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.

curl -s "https://api.amodb.dev/3/movie/550/translations" \
  -H "Authorization: Bearer $AMODB_KEY"

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');

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
$ch = curl_init('https://api.amodb.dev/3/movie/550/translations');
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");
}
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;

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

• movie_idcaminhoobrigatório
  Id numérico do filme, por exemplo 550.
• api_keyconsultaum dos dois
  Sua chave. Use este parâmetro ou o header Authorization: Bearer.

Campos da resposta

Exemplo de resposta

Duas das 50 linhas são mostradas, e as sinopses estão cortadas.

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

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.

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

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

Para as tags que language aceita, veja idiomas. Qualquer outra tag volta para o inglês em uma chamada de detalhes.

Erros

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 e limites de requisições.

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.