Autenticação

A URL base é https://api.vdclip.com e a superfície REST fica sob /v1/*. Há duas formas de autenticação:

Chaves de API

Envie sua chave de API no cabeçalho Authorization como Bearer token em toda requisição /v1. As chaves têm o prefixo vdck_.

curl https://api.vdclip.com/v1/account \
  -H "Authorization: Bearer vdck_your_key_here"

Uma resposta bem-sucedida retorna o recurso diretamente:

{
  "id": "acc_...",
  "plan": "pro",
  "credits": 120
}

Paginação

Os endpoints de listagem usam paginação por cursor. Passe um limit e, para buscar a próxima página, use o cursor retornado. Os padrões e máximos variam por endpoint e estão na spec OpenAPI.

curl "https://api.vdclip.com/v1/projects?limit=20" \
  -H "Authorization: Bearer vdck_your_key_here"

Escopos

Cada escopo segue o padrão vdclip:<resource>:<action>. Uma requisição sem o escopo que seu endpoint precisa é rejeitada com MISSING_SCOPE. Os clientes OAuth solicitam os mesmos escopos. O catálogo completo está em Servidores MCP, e cada página de endpoint lista o escopo que exige.

vdclip:render:execute e vdclip:social:publish são restritos por plano: só funcionam em planos que os incluem, mesmo quando a chave carrega o escopo. Os endpoints de render também consomem créditos, retornando INSUFFICIENT_CREDITS quando eles acabam. Veja a página de preços  para saber o que cada plano inclui.

Respostas de erro

Todos os erros /v1 usam um array errors, com um code legível por máquina e uma description legível por humanos:

{
  "errors": [
    {
      "code": "MISSING_SCOPE",
      "description": "This credential is not authorized for vdclip:render:execute."
    }
  ]
}

Inclua o cabeçalho X-Request-ID de uma resposta com falha ao contatar contact@vdclip.com.

Limites de taxa

Quando você excede o limite de taxa, a API responde com HTTP 429 e um cabeçalho Retry-After (em segundos). Aguarde pelo menos esse tempo e use backoff exponencial para respostas 429 repetidas.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

OAuth 2.1 para clientes que agem em nome de um usuário

Para servidores MCP, agentes de IA e integrações de terceiros que atuam em nome de um usuário, o VDClip executa um Servidor de Autorização OAuth 2.1. Esses clientes enviam Authorization: Bearer <JWT> em vez de uma chave de API.

• O emissor é https://api.vdclip.com. Os endpoints OAuth ficam sob /oauth2/*, a descoberta sob /.well-known/*.
• Os access tokens são JWTs (at+jwt, ES256).
• Esses endpoints usam corpos padrão RFC, não o envelope /v1.
• Usam os mesmos escopos vdclip:<resource>:<action>, com a mesma restrição por plano.

Os clientes começam pela descoberta (RFC 8414), que anuncia o emissor, os endpoints de autorização/token/revogação, os escopos suportados e o JWKS URI para verificar as assinaturas dos tokens:

curl https://api.vdclip.com/.well-known/oauth-authorization-server

Com um access token, um cliente chama os mesmos endpoints /v1 com o mesmo cabeçalho Bearer:

curl https://api.vdclip.com/v1/projects \
  -H "Authorization: Bearer <JWT>"

Veja OAuth 2.1 para o fluxo completo.

Dicas e Boas Práticas

Perguntas Frequentes