# Polf API

> API B2B do Polf (polf.ai): transforma vídeo longo em cortes verticais (Reels/TikTok/Shorts) com legenda PT-BR queimada. REST + JSON, assíncrona (create → webhook/poll → download). Contrato compatível com a Vizard + extras v2: webhooks nomeados assinados (HMAC Stripe-style), download durável que não expira, idempotencyKey anti-cobrança-dupla, sandbox polf-test:// pra CI e publicação social.

Base URL: https://api.polf.ai — Auth: header `INSTACUT_API_KEY: ik_...` (peça a sua ao suporte).

## Docs

- [Documentação completa da API](https://app.polf.ai/docs/api): quickstart curl, autenticação, referência de endpoints, webhooks com payloads de exemplo, verificação HMAC (Node e Python), sandbox, catálogo de erros, rate limits e retenção
- [OpenAPI 3.1 (JSON)](https://app.polf.ai/api/openapi.json): spec das rotas públicas /api/v1/*, gerada do código real — use pra gerar tipos/SDK
- [llms-full.txt](https://app.polf.ai/llms-full.txt): esta documentação inteira em um único markdown (contexto completo pra agentes)

## Conceitos-chave

- Endpoints de clipping respondem HTTP 200 com envelope {code}: 2000 ok, 1000 processando, 4xxx erro (compat-Vizard). Endpoints novos (download, social) usam status HTTP semânticos.
- status v2 do projeto (string): queued | processing | done | failed. stage: download | transcribe | select | render. Progresso = clipsReady/clipsTotal (contagem real, sem porcentagem inventada).
- Erro v2 estruturado: {errorCode, message (PT-BR), retriable, stage}. errorCode estável: SOURCE_UNAVAILABLE, NO_CREDITS, LANGUAGE_UNSUPPORTED, RENDER_FAILED, INTERNAL, NO_CLIPS (reservado), PUBLISH_FAILED (posts).
- Webhooks v2 (envelope: event, eventId, createdAt, apiVersion 2026-07-01, projectId, externalUserId, data): project.selected, clip.rendered, clip.failed, project.completed, project.failed, post.published, post.failed. Entrega at-least-once (dedup por eventId), ordem não garantida, assinatura header Polf-Signature: t=<unix>,v1=HMAC-SHA256(webhook_secret, "t.corpo_cru"), janela anti-replay 300s. Retry: 3× na hora (0/+5s/+30s) + re-entrega em background por até 24h (a cada ~15min, máx 8 tentativas, MESMO eventId). Todo projeto termina com evento terminal (completed ou failed) — inclusive interrupção no servidor.
- Uso/saldo self-service: GET /api/v1/usage → {credits: {unit: source_minutes, used, limit, remaining, period, periodStart}, posts: {month, limit}, suspended}. Mesma info via MCP tool get_credits.
- Sandbox (contrato público): videoUrl = polf-test://success | fail-source | fail-render | slow simula o fluxo inteiro (webhooks reais, clips fake "[SANDBOX]", download real de asset fixo) SEM gastar crédito/GPU. Payloads levam "sandbox": true.
- Download durável: GET /api/v1/clips/{clipId}/download → 302 pra presigned fresca com Content-Disposition: attachment. Retenção dos arquivos: 30 dias (depois 410). streamUrl/thumbnailUrl presigned expiram ~1h — persista o downloadUrl.
- Rate limits por chave (janela 60s): create e POSTs caros 20/min; leitura 120/min. Headers RateLimit-Limit/Remaining/Reset em toda resposta; 429 com Retry-After.
- Travas de postagem (posts sociais): teto/dia + espaçamento mínimo por conta/rede + rampa de aquecimento de conta recém-conectada (~14 dias, começa em 1/dia). Estourou → HTTP 429 {errorCode: RATE_PROTECTED, retriable: true, nextSlot}. scheduledAt: "auto" no POST /api/v1/posts agenda no próximo horário seguro (resposta ecoa o horário resolvido).

## Optional

- [Site](https://polf.ai): produto Polf (app em app.polf.ai)
- [Termos de Uso](https://app.polf.ai/termos)