REST API

A API pública do VDClip é uma interface REST servidor-a-servidor sob https://api.vdclip.com/v1. Você autentica com Authorization: Bearer <token>, onde o token é uma chave de API do VDClip (vdck_...) ou um access token OAuth. Cada credencial tem escopo para os recursos que você conceder.

URL base e versionamento

• URL base: https://api.vdclip.com
• Superfície REST: todo endpoint tem o prefixo /v1, por exemplo https://api.vdclip.com/v1/projects.
• Superfície OAuth: o servidor OAuth 2.1 fica sob /oauth2/* e /.well-known/*. Esses endpoints seguem as RFCs relevantes. Veja Autenticação.

Autenticação

Envie sua chave de API no cabeçalho Authorization como Bearer token em toda requisição /v1.

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

As chaves de API carregam um conjunto fixo de escopos e consomem do seu saldo de créditos. Para clientes que atuam em nome de um usuário, use OAuth 2.1 com um token Bearer; veja OAuth 2.1.

Respostas

Endpoints /v1 bem-sucedidos retornam o recurso diretamente como JSON. Erros retornam um array errors. Inclua os cabeçalhos X-Request-ID e X-Trace-ID ao contatar contact@vdclip.com.

{
  "errors": [
    {
      "code": "INSUFFICIENT_CREDITS",
      "description": "Your account does not have enough credits for this operation."
    }
  ]
}

Códigos de erro

Paginação

Os endpoints de listagem usam paginação por cursor: limit define o tamanho da página, e cursor é um token opaco da página anterior (não faça parse nem o construa você mesmo). Os padrões e máximos variam por endpoint e estão definidos na spec OpenAPI.

# First page
curl 'https://api.vdclip.com/v1/projects?limit=20' \
  -H 'Authorization: Bearer vdck_your_key_here'
 
# Next page, using the cursor from the previous response
curl 'https://api.vdclip.com/v1/projects?limit=20&cursor=eyJpZCI6IjEyMyJ9' \
  -H 'Authorization: Bearer vdck_your_key_here'

Escopos

Os escopos seguem o padrão vdclip:<resource>:<action>. Há 15. Uma requisição sem o escopo que um endpoint exige falha com MISSING_SCOPE. Dois escopos são restritos por plano: vdclip:render:execute e vdclip:social:publish exigem um plano que os inclua. Veja a página de preços.

Referência de endpoints

Todos os endpoints /v1, agrupados por recurso. Schemas completos, corpos de requisição são gerados a partir da spec OpenAPI.

Account

Projects

Clips

Templates

Assets

Calendar

Social

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

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

Páginas relacionadas

Dicas e Boas Práticas

Perguntas Frequentes