Use a API REST da Clevera

A API REST da Clevera permite que seus próprios scripts e serviços façam o que um agente pode fazer via MCP: ler sua biblioteca, solicitar vídeos e artigos, exportar vídeos, trabalhar em sites de documentação e acompanhar os trabalhos. Este artigo aborda a URL base, autenticação, o fluxo de solicitação para trabalhos pagos, erros e limites de taxa.

Noções básicas#

Verifique um token com GET /docs/me:

curl -H "Authorization: Bearer $CLEVERA_TOKEN" \
     -H "Accept: application/json" \
     https://app.clevera.ai/api/v1/docs/me

A resposta diz em nome de quem o token atua: o nome e a validade do token, a pessoa e seu cargo atual, o workspace, os sites no escopo e as permissões que funcionam no momento (as permissões do token reduzidas ao cargo atual da pessoa). Chame-o primeiro quando uma chamada for recusada.

Endpoints#

Cada endpoint precisa da permissão mostrada. Chamar um sem ela retorna 403 forbidden_ability. Veja Permissões do agente.

Biblioteca e materiais#

Vídeos e artigos#

Trabalhos e créditos#

Sites de documentação#

Mais sobre agentes e sites de documentação: Conectar agentes de IA aos seus sites de documentação.

Solicitar trabalho pago#

Trabalhos que custam créditos sempre passam pela cotação primeiro, depois iniciam:

1. Cote. POST /videos/quotes (ou /clips/quotes) com o que você deseja. A resposta tem um quote_id e o intervalo de crédito. Uma cotação é válida por 15 minutos e pode ser usada uma vez.
2. Opcionalmente, faça um teste. Envie o início com "dry_run": true para saber se ele iniciaria, precisaria de aprovação ou seria bloqueado. Nada é gravado.
3. Inicie. POST /videos com quote_id e um cabeçalho Idempotency-Key. A resposta é 202 com um trabalho.
4. Acompanhe. GET /jobs/{job}/wait até que o status do trabalho mude, ou ouça webhooks.

curl -X POST https://app.clevera.ai/api/v1/videos/quotes \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "how_to", "recording_id": "<recording id>", "language": "en-US"}'

curl -X POST https://app.clevera.ai/api/v1/videos \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c1a2e-8d4b-4f7a-9c1e-2b5d7e9f0a13" \
  -d '{"quote_id": "<quote id>"}'

Status dos trabalhos:

Se um início é executado imediatamente ou aguarda uma pessoa depende dos limites de gastos do token e da sua configuração Aprovar automaticamente abaixo. Veja Controlar gastos e aprovações do agente.

Novas tentativas e idempotência#

Envie um cabeçalho Idempotency-Key (um UUID novo por ação) em cada criação e início. Se a rede cair e você tentar novamente com a mesma chave e corpo, você recebe a primeira resposta de volta em vez de um segundo vídeo. As chaves são lembradas por 24 horas.

Erros#

Todo erro tem o mesmo formato, com uma mensagem que diz o que fazer a seguir:

{
  "error": {
    "code": "forbidden_ability",
    "message": "This token lacks the videos:create ability. Ask the workspace member who owns it for a token that has it.",
    "details": { "ability": "videos:create" }
  },
  "request_id": "req_example"
}

Inclua o request_id ao entrar em contato com o suporte.

Cada mensagem, com a correção: Corrigir erros do agente e da API.

Limites de taxa#

Uma resposta 429 tem um cabeçalho Retry-After e retry_after (segundos) no corpo. Aguarde esse tempo antes de tentar novamente. Leituras, cotações e verificações de status não custam créditos.

Relacionado#