API v1
La API JSON de KumoYami para integraciones, la que usarán las apps de la Biblioteca y de Archivos (próximamente).
KumoYami tiene una API JSON, la que usarán sus apps del móvil y de Android TV (próximamente). Sirve para hacer tu propia app o integrar tu servidor con otras herramientas. Ve exactamente lo que la web enseña a la misma cuenta, con sus permisos.
Lo básico
- Dirección:
https://tu-servidor/api/v1/, en cualquiera de las dos direcciones del servidor (Archivos o la Biblioteca). - Todas las rutas acaban en barra:
/api/v1/home/. Sin ella, la respuesta es un308a la ruta con barra. - JSON de entrada y de salida (
Content-Type: application/jsonen los POST). - Sin caché (
Cache-Control: no-store) y sin CORS: está pensada para apps, no para otras webs. - Las horas son milisegundos desde 1970; las posiciones y duraciones de vídeo, segundos.
- Las rutas de los archivos (
path) son las de la web, tal cual:/Series/3 Body Problem (2024). Codifícalas solo al ponerlas en una URL.
Primera llamada
curl https://nube.example.com/api/v1/info/{
"name": "KumoYami",
"version": "0.1.4",
"api": 1,
"library": true,
"users": true,
"files": true,
"anonymous": "all",
"signIn": { "password": true, "passkey": false, "device": true, "patreon": false },
"features": ["media-library", "profiles", "watch-party"]
}/info/ no necesita sesión: dice qué partes están encendidas, cómo se puede entrar y qué funciones trae el plan.
Encontrar el servidor con su código
Con el código de servidor, una app pide el código y lo busca en el directorio del servidor de licencias:
curl https://licenses.kumoyami.com/v1/directory/BCDF-GHJK{
"name": "KumoYami",
"urls": { "files": "https://nube.example.com", "library": "https://app.example.com" },
"reachable": { "files": true, "library": true },
"version": "0.1.4"
}Es público y sin sesión, con un límite de 30 búsquedas por minuto y por IP. Después la app habla directamente con el servidor: guarda la dirección, no el código.
Entrar
Cada sesión es un token: va en cada petición como Authorization: Bearer <token>. Dura 60 días desde el último
uso y la cuenta la ve, con el nombre del dispositivo, entre sus sesiones. Las cookies se ignoran en la v1.
La forma más cómoda, sin teclear contraseñas en la tele. Funciona también con passkeys, Patreon y la verificación en dos pasos.
curl -X POST https://nube.example.com/api/v1/auth/device/ \
-H 'Content-Type: application/json' \
-d '{ "action": "start", "device": { "name": "Tele del salón", "platform": "androidtv" } }'La respuesta trae userCode (por ejemplo BCDF-GHJK) y verificationUri. Enséñalos (y un QR de
verificationUriComplete). La persona los abre en su móvil, donde ya ha entrado, y aprueba. Mientras, pregunta cada
interval segundos con { "action": "poll", "deviceCode": "…" } hasta recibir "status": "approved" y el token.
POST /auth/logout/ cierra la sesión: el token y todas las direcciones firmadas para él dejan de valer.
Las partes
| Parte | Rutas | Necesita |
|---|---|---|
| Servidor | /info/ | Nada |
| Entrar | /auth/*, /me/, /profiles/ | Las cuentas encendidas |
| Biblioteca | /home/, /libraries/, /browse/, /title/, /search/, /play/, /progress/, /watched/, /watchlist/, /history/, /requests/*, /downloads/… | La Biblioteca encendida y un token de una cuenta que entra en ella |
| Archivos | /files/list/, /files/search/, /files/download/, /files/preview/, /files/unlock/ | Nada más; el token es opcional |
| Medios | /media/<tipo>/ | Una dirección firmada |
Si una parte no está disponible, sus rutas responden 403 con code: "license" (no está en el plan) o
"disabled" (apagada en el panel).
Lo más usado
GET /home/: los bloques de la página de inicio de la Biblioteca («Seguir viendo», «Recién añadido»…).GET /libraries/yGET /browse/?library=: las bibliotecas y su contenido, por páginas (cursor).GET /title/?path=: la ficha de una película, serie, temporada o episodio.GET /play/?path=: cómo reproducir un vídeo (directo o convertido, con sus pistas y subtítulos).POST /progress/: dónde va la reproducción, para «Seguir viendo».GET /profiles/yPOST /profiles/: elegir perfil, con su PIN si lo tiene.
Direcciones firmadas
Las imágenes, vídeos, subtítulos y descargas llegan como direcciones absolutas y firmadas, para que los componentes de imagen y vídeo las carguen sin cabeceras:
https://nube.example.com/api/v1/media/<tipo>/?path=…&ks=<firma>Caducan solas (las imágenes en 6 a 12 horas, los vídeos tras su duración y 2 horas más) y dejan de valer al cerrar la sesión. Trátalas como secretas: abren ese archivo hasta que caducan.
Errores
{ "error": "Mensaje para personas (en inglés)", "code": "codigo_para_maquinas" }| Estado | code | Qué pasa |
|---|---|---|
| 400 | bad_request | Falta un parámetro o no vale. |
| 401 | auth | Sin token, o ya no vale. |
| 403 | forbidden, password, profile | La cuenta no puede abrirlo, necesita la contraseña de la carpeta, o el perfil no tiene edad. |
| 403 | license, disabled | La parte no está en el plan, o está apagada. |
| 404 | not_found | No existe, o no se ve. |
| 409 | profile_required | Antes hay que elegir perfil. |
| 429 | rate_limited, too_many_playbacks | Demasiados intentos, o demasiados vídeos a la vez. |
| 5xx | server, storage | Error del servidor o del almacenamiento. |
Accept-Language elige el idioma de los títulos, sinopsis y los pocos textos de la API (es, en y otros).
¿Vas a hacer una app?
Escríbenos (el correo está en el aviso legal) y te mandamos la referencia completa de la API, con cada ruta, sus respuestas y ejemplos.
Todas las marcas y logotipos pertenecen a sus respectivos propietarios. Su uso solo indica compatibilidad, no patrocinio ni asociación. El logotipo de Synology es una marca de Synology Inc.; Google Drive, Google Cast y Android son marcas de Google LLC, y el robot de Android es obra de Google, compartida con la licencia Creative Commons Reconocimiento 3.0. Microsoft, Windows y OneDrive son marcas de Microsoft; Amazon S3, de Amazon.com, Inc. o sus filiales; Apple, AirPlay, macOS e iPhone, de Apple Inc.; Raspberry Pi, de Raspberry Pi Ltd; Ubuntu, de Canonical Ltd.; Debian, de Software in the Public Interest, Inc.; Linux, de Linus Torvalds. Este producto usa la API de TMDB, pero TMDB no lo respalda ni certifica.