API des traductions

Obtenir les traductions d'un film

GET /3/movie/{movie_id}/translations renvoie une ligne par langue qui a du texte pour le film. Chaque ligne contient un objet data avec les champs traduits. L'appel n'accepte aucun paramètre de langue, car tout l'intérêt est de voir toutes les langues à la fois.

L'exemple trouve la ligne russe et affiche son titre et le début de son résumé.

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")
}

Paramètres

• movie_idcheminobligatoire
  Identifiant numérique du film, par exemple 550.
• api_keyrequêtel'un des deux
  Votre clé. Utilisez-la ou l'en-tête Authorization: Bearer.

Champs de la réponse

Exemple de réponse

Deux des 50 lignes sont montrées, et les résumés sont coupés.

{
  "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
      }
    }
  ]
}

Dans amodb, runtime vaut toujours 0 dans une ligne de traduction. Lisez la durée dans la fiche de détails du film.

Points de terminaison de traductions et leurs clés de données

Tous les chemins partagent la base https://api.amodb.dev/3. Chacun renvoie id et un tableau translations de la forme de ligne ci-dessus. Seules les clés à l'intérieur de data changent.

Les fiches de séries listent à peu près autant de langues que les films. Les lignes d'épisodes ne couvrent que les langues servies qui ont du texte pour cet épisode, de 2 à 14 dans les échantillons vérifiés. Traitez une clé manquante comme une valeur vide, et ignorez les clés que vous ne connaissez pas. Voir séries TV pour les fiches parentes.

amodb ne propose pas de traductions pour les personnes ni pour les collections. La biographie d'une personne suit le paramètre language de l'appel de détails de la personne, et le résumé d'une collection est fourni tel que stocké.

Se replier quand le texte manque

Un titre peut exister en 14 langues et avoir quand même un résumé vide dans celle que votre utilisateur a choisie. Parcourez une chaîne de langues, prenez la première valeur non vide et retenez de quelle langue elle vient.

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

Pour une série, passez 'name' comme champ au lieu de 'title'. Signalez dans votre interface le texte issu d'une langue de repli, pour que l'utilisateur sache pourquoi une page ukrainienne affiche un synopsis en anglais.

Translations ou paramètre language

Pour les balises qu'accepte language, voir langues. Toute autre balise se replie sur l'anglais lors d'un appel de détails.

Erreurs

Un identifiant de film ou de série qui n'existe pas n'est pas une erreur sur ce chemin : il répond 200 avec "translations": [], alors que le chemin de détails répond 404. Plus d'informations sur erreurs et limites de débit.

Remarques pratiques

• Un appel remplace jusqu'à 14 appels de détails. Utilisez-le quand vous avez besoin de plus de deux langues du même titre.
• Les lignes sont triées par code de langue, ce qui n'est pas un ordre de priorité. Choisissez les lignes par iso_639_1, jamais par position dans le tableau.
• Les appels de type détails sont mis en cache 6 heures en périphérie : un cache client de même durée ne coûte donc rien en fraîcheur.
• Les titres originaux dans d'autres écritures, comme le japonais ou le coréen, sont toujours disponibles dans original_title et original_name sur la fiche de détails.
• Pour ajouter les traductions à un appel de détails, passez append_to_response=translations et lisez le même tableau dans la réponse. Cela fonctionne pour les films, les séries et les épisodes. Le bloc ajouté n'a pas d'id.