Documentação

Documentação

Referência de API

Referência REST API dos principais endpoints RenderingVideo v1

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:

Método Formato
Bearer Token Authorization: Bearer sk-xxx
Token Header Authorization: Token sk-xxx
X-API-Key X-API-Key: sk-xxx
Query Parameter ?api_key=sk-xxx

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

Método Endpoint Uso
POST /api/v1/video Criar uma tarefa permanente de vídeo
GET /api/v1/video Listar tarefas de vídeo
GET /api/v1/video/:taskId Ler detalhes de uma tarefa
DELETE /api/v1/video/:taskId Excluir uma tarefa de vídeo
POST /api/v1/video/:taskId/render Disparar renderização
POST /api/v1/upload Enviar assets
GET /api/v1/files Listar arquivos
DELETE /api/v1/files/:fileId Excluir um arquivo
GET /api/v1/credits Consultar saldo de créditos
POST /api/v1/preview Criar preview temporária
GET /api/v1/preview/:tempId Ler configuração da preview
DELETE /api/v1/preview/:tempId Excluir preview
POST /api/v1/preview/:tempId/convert Converter preview em tarefa permanente
POST /api/v1/preview/:tempId/render Converter preview e renderizar

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:

Campo Tipo Obrigatório Descrição
config object Sim Schema de vídeo conforme o JSON Schema
metadata object Não Metadados personalizados anexados à tarefa

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:

Parâmetro Tipo Padrão Descrição
page integer 1 Número da página
limit integer 20 Itens por página, máximo 100
status string - Filtra pelo status mais recente

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:

Status Significado
created Tarefa criada, render ainda não iniciado
rendering Renderização em andamento
completed Render concluído com sucesso
failed Falha no render

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:

Campo Tipo Obrigatório Padrão Descrição
webhook_url string Não - URL para notificação de conclusão
num_workers integer Não 5 Número de workers de renderizaçã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:

Campo Tipo Obrigatório Descrição
file File Não* Arquivo único
files File[] Não* Vários arquivos

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

Famílias MIME suportadas:

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

Limites de armazenamento por plano:

Plano Limite
Free 512 MB
Starter 10 GB
Standard 20 GB
Pro 50 GB

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:

Parâmetro Tipo Padrão Descrição
page integer 1 Número da página
limit integer 20 Itens por página
type string - image, video ou audio

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:

Campo Tipo Obrigatório Descrição
category string Não Categoria associada à nova tarefa

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:

Campo Tipo Obrigatório Padrão Descrição
category string Não api Categoria da nova tarefa
webhook_url string Não - Webhook para o resultado do render
num_workers integer Não 5 Número de workers de renderizaçã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
Qualidade Lado curto Multiplicador
720p <= 720px 1.0
1080p <= 1080px 1.5
2K <= 1440px 2.0

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