Referência da API
A API pública do VDClip permite que seus servidores criem projetos, renderizem clipes, gerenciem assets de marca e publiquem em plataformas sociais. É uma API REST em https://api.vdclip.com sob /v1/*, autenticada com uma chave de API no cabeçalho Authorization.
curl https://api.vdclip.com/v1/account \
-H 'Authorization: Bearer vdck_your_key_here'A API é somente servidor-a-servidor. Não tem CORS e rejeita requisições de navegador. Mantenha sua chave vdck_... no backend e trate-a como uma senha.
Respostas bem-sucedidas retornam o recurso diretamente como JSON. Em caso de falha, a resposta retorna errors[] com code e description:
{
"errors": [
{
"code": "MISSING_SCOPE",
"description": "Esta credencial não está autorizada para vdclip:render:execute."
}
]
}Inclua o X-Request-ID ao contatar contact@vdclip.com.
O VDClip também executa um Servidor de Autorização OAuth 2.1 em /oauth2/* e /.well-known/*
para servidores MCP, agentes de IA e integrações de terceiros que atuam em nome de um usuário.
Esses endpoints usam corpos padrão RFC, não o envelope /v1. Veja OAuth 2.1.
Explore a API
Autenticação
Chaves de API, o cabeçalho Authorization Bearer e escopos
Fundamentos da REST API
URL base, envelope, paginação, erros
Projetos
Crie projetos de clipagem e legendas
Clipes
Inspecione, renderize e publique clipes
Templates
Presets reutilizáveis de layout e legenda
Assets
Uploads de assets do brand kit
Servidores MCP
Model Context Protocol para assistentes de IA
OAuth 2.1
Servidor de autorização para clientes que agem em nome de um usuário
Duas formas de autenticar
- Chave de API. A superfície principal. Envie
Authorization: Bearer vdck_...em toda requisição/v1a partir do seu próprio backend. Cada chave tem escopos que decidem o que ela pode fazer. Veja Autenticação. - OAuth 2.1. Para servidores MCP, agentes de IA e integrações de terceiros que atuam em nome de um usuário. Esses clientes enviam
Authorization: Bearer <JWT>. Veja OAuth 2.1 e Servidores MCP.
Escopos
Os escopos têm o formato vdclip:<resource>:<action>, por exemplo vdclip:projects:read. Uma requisição sem o escopo de que precisa retorna MISSING_SCOPE. Dois escopos são restritos por plano: vdclip:render:execute e vdclip:social:publish.
O catálogo completo está em Servidores MCP. Para liberar uma capacidade restrita, faça upgrade na página de preços →.
Erros e limites de taxa
Quando algo falha, o error.code diz o que fazer:
| Código | Significado |
|---|---|
INVALID_API_KEY | A chave está ausente, malformada ou revogada. |
MISSING_SCOPE | A chave é válida, mas não tem o escopo que este endpoint precisa. |
INSUFFICIENT_CREDITS | A conta está sem créditos para a ação. |
RATE_LIMITED | Requisições demais. Retornado com HTTP 429 e um cabeçalho Retry-After. |
UPSTREAM_ERROR | Um serviço interno falhou. Seguro para repetir. |
VALIDATION_ERROR | O corpo da requisição ou os parâmetros de query falharam na validação. |
INVALID_JSON | O corpo da requisição não era JSON válido. |
NOT_FOUND | O recurso não existe ou não é visível para esta chave. |
ORIGIN_REJECTED | A requisição veio de uma origem de navegador. A API é somente servidor-a-servidor. |
Em RATE_LIMITED, aguarde os segundos do Retry-After antes de repetir. Os endpoints de listagem usam paginação por cursor: passe cursor e limit, e siga o cursor retornado. Os padrões e máximos estão nas convenções da REST API.
Dicas e Boas Práticas
Nunca envie chaves vdck_ para navegadores, apps móveis ou qualquer cliente. A API não tem CORS e rejeita origens de navegador com ORIGIN_REJECTED.
Conceda a cada chave o conjunto mínimo de escopos vdclip:<resource>:<action> para limitar o raio de impacto caso ela vaze.
Em um HTTP 429, recue pelos segundos no cabeçalho Retry-After em vez de repetir imediatamente.
Armazene X-Request-ID de cada resposta para que o suporte possa rastrear qualquer problema que você reporte a contact@vdclip.com.
Use o servidor OAuth 2.1 quando um servidor MCP, agente de IA ou integração atua em nome de um usuário. Tarefas servidor-a-servidor devem usar uma chave de API.