# API di metadati film multilingue

> Questa API di metadati film multilingue serve titoli, trame, slogan, nomi dei generi e biografie in 14 lingue: inglese, russo, ucraino, bielorusso, cinese, portoghese, bulgaro, ebraico, ceco, rumeno, francese, polacco, italiano e spagnolo. Passa un tag TMDB come ru-RU nel parametro language.

## Ottenere i dati dei film in 14 lingue

`GET /3/movie/{movie_id}?language=ru-RU` restituisce titolo, trama, slogan e nomi dei generi in russo. Il parametro `language` accetta tag TMDB come `ru-RU` o `pt-BR` e funziona su ogni endpoint che restituisce testo. Gli ID restano uguali in ogni lingua, quindi una sola riga nel tuo database le serve tutte.

Ottieni 14 lingue con una sola chiave, l'`original_title` di ogni film, un endpoint di traduzioni che elenca tutte le lingue di un titolo e nomi dei generi localizzati. L'elenco completo è nella pagina [lingue](https://amodb.dev/it/languages/).

## Le 14 lingue servite

| Lingua     | Codice | Tag di esempio |
| ---------- | ------ | -------------- |
| Inglese    | `en`   | `en-US`        |
| Russo      | `ru`   | `ru-RU`        |
| Ucraino    | `uk`   | `uk-UA`        |
| Bielorusso | `be`   | `be-BY`        |
| Cinese     | `zh`   | `zh-CN`        |
| Portoghese | `pt`   | `pt-BR`        |
| Bulgaro    | `bg`   | `bg-BG`        |
| Ebraico    | `he`   | `he-IL`        |
| Ceco       | `cs`   | `cs-CZ`        |
| Rumeno     | `ro`   | `ro-RO`        |
| Francese   | `fr`   | `fr-FR`        |
| Polacco    | `pl`   | `pl-PL`        |
| Italiano   | `it`   | `it-IT`        |
| Spagnolo   | `es`   | `es-ES`        |

Qualsiasi altro tag ripiega su `en`. Giapponese e coreano non sono serviti come lingue dell'interfaccia. I loro titoli originali tornano comunque in `original_title` per i film e `original_name` per le serie TV.

## Quali dati ottieni

| Endpoint                                   | Contenuto localizzato                                                   |
| ------------------------------------------ | ----------------------------------------------------------------------- |
| `GET /3/movie/{movie_id}`                  | `title`, `overview`, `tagline`, nomi dei generi                         |
| `GET /3/tv/{tv_id}`                        | `name`, `overview`, `tagline`, nomi dei generi                          |
| `GET /3/tv/{tv_id}/season/{season_number}` | `name` e `overview` di stagioni ed episodi                              |
| `GET /3/person/{person_id}`                | `biography`                                                             |
| `GET /3/genre/movie/list`                  | Nomi dei generi per filtri e menu                                       |
| `GET /3/movie/{movie_id}/translations`     | Tutte le lingue di un titolo in una sola risposta                       |
| `GET /3/movie/{movie_id}/images`           | Locandine etichettate per lingua, filtrate con `include_image_language` |
| `GET /3/movie/{movie_id}/videos`           | Video etichettati con `iso_639_1`, tutte le lingue in una sola risposta |

## Parti in 3 passaggi

1. Scegli un piano nella pagina dei [prezzi](https://amodb.dev/it/pricing/). Il numero di lingue non cambia con il piano, cambia solo la frequenza delle richieste.
2. Crea una chiave nella dashboard del tuo account.
3. Chiama qualsiasi endpoint con un tag `language` e invia la chiave come `api_key` o come header Bearer.

## Esempio di richiesta

L'esempio in bash stampa il titolo di Fight Club (id `550`) in tre lingue. Usa `jq` per stampare un campo. L'esempio in PHP richiede il bielorusso e ripiega sull'inglese quando la trama è vuota.

```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;
```

Risposta per `language=ru-RU`, ridotta a pochi campi. La chiave `text_language` nell'esempio PHP è aggiunta dal tuo codice, non dall'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": "Бойцовский клуб"
}
```

## Ripiego quando un campo è vuoto

Non tutti i titoli hanno testo in ogni lingua. Un `overview` può tornare vuoto quando non esiste una traduzione, e un `title` o un `tagline` può tornare in inglese. L'API non inventa testo. Usa un ordine fisso così la pagina mostra sempre qualcosa:

1. Richiedi la lingua che mostri.
2. Se un campo è vuoto, richiedi `en-US` per lo stesso ID, oppure leggi la voce inglese dalla lista delle traduzioni.
3. Se il titolo è vuoto, mostra `original_title`.
4. Registra da quale lingua proviene ogni campo, così puoi riprovare più tardi.

La cache edge tiene una copia per lingua per ogni percorso in cache, quindi il ripiego in inglese di un titolo popolare di solito viene servito dalla cache.

## Elencare tutte le traduzioni di un titolo

`GET /3/movie/{movie_id}/translations` restituisce un array `translations`, con una voce per ogni lingua che ha dati. L'elenco può essere più lungo delle 14 lingue servite: Fight Club ha 50 voci. Usalo per costruire un selettore di lingua, o per salvare tutti i testi di un titolo in una sola riga.

| Campo                                                                         | Significato                                   |
| ----------------------------------------------------------------------------- | --------------------------------------------- |
| `iso_639_1`, `iso_3166_1`                                                     | Codici di lingua e paese                      |
| `english_name`                                                                | Nome della lingua in inglese                  |
| `data.title` (film) o `data.name` (serie TV), `data.overview`, `data.tagline` | Testo localizzato, il titolo può essere vuoto |
| `data.homepage`, `data.runtime`                                               | Valori facoltativi per quella traduzione      |

Lo stesso endpoint esiste per serie TV ed episodi. Le voci delle serie portano `data.name` e nessun `runtime`, e le voci degli episodi portano solo `name` e `overview`. Le stagioni rispondono con una lista vuota, e persone e collezioni non hanno un endpoint di traduzioni. I dettagli sono nella pagina [traduzioni](https://amodb.dev/it/translations/). Una sola chiamata di traduzioni sostituisce fino a 14 chiamate di dettagli quando vuoi tutte le lingue insieme.

## Locandine e video per lingua

Immagini e video portano i propri tag di lingua in `iso_639_1`. Sugli endpoint delle immagini passa un elenco separato da virgole e aggiungi `null` per gli elementi senza lingua, come le locandine senza testo. La risposta contiene gli elementi corrispondenti, quindi ordinali nel tuo codice.

| Parametro                | Usato su                | Esempio      |
| ------------------------ | ----------------------- | ------------ |
| `include_image_language` | Endpoint delle immagini | `ru,en,null` |

Gli endpoint dei video restituiscono tutte le lingue in una sola risposta e ignorano `include_video_language`, quindi filtra tu su `iso_639_1`. Vedi [immagini](https://amodb.dev/it/images-api/) per dimensioni e CDN.

## L'ebraico e il testo da destra a sinistra

L'ebraico è l'unica lingua da destra a sinistra tra le 14. Gestiscilo nella pagina, non nei dati:

- Imposta `lang="he"` e `dir="rtl"` sull'elemento che contiene il testo.
- Racchiudi i titoli in caratteri latini dentro un testo ebraico in un elemento `<bdi>` perché la punteggiatura non finisca dal lato sbagliato.
- Usa proprietà CSS logiche come `margin-inline-start` invece di sinistra e destra.

## Confronto

| Funzionalità                     | Fare scraping delle pagine da solo | Dataset solo in inglese     | amodb                             |
| -------------------------------- | ---------------------------------- | --------------------------- | --------------------------------- |
| Lingue                           | Una lingua del sito per richiesta  | Inglese                     | 14 lingue con `language`          |
| Stesso ID in tutte le lingue     | URL diversi per lingua             | Non applicabile             | Lo stesso ID numerico ovunque     |
| Tutte le traduzioni di un titolo | Scaricare la pagina di ogni lingua | Non applicabile             | Una sola chiamata `translations`  |
| Locandine localizzate            | URL delle immagini per lingua      | Vedi la loro documentazione | Filtro `include_image_language`   |
| Titolo originale                 | Da estrarre dal testo della pagina | Vedi la loro documentazione | `original_title`, `original_name` |

## Prezzi

L'insieme delle lingue è lo stesso su ogni piano, quindi paghi solo la frequenza e il periodo. Acquista 1, 3, 6, 12 o 24 mesi prepagati, con uno sconto di 0, 10, 20, 30 o 40 per cento su quelli più lunghi e senza rinnovo automatico. I piani da 20, 40 e 120 richieste al minuto includono ogni lingua e ogni endpoint. Un sito in cinque lingue richiede fino a cinque chiamate di dettagli per titolo, e le richieste ripetute sono servite dalla cache edge per 6 ore. Nessun piano gratuito. Vedi i [prezzi](https://amodb.dev/it/pricing/).

## Domande e risposte

### Quali lingue serve l'API?

Quattordici: inglese, russo, ucraino, bielorusso, cinese, portoghese, bulgaro, ebraico, ceco, rumeno, francese, polacco, italiano e spagnolo, con i codici en ru uk be zh pt bg he cs ro fr pl it es.

### Cosa succede se invio un tag di lingua non servito?

La risposta ripiega sull'inglese. Un tag come ja-JP restituisce testo inglese, mentre il titolo giapponese originale arriva comunque in original_title per i film e original_name per le serie TV.

### Posso ottenere tutte le traduzioni di un titolo con una sola richiesta?

Sì. GET /3/movie/{movie_id}/translations elenca una voce per ogni lingua che ha dati, ciascuna con title, overview, tagline, homepage e runtime. Serie TV ed episodi hanno lo stesso endpoint, con name al posto di title. Stagioni, persone e collezioni non hanno traduzioni.

### Come gestisco una trama mancante nella lingua scelta?

Controlla la stringa vuota, poi richiedi lo stesso ID con en-US, oppure leggi la voce inglese dalla lista delle traduzioni. Mostra original_title come ultimo ripiego e segnala che il testo è in inglese. Titoli e slogan possono già tornare in inglese.

### Anche le locandine sono localizzate?

Le locandine portano un tag di lingua. Richiedile con include_image_language, per esempio ru,en,null, e ordina le corrispondenze nel tuo codice. I file delle immagini vengono da img.amodb.dev e non richiedono alcuna chiave.

## Pagine correlate

- [Lingue](https://amodb.dev/it/languages/): amodb serve titoli, trame e nomi in 14 lingue. Passa un tag in stile TMDB come ru-RU o pt-BR in language; qualsiasi altro tag ripiega sull'inglese.
- [API delle traduzioni](https://amodb.dev/it/translations/): API traduzioni con percorsi TMDB v3: leggi titoli, trame e slogan di un film, una serie o un episodio in tutte le loro lingue in una volta sola.
- [API dei dettagli del film](https://amodb.dev/it/movies/): API dettagli film con gli stessi percorsi e JSON di TMDB v3. Ottieni un film per ID, aggiungi crediti, valutazioni e mood con append_to_response, in 14 lingue.
- [API delle serie TV](https://amodb.dev/it/tv-series/): API serie TV con gli stessi percorsi e JSON di TMDB v3. Ottieni una serie per ID con stagioni, emittenti e prossimo episodio, più classificazioni e piattaforme.
- [API delle immagini e host delle immagini](https://amodb.dev/it/images-api/): API immagini dei film con percorsi TMDB v3: elenca locandine, sfondi, loghi e fermi immagine di ogni titolo e caricali da img.amodb.dev in 10 dimensioni.
- [Avvio rapido](https://amodb.dev/it/quickstart/): Fai la prima chiamata ad amodb: ottieni una chiave, richiedi i dettagli di un film in curl, JavaScript, Python, PHP o Go, carica la locandina. Meno di 2 minuti.

Aggiornato: 2026-10-18. Source: https://amodb.dev/it/multilingual-movie-metadata-api/