# API per i trailer dei film > L'API per i trailer è GET /3/movie/{movie_id}/videos su api.amodb.dev. Ogni video porta un tipo, un flag ufficiale, una lingua e una data di pubblicazione, così scegli il trailer ufficiale in un solo passaggio. Le serie restituiscono la stessa struttura. Percorsi e JSON seguono TMDB v3. ## Ottenere il trailer ufficiale di un film `GET /3/movie/{movie_id}/videos` restituisce tutti i video collegati a un film. Ogni elemento ha un `type`, un flag `official`, un codice lingua, un timestamp `published_at`, e il `site` e la `key` che identificano il video. Tieni gli elementi in cui `type` è `Trailer` e `official` è `true`, e hai il tuo trailer. Ottieni un elenco di record video che ordini tu, non uno stream. La risposta nomina il video e dice dove si trova, e la tua pagina costruisce il player da `site` e `key`. La stessa struttura torna per le serie TV. I percorsi di stagioni ed episodi rispondono con una lista vuota. ## Quali dati ottieni | Endpoint | Restituisce | | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `GET /3/movie/{movie_id}/videos` | Trailer, teaser, clip, featurette, dietro le quinte e fuori onda di un film | | `GET /3/tv/{tv_id}/videos` | La stessa lista per una serie | | `GET /3/tv/{tv_id}/season/{season_number}/videos` | Sempre una lista `results` vuota | | `GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}/videos` | Sempre una lista `results` vuota | | `GET /3/movie/{movie_id}` con `append_to_response=videos` | Dettagli e video in una sola richiesta | Campi di ogni video: | Campo | Tipo | Uso | | ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `type` | stringa | Tipo di video: `Trailer`, `Teaser`, `Clip`, `Featurette`, `Behind the Scenes` o `Bloopers`, come nella pagina dei video | | `official` | booleano | `true` quando il video è segnato come ufficiale | | `iso_639_1`, `iso_3166_1` | stringa | Codici di lingua e paese del video | | `key`, `site` | stringa | Identificativo del video e nome del sito che lo ospita, `YouTube` su ogni video visto | | `size` | intero | Risoluzione verticale, `1080` su ogni video visto | | `published_at` | stringa | Timestamp ISO 8601, utile per ordinare dal più recente | | `name`, `id` | stringa | Titolo del video e suo id, che è la stessa stringa di `key` | ## Parti in 3 passaggi 1. Scegli un piano nella pagina dei [prezzi](https://amodb.dev/it/pricing/). Ogni piano restituisce tutti i dati, quindi scegli in base alle richieste al minuto. 2. Crea una chiave nella dashboard del tuo account. È di 32 caratteri esadecimali minuscoli. 3. Chiama `GET /3/movie/{movie_id}/videos` con la chiave in `api_key` o in un header `Authorization: Bearer`. ## Esempio di richiesta L'esempio chiede i video di Inception (id `27205`), li ordina nel codice e stampa il migliore. L'ordinamento mette prima le corrispondenze di lingua, poi `Trailer` prima di `Teaser`, poi quelli ufficiali prima dei non ufficiali, poi il `published_at` più recente. ```bash curl -s "https://api.amodb.dev/3/movie/27205/videos" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const BASE = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; const TYPE_RANK = { Trailer: 0, Teaser: 2 }; function rank(video, lang) { const language = video.iso_639_1 === lang ? 0 : 10; const type = TYPE_RANK[video.type] ?? 4; return language + type + (video.official ? 0 : 1); } async function pickTrailer(movieId, lang = 'en') { const res = await fetch(`${BASE}/movie/${movieId}/videos`, { headers }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const { results } = await res.json(); results.sort( (a, b) => rank(a, lang) - rank(b, lang) || (b.published_at || '').localeCompare(a.published_at || ''), ); return results[0] ?? null; } const trailer = await pickTrailer(27205, 'en'); console.log(trailer ? `${trailer.name}: ${trailer.site} ${trailer.key}` : 'no video found'); ``` Risposta ridotta: i primi 2 dei 42 video. La lista contiene tutte le lingue. ```json { "id": 27205, "results": [ { "iso_639_1": "en", "iso_3166_1": "US", "name": "The Dream Sequence", "key": "mpj9dL7swwk", "site": "YouTube", "size": 1080, "type": "Clip", "official": true, "published_at": "2022-03-09T01:00:20Z", "id": "mpj9dL7swwk" }, { "iso_639_1": "en", "iso_3166_1": "US", "name": "35mm Theatrical Trailer #3", "key": "cdx31ak4KbQ", "site": "YouTube", "size": 1080, "type": "Trailer", "official": false, "published_at": "2022-03-07T06:00:19Z", "id": "cdx31ak4KbQ" } ] } ``` ## Scegliere quale video riprodurre Un titolo ha spesso più trailer ufficiali (un primo annuncio, una versione finale) accanto a teaser e clip. Ordinali con una sequenza fissa così la pagina non finisce mai con un video di fuori onda al posto del trailer. | Priorità | Filtro | Uso tipico | | ---------- | ------------------------------------------- | ------------------------------------------------------------------- | | 1 | `Trailer`, ufficiale, lingua corrispondente | Il video da riprodurre | | 2 | `Trailer`, non ufficiale | Caricamenti regionali o di fan quando non esiste nulla di ufficiale | | 3 | `Teaser`, ufficiale | Brevi spot prima dell'uscita | | 4 | `Clip`, `Featurette` | Ripiego perché lo spazio non resti vuoto | | da saltare | `Behind the Scenes`, `Bloopers` | Da mostrare in un elenco di extra separato | Spareggia i pari con `published_at`. Dal più recente dà l'ultima versione, dal più vecchio dà il primo annuncio. ## Lingue dei trailer I video sono etichettati con una lingua tramite `iso_639_1`, e un titolo può avere trailer in più lingue. Inception ha 42 video in 9 lingue. amodb li restituisce tutti in una sola risposta. I parametri `language` e `include_video_language` non hanno effetto sugli endpoint dei video, quindi scegli la lingua nel tuo codice. | Passaggio | Cosa fare | | --------- | ---------------------------------------------------------------------------- | | 1 | Tieni i video il cui `iso_639_1` corrisponde al tuo utente, per esempio `ru` | | 2 | Se nessuno corrisponde, tieni `en` | | 3 | Se nessuno corrisponde, tieni il resto | All'interno di ogni passaggio ordina per tipo e per flag `official` come nell'esempio. Le lingue dei video seguono il caricamento e non le 14 lingue dell'interfaccia elencate nella pagina [lingue](https://amodb.dev/it/languages/), quindi un trailer può essere `cs` o `he`. ## Trailer per le serie Il trailer di una serie sta in `/3/tv/1396/videos` (Breaking Bad), che contiene 9 trailer. La funzione di ordinamento qui sopra funziona così com'è, perché i campi non cambiano. I percorsi di stagioni ed episodi come `/3/tv/1396/season/1/videos` rispondono 200 con una lista `results` vuota, quindi leggi la lista della serie. Vedi [video e trailer](https://amodb.dev/it/videos-trailers/) per l'elenco completo dei percorsi. ## Costruire un carosello di trailer Un carosello di film in sala richiede una chiamata di lista e una chiamata per titolo: `GET /3/movie/now_playing` (vedi [tendenze e liste](https://amodb.dev/it/trending-lists/)) più dieci chiamate di video fanno 11 richieste per dieci titoli. Salva la `key` scelta accanto all'ID del film. I trailer cambiano di rado, quindi aggiorna una scelta salvata ogni poche ore o quando un titolo torna in sala. ## Confronto | Funzionalità | Fare scraping delle pagine da solo | API di metadati con piano gratuito | amodb | | ------------------------ | ---------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- | | Flag ufficiale | Dedurlo dal titolo della pagina | Vedi la loro documentazione | Booleano `official` su ogni video | | Filtro per tipo di video | Analizzare il testo | Vedi la loro documentazione | Sei valori di `type` | | Scelta della lingua | Una lingua per pagina | Vedi la loro documentazione | `iso_639_1` e `iso_3166_1` su ogni video, filtrati nel tuo codice | | Serie ed episodi | Pagine separate da scansionare | Vedi la loro documentazione | Le serie usano lo stesso endpoint, le liste di stagioni ed episodi sono vuote | | Manutenzione | Si rompe quando cambia il markup | Dipende dal fornitore | Una sola struttura JSON stabile | | Condizioni | Ti assumi il rischio | Vedi le loro condizioni | Piani a pagamento, vedi i [prezzi](https://amodb.dev/it/pricing/) | ## Prezzi I piani sono prepagati. Acquisti 1, 3, 6, 12 o 24 mesi e ottieni uno sconto di 0, 10, 20, 30 o 40 per cento per i periodi più lunghi. Nulla si rinnova da solo. I piani da 20, 40 e 120 richieste al minuto servono tutti ogni endpoint di questa pagina, quindi un carosello di trailer molto usato è solo una questione di frequenza. Non esistono un piano gratuito né una prova. Confronta i piani nella pagina dei [prezzi](https://amodb.dev/it/pricing/). ## Domande e risposte ### Come ottengo il trailer ufficiale di un film? Chiama GET /3/movie/{movie_id}/videos, tieni gli elementi in cui type è Trailer e official è true, poi ordina per published_at. Il primo elemento è il trailer ufficiale più recente. Se non esiste alcun trailer, ripiega su un Teaser. ### L'API restituisce un file video o uno stream? No. Restituisce i metadati di ogni video: name, type, site, key, size, language e date. Costruisci il link del player da site e key, oppure incorpori il video nella tua pagina. Locandine e immagini vengono da img.amodb.dev. ### Come ottengo i trailer nella mia lingua? L'endpoint videos restituisce tutte le lingue in una sola risposta e ignora i parametri language e include_video_language. Filtra su iso_639_1 nel tuo codice, per esempio prima ru, poi en, poi il resto. Inception ha video in 9 lingue. ### Posso ottenere i trailer di serie ed episodi? Per le serie sì: usa /3/tv/{tv_id}/videos. I campi sono gli stessi, quindi il codice di ordinamento scritto per i film funziona senza modifiche. I percorsi dei video di stagioni ed episodi rispondono con un array results vuoto, quindi usa la lista della serie. ### Quante richieste usa la ricerca di un trailer? Una richiesta per titolo. Con append_to_response=videos il trailer arriva dentro la chiamata dei dettagli, quindi dettagli più trailer restano una sola richiesta sulle tue 20, 40 o 120 richieste al minuto. ## Pagine correlate - [API dei video e dei trailer](https://amodb.dev/it/videos-trailers/): API video con percorsi TMDB v3: elenca trailer, teaser, clip e featurette di un film o serie TV, poi filtra per tipo e lingua nel tuo codice. - [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. - [Tendenze e endpoint delle liste](https://amodb.dev/it/trending-lists/): API tendenze con percorsi TMDB v3: classifiche giorno e settimana, più liste di film e serie in sala, popolari, più votati e in arrivo, cache di 30 minuti. - [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. - [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/movie-trailer-api/