# API de trailers de filmes > A API de trailers de filmes é GET /3/movie/{movie_id}/videos em api.amodb.dev. Cada vídeo traz tipo, flag oficial, idioma e data de publicação, então você escolhe o trailer oficial em uma só passada. As séries retornam o mesmo formato. Caminhos e JSON seguem o TMDB v3. ## Obtenha o trailer oficial de um filme `GET /3/movie/{movie_id}/videos` retorna todos os vídeos ligados a um filme. Cada item tem um `type`, uma flag `official`, um código de idioma, um timestamp `published_at` e o `site` e a `key` que identificam o vídeo. Mantenha os itens em que `type` é `Trailer` e `official` é `true`, e você tem o seu trailer. Você recebe uma lista de registros de vídeo que pode classificar por conta própria, não um stream. A resposta nomeia o vídeo e diz onde ele está, e sua página monta o player a partir de `site` e `key`. O mesmo formato volta para séries de TV. Os caminhos de temporada e episódio respondem com uma lista vazia. ## Quais dados você recebe | Endpoint | Retorna | | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `GET /3/movie/{movie_id}/videos` | Trailers, teasers, clipes, featurettes, bastidores e erros de gravação (bloopers) de um filme | | `GET /3/tv/{tv_id}/videos` | A mesma lista para uma série | | `GET /3/tv/{tv_id}/season/{season_number}/videos` | Sempre uma lista `results` vazia | | `GET /3/tv/{tv_id}/season/{season_number}/episode/{episode_number}/videos` | Sempre uma lista `results` vazia | | `GET /3/movie/{movie_id}` com `append_to_response=videos` | Detalhes e vídeos em uma requisição | Campos de cada vídeo: | Campo | Tipo | Uso | | ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | | `type` | string | Tipo de vídeo: `Trailer`, `Teaser`, `Clip`, `Featurette`, `Behind the Scenes` ou `Bloopers`, como na página de vídeos | | `official` | boolean | `true` quando o vídeo é marcado como oficial | | `iso_639_1`, `iso_3166_1` | string | Códigos de idioma e de país do vídeo | | `key`, `site` | string | Identificador do vídeo e nome do site que o hospeda, `YouTube` em todos os vídeos vistos | | `size` | integer | Resolução vertical, `1080` em todos os vídeos vistos | | `published_at` | string | Timestamp ISO 8601, bom para ordenar do mais novo para o mais antigo | | `name`, `id` | string | Título do vídeo e seu id, que é a mesma string que `key` | ## Comece em 3 passos 1. Escolha um plano em [preços](https://amodb.dev/pt/pricing/). Todo plano retorna todos os dados, então você escolhe pelas requisições por minuto. 2. Crie uma chave no painel da sua conta. Ela tem 32 caracteres hexadecimais em minúsculas. 3. Chame `GET /3/movie/{movie_id}/videos` com a chave em `api_key` ou em um header `Authorization: Bearer`. ## Exemplo de requisição O exemplo pede os vídeos de Inception (id `27205`), classifica-os no código e imprime o melhor. A classificação coloca primeiro as correspondências de idioma, depois `Trailer` antes de `Teaser`, depois oficial antes de não oficial e por fim o `published_at` mais 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'); ``` Resposta reduzida: os 2 primeiros de 42 vídeos. A lista contém todos os idiomas. ```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" } ] } ``` ## Escolha qual vídeo reproduzir Um título costuma ter vários trailers oficiais (um primeiro anúncio, um corte final) ao lado de teasers e clipes. Classifique-os com uma ordem fixa para que a página nunca coloque um vídeo de erros de gravação no espaço do trailer. | Prioridade | Filtro | Uso típico | | ---------- | ----------------------------------- | ---------------------------------------------------------- | | 1 | `Trailer`, oficial, idioma coincide | O vídeo a reproduzir | | 2 | `Trailer`, não oficial | Uploads regionais ou de fãs quando não existe nada oficial | | 3 | `Teaser`, oficial | Chamadas curtas de pré-lançamento | | 4 | `Clip`, `Featurette` | Alternativa para o espaço não ficar vazio | | ignorar | `Behind the Scenes`, `Bloopers` | Mostre em uma lista separada de extras | Desempate por `published_at`. O mais novo primeiro dá o corte mais recente, e o mais antigo primeiro dá o primeiro anúncio. ## Idiomas dos trailers Os vídeos recebem uma marca de idioma em `iso_639_1`, e um título pode ter trailers em vários. Inception tem 42 vídeos em 9 idiomas. O amodb retorna todos eles em uma só resposta. Os parâmetros `language` e `include_video_language` não têm efeito nos endpoints de vídeos, então escolha o idioma no seu código. | Passo | O que fazer | | ----- | -------------------------------------------------------------------------------- | | 1 | Mantenha os vídeos cujo `iso_639_1` corresponde ao seu usuário, por exemplo `ru` | | 2 | Se nenhum corresponder, mantenha `en` | | 3 | Se nenhum corresponder, mantenha o restante | Classifique dentro de cada passo por tipo e pela flag `official`, como no exemplo. Os idiomas dos vídeos seguem o upload, não os 14 idiomas da interface listados em [idiomas](https://amodb.dev/pt/languages/), então um trailer pode ser `cs` ou `he`. ## Trailers de séries O trailer de uma série fica em `/3/tv/1396/videos` (Breaking Bad), que tem 9 trailers. A função de classificação acima funciona como está, porque os campos não mudam. Caminhos de temporada e episódio como `/3/tv/1396/season/1/videos` respondem 200 com uma lista `results` vazia, então leia a lista da série. Veja [vídeos e trailers](https://amodb.dev/pt/videos-trailers/) para a lista completa de caminhos. ## Monte uma fileira de trailers Uma fileira de filmes em cartaz precisa de uma chamada de lista e uma chamada por título: `GET /3/movie/now_playing` (veja [em alta e listas](https://amodb.dev/pt/trending-lists/)) mais dez chamadas de vídeos dão 11 requisições para dez títulos. Guarde a `key` escolhida junto ao id do filme. Os trailers mudam pouco, então atualize uma escolha guardada a cada poucas horas ou quando um título for relançado. ## Como se compara | Recurso | Fazer scraping das páginas | API de metadados com plano gratuito | amodb | | ------------------------ | ------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | | Flag de oficial | Deduzir pelo título da página | Veja a documentação deles | Booleano `official` em todo vídeo | | Filtro por tipo de vídeo | Interpretar texto | Veja a documentação deles | Seis valores de `type` | | Escolha de idioma | Uma localidade por página | Veja a documentação deles | `iso_639_1` e `iso_3166_1` em todo vídeo, filtrados no seu código | | Séries e episódios | Páginas separadas para rastrear | Veja a documentação deles | As séries usam o mesmo endpoint, as listas de temporada e episódio são vazias | | Manutenção | Quebra quando o markup muda | Depende do provedor | Um formato JSON estável | | Termos | Você assume o risco | Veja os termos deles | Planos pagos, veja [preços](https://amodb.dev/pt/pricing/) | ## Preços Os planos são pré-pagos. Você compra 1, 3, 6, 12 ou 24 meses e ganha 0, 10, 20, 30 ou 40 por cento de desconto nos períodos mais longos. Nada renova sozinho. Os planos de 20, 40 e 120 requisições por minuto atendem todos os endpoints desta página, então uma fileira de trailers movimentada é só uma questão de taxa. Não há plano gratuito nem período de teste. Compare os planos em [preços](https://amodb.dev/pt/pricing/). ## Perguntas e respostas ### Como obtenho o trailer oficial de um filme? Chame GET /3/movie/{movie_id}/videos, mantenha os itens em que type é Trailer e official é true e ordene por published_at. O primeiro item é o trailer oficial mais recente. Se não houver trailer, use um Teaser. ### A API retorna um arquivo de vídeo ou um stream? Não. Ela retorna metadados de cada vídeo: name, type, site, key, size, language e datas. Você monta o link do player com site e key, ou incorpora o vídeo na sua própria página. Pôsteres e stills vêm de img.amodb.dev. ### Como obtenho trailers no meu idioma? O endpoint de vídeos retorna todos os idiomas em uma só resposta e ignora os parâmetros language e include_video_language. Filtre por iso_639_1 no seu código, por exemplo ru primeiro, depois en e depois o resto. Inception tem vídeos em 9 idiomas. ### Posso obter trailers de séries e episódios? Para séries, sim: use /3/tv/{tv_id}/videos. Os campos são os mesmos, então o código de classificação que você escreveu para filmes funciona sem mudanças. Os caminhos de vídeos de temporada e episódio respondem com um array results vazio, então use a lista da série. ### Quantas requisições uma busca de trailer usa? Uma requisição por título. Com append_to_response=videos o trailer chega dentro da chamada de detalhes, então detalhes mais trailer continuam sendo uma requisição contra seus 20, 40 ou 120 requisições por minuto. ## Páginas relacionadas - [API de vídeos e trailers](https://amodb.dev/pt/videos-trailers/): API de vídeos de filmes com caminhos do TMDB v3: liste trailers, teasers, clipes e featurettes de um filme ou série e filtre por tipo e idioma no seu código. - [API de detalhes de filmes](https://amodb.dev/pt/movies/): API de detalhes de filmes com caminhos e JSON do TMDB v3. Busque um filme por id e junte créditos, avaliações e moods com append_to_response, em 14 idiomas. - [API de séries de TV](https://amodb.dev/pt/tv-series/): API de séries de TV com os mesmos caminhos e JSON do TMDB v3. Busque uma série por id com temporadas, emissoras, próximo episódio e classificações. - [Endpoints de em alta e de listas](https://amodb.dev/pt/trending-lists/): API de filmes em alta com caminhos do TMDB v3: rankings do dia e da semana, listas em cartaz, populares, mais bem avaliados e em breve. Cache de 30 minutos. - [Idiomas](https://amodb.dev/pt/languages/): O amodb serve títulos, sinopses e nomes em 14 idiomas. Passe uma tag no estilo TMDB como ru-RU ou pt-BR em language; qualquer outra tag volta para o inglês. - [Início rápido](https://amodb.dev/pt/quickstart/): Faça sua primeira chamada ao amodb: obtenha uma chave, peça um filme em curl, JavaScript, Python, PHP ou Go e carregue o pôster. Menos de 2 minutos. Atualizado: 2026-10-18. Source: https://amodb.dev/pt/movie-trailer-api/