# API de metadatos de películas multilingüe

> Esta API de metadatos de películas multilingüe sirve títulos, sinopsis, eslóganes, nombres de géneros y biografías en 14 idiomas: inglés, ruso, ucraniano, bielorruso, chino, portugués, búlgaro, hebreo, checo, rumano, francés, polaco, italiano y español. Pasa una etiqueta de TMDB como ru-RU en el parámetro language.

## Obtén datos de películas en 14 idiomas

`GET /3/movie/{movie_id}?language=ru-RU` devuelve el título, la sinopsis, el eslogan y los nombres de géneros en ruso. El parámetro `language` acepta etiquetas de TMDB como `ru-RU` o `pt-BR` y funciona en todos los endpoints que devuelven texto. Los ids son los mismos en todos los idiomas, así que una fila de tu base de datos sirve para todos.

Obtienes 14 idiomas con una sola clave, el `original_title` de cada película, un endpoint de traducciones que lista todos los idiomas de un título y nombres de géneros localizados. La lista completa está en [idiomas](https://amodb.dev/es/languages/).

## Los 14 idiomas disponibles

| Idioma     | Código | Etiqueta de ejemplo |
| ---------- | ------ | ------------------- |
| Inglés     | `en`   | `en-US`             |
| Ruso       | `ru`   | `ru-RU`             |
| Ucraniano  | `uk`   | `uk-UA`             |
| Bielorruso | `be`   | `be-BY`             |
| Chino      | `zh`   | `zh-CN`             |
| Portugués  | `pt`   | `pt-BR`             |
| Búlgaro    | `bg`   | `bg-BG`             |
| Hebreo     | `he`   | `he-IL`             |
| Checo      | `cs`   | `cs-CZ`             |
| Rumano     | `ro`   | `ro-RO`             |
| Francés    | `fr`   | `fr-FR`             |
| Polaco     | `pl`   | `pl-PL`             |
| Italiano   | `it`   | `it-IT`             |
| Español    | `es`   | `es-ES`             |

Cualquier otra etiqueta recurre a `en`. El japonés y el coreano no se sirven como idiomas de interfaz. Sus títulos originales siguen llegando en `original_title` para películas y en `original_name` para series de TV.

## Qué datos obtienes

| Endpoint                                   | Contenido localizado                                                        |
| ------------------------------------------ | --------------------------------------------------------------------------- |
| `GET /3/movie/{movie_id}`                  | `title`, `overview`, `tagline`, nombres de géneros                          |
| `GET /3/tv/{tv_id}`                        | `name`, `overview`, `tagline`, nombres de géneros                           |
| `GET /3/tv/{tv_id}/season/{season_number}` | `name` y `overview` de la temporada y de sus episodios                      |
| `GET /3/person/{person_id}`                | `biography`                                                                 |
| `GET /3/genre/movie/list`                  | Nombres de géneros para filtros y menús                                     |
| `GET /3/movie/{movie_id}/translations`     | Todos los idiomas de un título en una sola respuesta                        |
| `GET /3/movie/{movie_id}/images`           | Pósters etiquetados por idioma, filtrados con `include_image_language`      |
| `GET /3/movie/{movie_id}/videos`           | Vídeos etiquetados por `iso_639_1`, todos los idiomas en una sola respuesta |

## Empieza en 3 pasos

1. Elige un plan en [precios](https://amodb.dev/es/pricing/). El número de idiomas no cambia con el plan, solo la velocidad de solicitudes.
2. Crea una clave en el panel de tu cuenta.
3. Llama a cualquier endpoint con una etiqueta `language` y envía la clave como `api_key` o como encabezado Bearer.

## Ejemplo de solicitud

El ejemplo en bash imprime el título de Fight Club (id `550`) en tres idiomas. Usa `jq` para imprimir un campo. El ejemplo en PHP pide bielorruso y recurre al inglés cuando la sinopsis está en blanco.

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

Respuesta para `language=ru-RU`, recortada a unos pocos campos. La clave `text_language` del ejemplo en PHP la añade tu código, no la 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": "Бойцовский клуб"
}
```

## Respaldo cuando un campo está vacío

No todos los títulos tienen texto en todos los idiomas. Un `overview` puede llegar vacío cuando no existe traducción, y un `title` o un `tagline` puede llegar en inglés. La API no inventa texto. Usa un orden fijo para que la página siempre muestre algo:

1. Pide el idioma que muestras.
2. Si un campo está vacío, pide `en-US` para el mismo id, o lee la entrada en inglés de la lista de traducciones.
3. Si el título está vacío, muestra `original_title`.
4. Guarda de qué idioma salió cada campo, para poder reintentarlo más tarde.

La caché perimetral guarda una copia por idioma para cada ruta en caché, así que el respaldo en inglés de un título popular suele servirse desde la caché.

## Lista todas las traducciones de un título

`GET /3/movie/{movie_id}/translations` devuelve una lista `translations`, con una entrada por cada idioma que tiene datos. La lista puede ser más larga que los 14 idiomas servidos: Fight Club tiene 50 entradas. Úsala para crear un selector de idioma o para guardar todos los textos de un título en una sola fila.

| Campo                                                                        | Significado                                   |
| ---------------------------------------------------------------------------- | --------------------------------------------- |
| `iso_639_1`, `iso_3166_1`                                                    | Códigos de idioma y de país                   |
| `english_name`                                                               | Nombre del idioma en inglés                   |
| `data.title` (películas) o `data.name` (TV), `data.overview`, `data.tagline` | Texto localizado, el título puede estar vacío |
| `data.homepage`, `data.runtime`                                              | Valores opcionales de esa traducción          |

El mismo endpoint existe para series de TV y episodios. Las entradas de TV incluyen `data.name` y no tienen `runtime`, y las de episodios solo incluyen `name` y `overview`. Las temporadas responden con una lista vacía, y las personas y las colecciones no tienen endpoint de traducciones. Los detalles están en [traducciones](https://amodb.dev/es/translations/). Una llamada de traducciones sustituye hasta 14 llamadas de detalles cuando quieres todos los idiomas a la vez.

## Pósters y vídeos por idioma

Las imágenes y los vídeos llevan sus propias etiquetas de idioma en `iso_639_1`. En los endpoints de imágenes, pasa una lista separada por comas y añade `null` para los elementos sin idioma, como los pósters sin texto. La respuesta contiene los elementos que coinciden, así que ordénalos en tu código.

| Parámetro                | Se usa en             | Ejemplo      |
| ------------------------ | --------------------- | ------------ |
| `include_image_language` | Endpoints de imágenes | `ru,en,null` |

Los endpoints de vídeos devuelven todos los idiomas en una sola respuesta e ignoran `include_video_language`, así que filtra tú mismo por `iso_639_1`. Consulta [imágenes](https://amodb.dev/es/images-api/) para ver los tamaños y el CDN.

## Hebreo y texto de derecha a izquierda

El hebreo es el único idioma de derecha a izquierda de los 14. Resuélvelo en la página, no en los datos:

- Define `lang="he"` y `dir="rtl"` en el elemento que contiene el texto.
- Envuelve los títulos en alfabeto latino dentro de texto en hebreo en un elemento `<bdi>` para que la puntuación no salte al lado equivocado.
- Usa propiedades CSS lógicas como `margin-inline-start` en lugar de izquierda y derecha.

## Cómo se compara

| Capacidad                           | Hacer scraping de las páginas tú mismo             | Dataset solo en inglés  | amodb                                |
| ----------------------------------- | -------------------------------------------------- | ----------------------- | ------------------------------------ |
| Idiomas                             | Una configuración regional del sitio por solicitud | Inglés                  | 14 idiomas con `language`            |
| Mismo id en todos los idiomas       | URL distintas por configuración regional           | No aplica               | El mismo id numérico en todas partes |
| Todas las traducciones de un título | Pedir la página de cada configuración regional     | No aplica               | Una llamada a `translations`         |
| Pósters localizados                 | URL de imagen por configuración regional           | Revisa su documentación | Filtro `include_image_language`      |
| Título original                     | Extraerlo del texto de la página                   | Revisa su documentación | `original_title`, `original_name`    |

## Precios

El conjunto de idiomas es el mismo en todos los planes, así que pagas solo por la velocidad y el periodo. Compra 1, 3, 6, 12 o 24 meses prepago, con un 0, 10, 20, 30 o 40 por ciento de descuento en los más largos y sin renovación automática. Los planes de 20, 40 y 120 solicitudes por minuto incluyen todos los idiomas y todos los endpoints. Un sitio en cinco idiomas necesita hasta cinco llamadas de detalles por título, y las solicitudes repetidas se sirven desde la caché perimetral durante 6 horas. No hay nivel gratuito. Consulta [precios](https://amodb.dev/es/pricing/).

## Preguntas y respuestas

### ¿Qué idiomas sirve la API?

Catorce: inglés, ruso, ucraniano, bielorruso, chino, portugués, búlgaro, hebreo, checo, rumano, francés, polaco, italiano y español, con los códigos en ru uk be zh pt bg he cs ro fr pl it es.

### ¿Qué pasa si envío una etiqueta de idioma que no se sirve?

La respuesta recurre al inglés. Una etiqueta como ja-JP devuelve texto en inglés, mientras que el título original en japonés sigue llegando en original_title para películas y en original_name para series de TV.

### ¿Puedo obtener todas las traducciones de un título en una sola solicitud?

Sí. GET /3/movie/{movie_id}/translations lista una entrada por cada idioma con datos, cada una con title, overview, tagline, homepage y runtime. Las series de TV y los episodios tienen el mismo endpoint, con name en lugar de title. Las temporadas, las personas y las colecciones no tienen traducciones.

### ¿Cómo manejo una sinopsis que falta en el idioma elegido?

Comprueba si llega una cadena vacía y luego pide el mismo id con en-US, o lee la entrada en inglés de la lista de traducciones. Muestra original_title como último recurso y marca el texto como inglés. Los títulos y los eslóganes ya pueden llegar en inglés.

### ¿Los pósters también están localizados?

Los pósters llevan una etiqueta de idioma. Pídelos con include_image_language, por ejemplo ru,en,null, y ordena las coincidencias en tu código. Los archivos de imagen salen de img.amodb.dev y no necesitan clave.

## Páginas relacionadas

- [Idiomas](https://amodb.dev/es/languages/): amodb sirve títulos, sinopsis y nombres en 14 idiomas. Pasa una etiqueta estilo TMDB como ru-RU o pt-BR en language; cualquier otra etiqueta recurre al inglés.
- [API de traducciones](https://amodb.dev/es/translations/): API de traducciones de películas con rutas TMDB v3: lee todos los títulos, sinopsis y eslóganes de una película, serie o episodio en todos sus idiomas.
- [API de detalles de película](https://amodb.dev/es/movies/): API de detalles de película con rutas y JSON de TMDB v3. Obtén una película por id y añade créditos, puntuaciones y moods con append_to_response, en 14 idiomas.
- [API de series de TV](https://amodb.dev/es/tv-series/): API de series de TV con las mismas rutas y JSON que TMDB v3. Obtén una serie con temporadas, cadenas y próximo episodio, más clasificaciones y plataformas.
- [API de imágenes y host de imágenes](https://amodb.dev/es/images-api/): API de imágenes de películas con rutas TMDB v3: lista pósters, fondos, logos y fotogramas por título y cárgalos desde img.amodb.dev en 10 tamaños sin clave.
- [Inicio rápido](https://amodb.dev/es/quickstart/): Haz tu primera llamada a amodb: consigue una clave, pide los detalles de una película en curl, JavaScript, Python, PHP o Go y carga el póster. En 2 minutos.

Actualizado: 2026-10-18. Source: https://amodb.dev/es/multilingual-movie-metadata-api/