REST + MCP · MEDIDO EN CRÉDITOS
Abre una sesión, conversa, aprueba el guion en el gate, recibe un enlace MP4 alojado. REST y MCP, 1:1. Medido en créditos — las fallas del sistema se reembolsan automáticamente.
Enlace entregado, o reembolso automático — solo fallas del sistema.
animated-explainer · certificado · 16:9 — un render entregado real. hold 500 → capture 308 → release 192.
ABRIR → CONVERSAR → GATE → ENTREGAR
POST /v1/sessions (open_session vía MCP) con un pipeline, un brief y budget_credits. El presupuesto queda retenido, no gastado — credits: {budget, held, spent} en cada consulta desde ese momento.
POST …/messages devuelve 202 {turn_id}; el motor investiga, escribe el guion y prepara los assets mientras tu agente consulta get_session o recibe eventos por streaming. Todo es asíncrono — no existe una llamada síncrona de "dame un video".
En status: awaiting_gate, tu agente lee el artifact_excerpt (o el artefacto completo en GET …/artifacts/:name) y luego POST …/gates/:gateId — approve, o revise con feedback. Nada se renderiza hasta que el gate se resuelve.
video_url aparece en el momento en que un render alojado realmente existe — el punto se llena. POST …/close libera la retención no gastada.
Si el sistema no puede entregar, el turno se reembolsa automáticamente. No pagas por un render que falla de nuestro lado.
QUICKSTART
curl -sX POST $BASE/v1/sessions \
-H "authorization: Bearer $KEY" -H "content-type: application/json" \
-H "idempotency-key: drpost-sess-42" \
-d '{"pipeline":"animated-explainer","budget_credits":500,"format":"9:16",
"brief":"Explain how our invoicing API works, 60s, friendly"}'curl -sX POST $BASE/v1/sessions/$SID/messages \
-H "authorization: Bearer $KEY" -H "content-type: application/json" \
-d '{"message":"Explain how our invoicing API works, 60s, friendly tone"}'claude mcp add --transport http macaroni \
https://api.macaroni.video/mcp \
--header "Authorization: Bearer $MAC_KEY"{
"mcpServers": {
"macaroni": {
"type": "http",
"url": "https://api.macaroni.video/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}EL CONTRATO, PUNTO POR PUNTO
video_url — no nulo si y solo si existe un video reproduciblevideo_url se asigna si y solo si existe un MP4 alojado resoluble por el gateway — nunca un placeholder, nunca obsoleto. video.ready se emite solo entonces; de lo contrario el turno se liquida como no_deliverable y se reembolsa automáticamente. Tu agente nunca tiene que detectar un enlace muerto, porque un enlace muerto nunca recibe URL.
abrir → conversar → gate → enlace entregado. En awaiting_gate, tu agente lee el artifact_excerpt — guion y escenas — y resuelve el gate: approve, o revise con feedback, antes de que un crédito se renderice. Las aprobaciones son manuales por diseño; tu agente las resuelve de forma programática — el punto de decisión es la funcionalidad.
Abrir una sesión retiene tu presupuesto; cada turno captura solo el gasto real; close libera el resto — visible como credits: {budget, held, spent} en cada consulta. Una falla del sistema reembolsa el turno automáticamente: una entrada refund en GET /v1/credits. Tus acciones — user_interrupted, budget_exceeded — facturan el gasto real y no se reembolsan. Cada falla lleva un failure_class; engine_error se reembolsa automáticamente junto con no_deliverable.
Los topes de gasto de modelo por sesión fallan cerrados: si el proxy que aplica el tope no está disponible, los turnos se niegan a iniciar en lugar de correr sin límite. El motor de cada sesión corre en su propio sandbox aislado y efímero — terminado con POST …/interrupt, nunca compartido entre cuentas. Idempotency-Key hace que cada reintento sea seguro de repetir. El default seguro es "no hacer nada", nunca "gastar libremente".
animated-explainer está certificado para entrega alojada. Los otros 12 pipelines son experimentales y están marcados como tales en todos los lugares donde aparecen — una ejecución experimental que termina sin video alojado se liquida como no_deliverable y se reembolsa automáticamente. list_pipelines te dice cuál es cuál; este sitio también.
POST /v1/providers/keys almacena tus claves de proveedor — AES-256-GCM en reposo; byok: true en open_session ejecuta el pipeline con ellas. Nunca se devuelven y nunca recurren a las claves de la plataforma — almacena una clave para cada proveedor que el pipeline necesite o la ejecución falla. Una excepción: sin tu propia clave de Anthropic, el modelo de razonamiento corre medido con la nuestra.
Horizontal para YouTube, LinkedIn, X y embeds — o vertical para TikTok, Reels y Shorts. Cada video entregado es un MP4 alojado. get_video devuelve width, height y aspect_ratio, así que quien llama enruta por plataforma sin sondear el archivo. Los enlaces para compartir se transmiten a través del gateway, con seek vía Range, y están pensados para ser de larga vida (alrededor de un año). Vertical 9:16 vía format en open_session — horizontal y vertical desde la misma sesión.
claude mcp add --transport http macaroni … y tu agente tiene la superficie completa: 14 herramientas, cada una espejo de un endpoint REST vivo, sobre Streamable HTTP sin estado en POST /mcp.
GET /v1/credits
Todo se mide en créditos enteros. Abrir una sesión → una retención del presupuesto. Cada turno captura solo su gasto real. Cerrar → la retención no gastada se libera. Una falla causada por el sistema reembolsa automáticamente el turno. Todo es visible: credits: {budget, held, spent} en cada consulta, el libro mayor completo en GET /v1/credits.
| entrada | tipo | créditos |
|---|---|---|
| open_session · budget_credits reservados, no gastados | hold | 500 |
| turno liquidado · solo el gasto real | capture | 308 |
| close · la retención no gastada, devuelta | release | 192 |
solo fallas del sistema — user_interrupted y budget_exceeded facturan el gasto real.
FAQ
Créditos, nunca dólares. Una sesión retiene un presupuesto que tú defines — el default es una estimación por pipeline, unos 500 créditos para un explainer. Los turnos capturan el gasto real; la retención no gastada se libera al cerrar. Consulta GET /v1/credits en cualquier momento — cada retención, captura, liberación y reembolso es una entrada del libro mayor. Detalles: /docs/api.
Cada falla está tipificada. Las fallas causadas por el sistema (infra_error, engine_error, no_deliverable) no te cuestan nada — nunca se facturan, o se reembolsan automáticamente. Tus acciones (user_interrupted, budget_exceeded) facturan el gasto real y no se reembolsan. La tabla de fallas completa, con recuperación documentada por tipo: /docs/integration.
No cuando la falla es nuestra. Un turno que termina sin un enlace alojado y reproducible se liquida como no_deliverable y reembolsa sus créditos automáticamente — la entrada refund aparece en GET /v1/credits. Si interrumpes un turno o excedes tu presupuesto, se factura el gasto real hasta ese punto; esas son decisiones tuyas, no fallas nuestras. /docs/integration.
MCP sobre Streamable HTTP en POST /mcp: un bloque de configuración o un comando claude mcp add — mira el quickstart arriba. 14 herramientas, cada una espejo de un endpoint REST vivo; REST es 1:1 si prefieres curl. /docs/mcp.
animated-explainer está certificado para entrega alojada. Doce más son experimentales y están etiquetados como tales — pueden terminar el trabajo creativo sin producir un video alojado, lo que se liquida como no_deliverable y se reembolsa automáticamente. El catálogo con marcadores de estabilidad: /docs/api.
Sí. POST /v1/providers/keys las almacena — AES-256-GCM en reposo, nunca devueltas, sin fallback a claves de la plataforma, así que almacena una clave para cada proveedor que tu pipeline necesite. Establece byok: true en open_session para ejecutar con ellas. Una excepción: sin tu propia clave de Anthropic, el modelo de razonamiento corre medido con la nuestra. La gestión de claves es solo REST. /docs/api.
16:9 horizontal o 9:16 vertical — eliges por sesión. Cada video entregado es un MP4 alojado, y get_video devuelve width, height y aspect_ratio para que tu agente enrute por plataforma sin sondear el archivo. /docs/api. Vertical 9:16 disponible vía format en open_session — misma sesión, mismo contrato.
La autenticación es solo Bearer, sin cookies — un EventSource nativo no puede enviar el encabezado Authorization. Usa fetch con streaming para SSE (GET /v1/sessions/:id/events, reanudable vía Last-Event-ID), o el ciclo de consulta documentado, que es la integración correcta más simple. /docs/integration.
Son URLs estables, no adivinables, con noindex, que transmiten el MP4 a través de nuestro gateway — con seek vía Range, sin clave de API para ver. Están pensados para ser de larga vida, del orden de un año. Declaramos la intención en lugar de prometer una garantía que no ofrecemos. /docs/api.
Hoy no. Contáctanos para créditos de evaluación — los créditos se aprovisionan a tu cuenta.
POST /v1/sessions
Lee la documentación primero — la tabla de fallas y el contrato de video_url son lo que estás evaluando. Cuando un turno entrega, el enlace abre. Cuando el sistema falla, el libro mayor muestra el reembolso. Enviamos tus claves por correo y hacemos el onboarding de cada cuenta directamente.