API de palabras clave
Los endpoints de palabras clave devuelven las etiquetas de trama de una película o serie de TV, cada una con un id y un nombre. Puedes consultar una palabra clave, listar las películas que la llevan o pasar los ids a discover con with_keywords para crear páginas temáticas. Las películas responden en keywords y las series en results.
Obtener las palabras clave de una película
GET / devuelve las etiquetas de trama de una película. Una palabra clave es una frase corta, como un tema, un escenario o un tipo de fuente, y tiene un id numérico que puedes reutilizar en discover.
El ejemplo carga las palabras clave de una película y luego pide a discover las películas más populares que comparten su primera palabra clave.
curl -s "https://api.amodb.dev/3/movie/550/keywords" \
-H "Authorization: Bearer $AMODB_KEY"
curl -s "https://api.amodb.dev/3/discover/movie?with_keywords=818&sort_by=popularity.desc" \
-H "Authorization: Bearer $AMODB_KEY"const base = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };
const kw = await fetch(`${base}/movie/550/keywords`, { headers });
if (!kw.ok) throw new Error(`keywords failed with ${kw.status}`);
const { keywords } = await kw.json();
console.log(keywords.map((k) => `${k.id}:${k.name}`).join(', '));
if (keywords.length > 0) {
const first = keywords[0];
const found = await fetch(`${base}/discover/movie?with_keywords=${first.id}&sort_by=popularity.desc`, { headers });
if (!found.ok) throw new Error(`discover failed with ${found.status}`);
const page = await found.json();
console.log(first.name, page.results.slice(0, 5).map((m) => m.title));
}import os
import requests
base = "https://api.amodb.dev/3"
headers = {"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}
r = requests.get(f"{base}/movie/550/keywords", headers=headers, timeout=10)
r.raise_for_status()
keywords = r.json()["keywords"]
print(", ".join(f"{k['id']}:{k['name']}" for k in keywords))
if keywords:
first = keywords[0]
d = requests.get(
f"{base}/discover/movie",
params={"with_keywords": first["id"], "sort_by": "popularity.desc"},
headers=headers,
timeout=10,
)
d.raise_for_status()
print(first["name"], [m["title"] for m in d.json()["results"][:5]])<?php
function amodb_get(string $url): array {
$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);
}
$base = 'https://api.amodb.dev/3';
$keywords = amodb_get("$base/movie/550/keywords")['keywords'];
if ($keywords) {
$first = $keywords[0];
$found = amodb_get("$base/discover/movie?with_keywords={$first['id']}&sort_by=popularity.desc");
$titles = array_column(array_slice($found['results'], 0, 5), 'title');
echo $first['name'], ': ', implode(', ', $titles), PHP_EOL;
}package main
import (
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
var client = &http.Client{Timeout: 10 * time.Second}
func get(path string, out any) error {
req, _ := http.NewRequest("GET", "https://api.amodb.dev/3"+path, nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
res, err := client.Do(req)
if err != nil {
return err
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
return fmt.Errorf("amodb returned %s", res.Status)
}
return json.NewDecoder(res.Body).Decode(out)
}
type Keywords struct {
Keywords []struct {
ID int `json:"id"`
Name string `json:"name"`
} `json:"keywords"`
}
type Page struct {
Results []struct {
Title string `json:"title"`
} `json:"results"`
}
func main() {
var kw Keywords
if err := get("/movie/550/keywords", &kw); err != nil {
panic(err)
}
if len(kw.Keywords) == 0 {
return
}
first := kw.Keywords[0]
var page Page
if err := get(fmt.Sprintf("/discover/movie?with_keywords=%d&sort_by=popularity.desc", first.ID), &page); err != nil {
panic(err)
}
fmt.Println(first.Name)
for i, m := range page.Results {
if i == 5 {
break
}
fmt.Println(" ", m.Title)
}
}Parámetros
movie_idrutaobligatorioId numérico de la película, por ejemplo550.api_keyconsultauno de los dosTu clave. Usa esta o el encabezadoAuthorization: Bearer.
Campos de la respuesta
| Campo | Tipo | Notas |
|---|---|---|
id | entero | El id de la película. |
keywords | array | Objetos con id y name. Vacío cuando la película no tiene ninguna. |
keywords[].id | entero | Id de la palabra clave. Úsalo en with_keywords y en las rutas de palabras clave de más abajo. |
keywords[].name | texto | El texto de la palabra clave. |
Ejemplo de respuesta
{
"id": 550,
"keywords": [
{ "id": 818, "name": "based on novel or book" },
{ "id": 825, "name": "support group" },
{ "id": 851, "name": "dual identity" }
]
}La respuesta real contiene 14 palabras clave. Esta se recorta a las 3 primeras. Los nombres de las palabras clave no se traducen, así que language no tiene efecto aquí.
Palabras clave de una serie de TV
GET / usa la misma clave y devuelve los mismos objetos, pero el array se llama results. El id de la ruta es el de la serie, por ejemplo 1396.
{
"id": 1396,
"results": [
{ "id": 1508, "name": "new mexico" },
{ "id": 2231, "name": "drug dealer" }
]
}La respuesta real contiene 29 entradas y esta se recorta a las 2 primeras. Un cliente que atiende ambos tipos de contenido puede leer data.keywords ? y tratar los dos casos igual.
Registros de palabras clave y sus películas
| Método y ruta | Devuelve | Parámetros |
|---|---|---|
GET / | { id, name } | ninguno |
GET / | Lista paginada de películas con id, page, results, total_pages, total_results | language, page |
Ambas rutas usan el id numérico de un array de palabras clave. La lista de películas tiene la misma forma de elemento que otras listas de películas, con genre_ids y poster_path, y además el id de la palabra clave en el nivel superior. include_adult se acepta y se ignora. Una página posterior a total_pages devuelve un array results vacío. No existe una lista de series para una palabra clave, así que usa / para TV.
Combinar palabras clave con discover
Para cualquier cosa más allá de una lista simple, filtra en discover. Ordena, pagina y combina palabras clave con otros filtros, y cubre TV además de películas.
| Objetivo | Cadena de consulta |
|---|---|
| Películas con una palabra clave | / |
| Películas con ambas de dos palabras clave | / |
| Películas sin una palabra clave | / |
| Series con una palabra clave | / |
| Series con cualquiera de dos palabras clave | / |
| Una palabra clave dentro de un género | / |
Una coma entre ids significa todos ellos. Escribe una barra vertical entre ids, como en with_keywords=818|4565, para que coincida cualquiera. Los resultados de discover se guardan en la caché perimetral durante 30 minutos.
Encontrar el id de una palabra clave
Para convertir texto en un id, llama a GET /. Devuelve una lista paginada de pares id y name, 20 por página. Consulta la búsqueda para ver todas las rutas de búsqueda. Una búsqueda de palabras clave sin coincidencias responde hoy 500 con status_code 11 en lugar de una lista vacía. Las respuestas de búsqueda se guardan en caché 10 minutos, pero cada llamada sigue contando para tus solicitudes por minuto, así que aplica debounce a un cuadro de autocompletado.
Errores
| HTTP | status_code | Cuándo |
|---|---|---|
| 401 | 7 | La clave falta o es incorrecta. |
| 402 | 36 | El periodo del plan ha terminado. |
| 404 | 34 | No hay ninguna palabra clave con ese id en /keyword/{keyword_id} ni en su lista de películas. |
| 405 | 37 | Usaste un método de escritura en una ruta de palabras clave. |
| 429 | 25 | Superaste tus solicitudes por minuto. Espera los segundos de Retry-After. |
| 500 | 11 | Una consulta a /search/keyword que no coincide con nada. |
Un id de película o serie desconocido en las rutas de palabras clave no da un 404. Recibes HTTP 200 con el id y un array vacío.
Consulta los errores para ver todos los códigos y los límites de solicitudes para los límites de cada plan.
Notas prácticas
- Guarda el
idde la palabra clave, no el nombre. Un nombre puede reformularse, un id no cambia. - Las listas de palabras clave se guardan en caché junto con los detalles del título durante 6 horas. Para páginas de etiquetas basta una actualización semanal.
- Un solo título tiene una lista corta de etiquetas. Para páginas temáticas, parte de un id de palabra clave y lista sus títulos en discover, no al revés.
- Usa
without_keywordspara quitar ruido, por ejemplo una etiqueta que nunca quieres en una página familiar. - Un array vacío es una respuesta válida para títulos poco conocidos. Oculta la fila de etiquetas en lugar de mostrar un error.