Documentação

API v1

Crie vídeos a partir do seu sistema. Autentique com uma chave criada em Configurações → Chaves da API. Cada chave tem escopos e limite de requisições por minuto. O fluxo é o mesmo do painel: projeto → ideias → briefing → orçamento → aprovação → vídeo.

Autenticação

Authorization: Bearer gk_live_xxxxxxxx_...

1. Criar projeto

curl -X POST https://guoki.com.br/api/v1/projects \
  -H "Authorization: Bearer $GUOKI_KEY" -H "Content-Type: application/json" \
  -d '{"brandKitId":"<uuid>","title":"Oferta de sexta","objective":"Oferta promocional",
       "format":"9:16","durationSec":30,"notes":"Combo a R$ 29,90 só sexta"}'
# → 201 {"id":"<projeto>","status":"CREATED"}  (as ideias começam a ser geradas)

2. Gerar o briefing

curl -X POST https://guoki.com.br/api/v1/projects/<id>/briefing -H "Authorization: Bearer $GUOKI_KEY" -d '{}'
# → 202 {"queued":true}. Ou envie {"content":{...briefing...}} para gravar uma versão sua.

3. Consultar status, briefing e orçamento

curl https://guoki.com.br/api/v1/projects/<id> -H "Authorization: Bearer $GUOKI_KEY"
# → {"status":"BRIEFING_READY","briefing":{...},"quote":{"credits":180,"cents":1800,...},"progress":0,"video":null}

4. Aprovar e produzir

curl -X POST https://guoki.com.br/api/v1/projects/<id>/approve -H "Authorization: Bearer $GUOKI_KEY" \
  -H "Idempotency-Key: pedido-123"
# → 202 {"jobId":"...","quote":{...}}   402 se faltar crédito. Repetir com a mesma chave não cobra duas vezes.

5. Baixar o vídeo

curl https://guoki.com.br/api/v1/projects/<id>/video -H "Authorization: Bearer $GUOKI_KEY"
# → {"url":"…/api/media/…?exp=…&sig=…","expiresAt":"…"}  (link assinado, válido por 3 dias)

Saldo e consumo

GET /api/v1/credits/balance   → {"balance":1820,"held":0,"available":1820}
GET /api/v1/usage             → {"periodDays":30,"videosCompleted":4,...}

Erros

JSON {"error":"mensagem","code":"..."}. Códigos: 401 chave inválida, 403 escopo, 402 créditos insuficientes, 409 estado não permite, 422 dados inválidos, 429 limite de requisições.

API · Guoki