REST + MCP · MEDIDO EM CRÉDITOS
Abra uma sessão, converse, aprove o roteiro no gate, receba um link de MP4 hospedado. REST e MCP, 1:1. Medido em créditos — falhas do sistema são reembolsadas automaticamente.
Link entregue, ou reembolso automático — apenas falhas do sistema.
animated-explainer · certificado · 16:9 — um render real, entregue. hold 500 → capture 308 → release 192.
ABRIR → CONVERSAR → GATE → ENTREGAR
POST /v1/sessions (open_session via MCP) com um pipeline, um briefing e budget_credits. O orçamento é reservado, não gasto — credits: {budget, held, spent} em cada poll daqui em diante.
POST …/messages retorna 202 {turn_id}; a engine pesquisa, roteiriza e prepara os assets enquanto seu agente faz polling de get_session ou acompanha o stream de eventos. Tudo é assíncrono — não existe chamada síncrona de "me dá um vídeo".
Em status: awaiting_gate, seu agente lê o artifact_excerpt (ou o artifact completo em GET …/artifacts/:name) e então POST …/gates/:gateId — approve, ou revise com feedback. Nada renderiza até o gate ser resolvido.
video_url aparece no momento em que um render hospedado existe de fato — o ponto acende. POST …/close libera a reserva não gasta.
Se o sistema não consegue entregar, o turno é reembolsado automaticamente. Você não paga por um render quando a falha é nossa.
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" }
}
}
}O CONTRATO, ITEM POR ITEM
video_url — não nulo se e somente se existe um vídeo reproduzívelvideo_url é definido se e somente se existe um MP4 hospedado resolvível pelo gateway — nunca um placeholder, nunca um link velho. video.ready dispara só nesse caso; caso contrário o turno é liquidado como no_deliverable e reembolsado automaticamente. Seu agente nunca precisa detectar link morto, porque link morto nunca ganha URL.
abrir → conversar → gate → link entregue. Em awaiting_gate, seu agente lê o artifact_excerpt — roteiro e cenas — e resolve o gate: approve, ou revise com feedback, antes de um crédito sequer renderizar. Aprovações são manuais por design; seu agente as resolve programaticamente — o ponto de decisão é a feature.
Abrir uma sessão reserva seu orçamento; cada turno captura só o gasto real; close libera o restante — visível como credits: {budget, held, spent} em cada poll. Uma falha do sistema reembolsa o turno automaticamente: um lançamento refund em GET /v1/credits. Suas ações — user_interrupted, budget_exceeded — cobram o gasto real e não são reembolsadas. Toda falha carrega um failure_class; engine_error é reembolsado automaticamente, junto com no_deliverable.
Tetos de gasto de modelo por sessão falham fechados: se o proxy que aplica os tetos está indisponível, os turnos se recusam a iniciar em vez de rodar sem limite. A engine de cada sessão roda no próprio sandbox isolado e efêmero — terminado em POST …/interrupt, nunca compartilhado entre contas. Idempotency-Key torna todo retry seguro de repetir. O padrão seguro é "não fazer nada", nunca "gastar à vontade".
animated-explainer é certificado para entrega hospedada. Os outros 12 pipelines são experimentais e marcados como tal em todo lugar onde aparecem — um run experimental que termina sem vídeo hospedado é liquidado como no_deliverable e reembolsado automaticamente. list_pipelines diz qual é qual; este site também.
POST /v1/providers/keys armazena suas chaves de provedor — AES-256-GCM em repouso; byok: true em open_session roda o pipeline com elas. Elas nunca são retornadas e não há fallback para chaves da plataforma — armazene uma chave para cada provedor que o pipeline usa, ou o run falha. Uma exceção: sem a sua própria chave Anthropic, o modelo de raciocínio roda medido nas nossas.
Horizontal para YouTube, LinkedIn, X e embeds — ou vertical para TikTok, Reels e Shorts. Todo vídeo entregue é um MP4 hospedado. get_video retorna width, height e aspect_ratio, então quem chama roteia por plataforma sem inspecionar o arquivo. Os links de compartilhamento são servidos em streaming pelo gateway, com seek via Range, e a intenção é que durem — cerca de um ano. 9:16 vertical via format em open_session — horizontal e vertical a partir da mesma sessão.
claude mcp add --transport http macaroni … e seu agente tem a superfície completa: 14 tools, cada uma espelhando um endpoint REST vivo, via Streamable HTTP stateless em POST /mcp.
GET /v1/credits
Tudo é medido em créditos inteiros. Abrir uma sessão → uma reserva de orçamento. Cada turno captura só o gasto real. Fechar → a reserva não gasta é liberada. Uma falha causada pelo sistema reembolsa automaticamente o turno. Tudo fica visível: credits: {budget, held, spent} em cada poll, o ledger completo em GET /v1/credits.
| lançamento | tipo | créditos |
|---|---|---|
| open_session · budget_credits reservados, não gastos | hold | 500 |
| turno liquidado · apenas o gasto real | capture | 308 |
| close · a reserva não gasta devolvida | release | 192 |
apenas falhas do sistema — user_interrupted e budget_exceeded cobram o gasto real.
FAQ
Créditos, nunca dólares. Uma sessão reserva um orçamento que você define — o padrão é uma estimativa por pipeline, cerca de 500 créditos para um explainer. Os turnos capturam o gasto real; a reserva não gasta é liberada no close. Consulte GET /v1/credits a qualquer momento — cada reserva, captura, liberação e reembolso é um lançamento no ledger. Detalhes: /docs/api.
Toda falha é tipada. Falhas causadas pelo sistema (infra_error, engine_error, no_deliverable) não custam nada para você — nunca cobradas, ou reembolsadas automaticamente. Suas ações (user_interrupted, budget_exceeded) cobram o gasto real e não são reembolsadas. A tabela completa de falhas, com recuperação documentada por tipo: /docs/integration.
Não quando a falha é nossa. Um turno que termina sem um link hospedado e reproduzível é liquidado como no_deliverable e os créditos são reembolsados automaticamente — o lançamento refund aparece em GET /v1/credits. Se você interrompe um turno ou estoura o orçamento, o gasto real até ali é cobrado; essas são decisões suas, não falhas nossas. /docs/integration.
MCP via Streamable HTTP em POST /mcp: um bloco de config ou um comando claude mcp add — veja o quickstart acima. 14 tools, cada uma espelhando um endpoint REST vivo; a REST é 1:1 se você preferir curl. /docs/mcp.
animated-explainer é certificado para entrega hospedada. Outros doze são experimentais e marcados como tal — podem concluir o trabalho criativo sem produzir um vídeo hospedado, o que liquida o turno como no_deliverable e reembolsa automaticamente. O catálogo com marcadores de estabilidade: /docs/api.
Sim. POST /v1/providers/keys as armazena — AES-256-GCM em repouso, nunca retornadas, sem fallback para chaves da plataforma, então armazene uma chave para cada provedor que seu pipeline usa. Defina byok: true em open_session para rodar com elas. Uma exceção: sem a sua própria chave Anthropic, o modelo de raciocínio roda medido nas nossas. A gestão de chaves é só via REST. /docs/api.
16:9 horizontal ou 9:16 vertical — você escolhe por sessão. Todo vídeo entregue é um MP4 hospedado, e get_video retorna width, height e aspect_ratio para o seu agente rotear por plataforma sem inspecionar o arquivo. /docs/api. 9:16 vertical está disponível via format em open_session — mesma sessão, mesmo contrato.
A autenticação é só Bearer, sem cookies — um EventSource nativo não envia o header Authorization. Use fetch com streaming para SSE (GET /v1/sessions/:id/events, retomável via Last-Event-ID), ou o loop de polling documentado, que é a integração correta mais simples. /docs/integration.
São URLs estáveis, não adivinháveis e noindex que servem o MP4 em streaming pelo nosso gateway — com seek via Range, sem chave de API para assistir. A intenção é que durem — na casa de um ano. Declaramos a intenção em vez de prometer uma garantia que não oferecemos. /docs/api.
Hoje, não. Entre em contato para créditos de avaliação — créditos são provisionados na sua conta.
POST /v1/sessions
Leia a documentação primeiro — a tabela de falhas e o contrato de video_url são o que você está avaliando. Quando um turno entrega, o link abre. Quando o sistema falha, o ledger mostra o reembolso. Enviamos suas chaves por e-mail e fazemos o onboarding de cada conta diretamente.