Referência de API

Autenticação

Todas as solicitações da API exigem uma API key. Você pode obtê-la em Settings > API Keys.

Formatos suportados:

Lembretes de segurança:

• nunca exponha sua API key em código cliente
• faça sempre as chamadas da API a partir do servidor

Visão geral dos endpoints

POST /api/v1/video

Cria uma tarefa permanente de vídeo a partir da sua configuração. Esta operação ainda não inicia a renderização.

Campos importantes:

Campos de resposta mais úteis:

• taskId
• videoTaskId
• previewUrl
• viewerUrl
• configUrl
• status
• quality
• width
• height
• duration

GET /api/v1/video

Lista todas as tarefas de vídeo da conta atual.

Parâmetros de query:

A resposta contém uma lista tasks e um objeto pagination.

GET /api/v1/video/:taskId

Recupera os detalhes completos de uma tarefa específica de vídeo.

Campos de retorno úteis:

• taskId
• videoTaskId
• status
• videoUrl
• previewUrl
• viewerUrl
• configUrl
• costCredits
• createdAt
• completedAt
• metadata

Valores de status:

DELETE /api/v1/video/:taskId

Exclui permanentemente uma tarefa e os registros locais de render associados. A API também tenta excluir a tarefa remota upstream.

Campos de resposta importantes:

• deleted
• remoteDeleted
• message

Se a exclusão upstream falhar, a exclusão local ainda pode ter sido concluída corretamente.

POST /api/v1/video/:taskId/render

Inicia ou reinicia a renderização de uma tarefa existente.

Corpo da requisição:

Resultados possíveis:

• uma nova renderização com status: rendering
• uma resposta reaproveitando um render já concluído com alreadyRendered: true

Erros frequentes:

• NOT_FOUND
• ALREADY_RENDERING
• INSUFFICIENT_CREDITS
• RENDER_TRIGGER_FAILED

Webhooks

webhook_url é suportado em:

• POST /api/v1/video/:taskId/render
• POST /api/v1/preview/:tempId/render

Fluxo de funcionamento:

1. sua webhook_url é salva junto da tarefa de render
2. o renderer upstream retorna completed ou failed
3. o projeto atualiza primeiro o banco local
4. em seguida envia um POST para a sua webhook_url

O payload reenviado normalmente inclui:

• taskId
• renderTaskId
• status
• videoUrl
• error
• timestamp

Limitações atuais:

• apenas completed e failed são reenviados
• webhook_url precisa ser uma URL absoluta válida
• ainda não existe assinatura de webhook
• ainda não existe fila de retry nem log de entrega

POST /api/v1/upload

Permite enviar imagens, vídeos e áudios para uso posterior em configurações de vídeo.

Campos do formulário:

*Pelo menos um entre file ou files é obrigatório.

Famílias MIME suportadas:

• image/*
• video/*
• audio/*

Limites de armazenamento por plano:

A resposta de sucesso inclui count e uma lista assets.

GET /api/v1/files

Lista os arquivos enviados para o proprietário atual da API key.

Parâmetros de query:

A resposta inclui files e pagination.

DELETE /api/v1/files/:fileId

Exclui permanentemente um arquivo da biblioteca. Tanto o objeto armazenado quanto o registro do arquivo são removidos.

Campos de resposta úteis:

• fileId
• deleted
• message

GET /api/v1/credits

Recupera o saldo atual de créditos da conta.

Resposta típica:

{
  "success": true,
  "credits": 985,
  "currency": "credits"
}

POST /api/v1/preview

Cria uma preview temporária sem consumir créditos.

Regras importantes:

• o schema completo do vídeo é enviado diretamente no body
• links de preview duram 7 dias
• a preview não consome créditos
• a preview não gera arquivo de vídeo para download

Campos de resposta:

• tempId
• previewUrl
• viewerUrl
• expiresIn

GET /api/v1/preview/:tempId

Lê a configuração por trás de um link temporário de preview.

Campos de retorno:

• tempId
• config

DELETE /api/v1/preview/:tempId

Exclui um link temporário de preview.

Campos de retorno:

• tempId
• deleted
• message

POST /api/v1/preview/:tempId/convert

Clona uma preview temporária em uma tarefa permanente de vídeo. A preview temporária continua disponível.

Corpo opcional:

Campos de retorno mais úteis:

• converted
• taskId
• videoTaskId
• previewUrl
• viewerUrl
• configUrl

POST /api/v1/preview/:tempId/render

Clona uma preview temporária em uma tarefa permanente e dispara imediatamente a renderização.

Corpo da requisição:

Resposta de sucesso típica:

• converted: true
• taskId
• renderTaskId
• status: rendering
• cost
• remainingCredits
• previewUrl
• viewerUrl

Cálculo de créditos

A regra de custo é:

• custo = duração do vídeo em segundos × multiplicador de qualidade

A qualidade é determinada automaticamente a partir da menor dimensão do vídeo.

Formato de erro

Todas as respostas de erro seguem este formato:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "additional context"
  }
}

Códigos de erro frequentes:

• MISSING_API_KEY
• INVALID_API_KEY
• INVALID_API_KEY_FORMAT
• API_KEY_INACTIVE
• USER_NOT_FOUND
• INVALID_REQUEST
• INVALID_CONFIG
• INSUFFICIENT_CREDITS
• NOT_FOUND
• ALREADY_RENDERING
• REMOTE_ERROR
• RENDER_TRIGGER_FAILED
• INTERNAL_ERROR