Desarrolladores
API de RAMS Design Lab
Importa vídeos, consulta sus momentos, pide clips, descárgalos y prográmalos en tus redes desde tus propios scripts. La API hace lo mismo que la app, con los mismos límites de tu plan.
Antes de empezar
- La API está incluida en los planes que lo indican en Precios.
- Crea una clave en la app, pestaña Mi plan, sección Claves de API. La clave completa se muestra una sola vez: guárdala en un lugar seguro.
- Si una clave se filtra, revócala en la misma sección y crea otra. Solo guardamos una huella de la clave, nunca la clave.
En los ejemplos, rams_xxx es tu clave y RAMS_URL la dirección del servicio:
export RAMS_URL="https://tu-dominio"
export RAMS_CLAVE="rams_xxx"
Autenticación
Cada petición lleva la clave en la cabecera Authorization: Bearer. La API no usa cookies: una petición con la sesión del navegador y sin clave se rechaza.
curl -s "$RAMS_URL/api/v1/me" \
-H "Authorization: Bearer rams_xxx"
Límites de peticiones
Cada clave tiene un límite por minuto y otro por día. Los valores actuales están en limites_api de GET /api/v1/me. Al superarlos la respuesta es 429 con la cabecera Retry-After, que indica los segundos que debes esperar.
Errores
Todos los errores son JSON con un código estable y un mensaje en español:
{"error": "clave_no_valida", "detalle": "La clave de API no es válida o se revocó."}
| Estado | error | Cuándo |
|---|---|---|
| 400 | solicitud_no_valida | El enlace o el tramo del clip no son válidos. |
| 401 | falta_clave, clave_no_valida | No hay clave, es incorrecta o se revocó. |
| 403 | plan_sin_api, no_permitido | Tu plan no incluye la API o no permite esa acción. |
| 404 | no_encontrado | El vídeo o el clip no existe o no es tuyo. |
| 409 | limite_del_plan, conflicto | No te quedan clips en el plan o el vídeo aún no está listo. |
| 422 | datos_no_validos | El cuerpo JSON no tiene los campos esperados. |
| 429 | demasiadas_peticiones | Superaste el límite de la clave. |
Endpoints
GET /api/v1/me
Tu cuenta, tu plan, el uso del periodo (clips, minutos de análisis y de IA) y los límites de la clave.
POST /api/v1/videos
Importa un vídeo público tuyo por enlace. Pasa las mismas comprobaciones que en la app y gasta minutos de análisis igual. La respuesta trae el id del vídeo y su estado.
curl -s -X POST "$RAMS_URL/api/v1/videos" \
-H "Authorization: Bearer rams_xxx" \
-H "Content-Type: application/json" \
-d '{"url": "https://www.youtube.com/watch?v=TU_VIDEO"}'
GET /api/v1/videos/{id}
El estado del vídeo (comprobando, descargando, listo, analizando, analizado o error) y sus momentos sugeridos, cada uno con inicio, fin, título, puntuación viral de 0 a 100, motivo y transcripción.
curl -s "$RAMS_URL/api/v1/videos/0123456789abcdef" \
-H "Authorization: Bearer rams_xxx"
POST /api/v1/videos/{id}/clips
Renderiza el tramo inicio-fin (en segundos) como clip. Gasta un clip de tu plan. titulo es opcional: si guardaste un estilo en el editor, se usa como título de gancho. Responde 202 con el clip en estado esperando.
curl -s -X POST "$RAMS_URL/api/v1/videos/0123456789abcdef/clips" \
-H "Authorization: Bearer rams_xxx" \
-H "Content-Type: application/json" \
-d '{"inicio": 754.5, "fin": 792, "titulo": "No esperaba este final"}'
GET /api/v1/clips y GET /api/v1/clips/{id}
Tus clips con su estado (esperando, procesando, listo o error) y, cuando están listos, las direcciones de descarga por formato en descargas. El id de un clip tiene la forma canal~fecha, por ejemplo video-0123456789abcdef~2026-11-20_18-04-11.
curl -s "$RAMS_URL/api/v1/clips" \
-H "Authorization: Bearer rams_xxx"
GET /api/v1/clips/{id}/descargar?formato=
Descarga el archivo. formato es uno de los que aparecen en descargas (por ejemplo difuminado, zoom, camara, editado u original), o srt para los subtítulos. Las direcciones también piden la clave.
curl -s -o clip.mp4 \
"$RAMS_URL/api/v1/clips/video-0123456789abcdef~2026-11-20_18-04-11/descargar?formato=difuminado" \
-H "Authorization: Bearer rams_xxx"
POST /api/v1/publicaciones
Publica un clip en tus redes conectadas, al momento o en la fecha de cuando (ISO 8601). cuentas son los identificadores de tus cuentas conectadas en Publicar en redes. textos es opcional: por red, o "*" para todas, con titulo, descripcion y hashtags.
curl -s -X POST "$RAMS_URL/api/v1/publicaciones" \
-H "Authorization: Bearer rams_xxx" \
-H "Content-Type: application/json" \
-d '{"clip": "video-0123456789abcdef~2026-11-20_18-04-11",
"formato": "difuminado", "cuentas": [3],
"cuando": "2026-11-21T18:00:00Z",
"textos": {"*": {"titulo": "No esperaba este final", "hashtags": ["directo"]}}}'
Un flujo completo
- Importa el vídeo con
POST /api/v1/videosy guarda suid. - Consulta
GET /api/v1/videos/{id}cada pocos segundos hasta que el estado seaanalizado. - Elige los momentos con mejor puntuación y pide cada clip con
POST /api/v1/videos/{id}/clips. - Espera a que cada clip esté
listoy descárgalo, o prográmalo conPOST /api/v1/publicaciones.
Respeta Retry-After cuando recibas un 429 y no consultes más de una vez por segundo.