API tłumaczeń

Pobieranie tłumaczeń filmu

GET /3/movie/{movie_id}/translations zwraca jeden wiersz na każdy język, który ma tekst dla filmu. Każdy wiersz zawiera obiekt data z przetłumaczonymi polami. Wywołanie nie przyjmuje parametru języka, bo cały sens polega na zobaczeniu wszystkich języków naraz.

Przykład znajduje wiersz rosyjski i wypisuje jego tytuł oraz początek opisu.

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

Parametry

• movie_idpathwymagany
  Numeryczne ID filmu, na przykład 550.
• api_keyqueryjeden z dwóch
  Twój klucz. Użyj go albo nagłówka Authorization: Bearer.

Pola odpowiedzi

Przykładowa odpowiedź

Pokazano dwa z 50 wierszy, a opisy są przycięte.

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

W amodb runtime w wierszu tłumaczenia to zawsze 0. Czas trwania odczytaj z rekordu szczegółów filmu.

Endpointy tłumaczeń i ich klucze data

Wszystkie ścieżki mają wspólną bazę https://api.amodb.dev/3. Każda zwraca id i tablicę translations o kształcie wiersza powyżej. Zmieniają się tylko klucze wewnątrz data.

Rekordy seriali wymieniają mniej więcej tyle języków co filmy. Wiersze odcinków obejmują tylko obsługiwane języki, które mają tekst dla danego odcinka, od 2 do 14 w sprawdzonych próbkach. Brakujący klucz traktuj jak pustą wartość, a nieznane klucze ignoruj. Rekordy nadrzędne zobacz w seriale.

amodb nie udostępnia tłumaczeń dla osób ani kolekcji. Biografia osoby zależy od parametru language w wywołaniu szczegółów osoby, a opis kolekcji przychodzi tak, jak zapisano.

Zapas, gdy brakuje tekstu

Tytuł może istnieć w 14 językach i mimo to mieć pusty opis w języku wybranym przez użytkownika. Przejdź łańcuch języków, weź pierwszą niepustą wartość i zapamiętaj, z jakiego języka pochodzi.

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

Dla serialu przekaż jako pole 'name' zamiast 'title'. Oznacz w interfejsie tekst z języka zapasowego, by użytkownik wiedział, dlaczego ukraińska strona pokazuje angielskie streszczenie.

Tłumaczenia czy parametr language

Tagi, które przyjmuje language, zobacz w języki. Każdy inny tag wraca do angielskiego w wywołaniu szczegółów.

Błędy

Nieistniejące ID filmu lub serialu nie jest na tej ścieżce błędem: odpowiada 200 z "translations": [], podczas gdy ścieżka szczegółów odpowiada 404. Więcej w błędy i limity żądań.

Praktyczne uwagi

• Jedno wywołanie zastępuje do 14 wywołań szczegółów. Użyj go, gdy potrzebujesz więcej niż dwóch języków tego samego tytułu.
• Wiersze są posortowane według kodu języka, co nie jest kolejnością priorytetu. Wybieraj wiersze po iso_639_1, nigdy po pozycji w tablicy.
• Wywołania typu szczegółów są w cache na edge przez 6 godzin, więc cache klienta o tej samej długości nic nie kosztuje pod względem świeżości.
• Tytuły oryginalne w innych pismach, takich jak japońskie czy koreańskie, są zawsze dostępne w original_title i original_name w rekordzie szczegółów.
• Aby dodać tłumaczenia do wywołania szczegółów, przekaż append_to_response=translations i odczytaj tę samą tablicę z odpowiedzi. Działa dla filmów, seriali i odcinków. Dołączony blok nie ma id.