Referência da API

Convenções

Todo endpoint /v1/* requer o cabeçalho Authorization: Bearer sk_.... Erros voltam como JSON com uma flag error e uma message:

{
  "error": true,
  "message": "length must be a positive multiple of 30 seconds, at most 360"
}

Endpoints de geração têm limite de 20 requisições por minuto. Todos os outros compartilham um limite de 200 por minuto.

Criar um explicativo

Inicia uma geração e retorna 202 Accepted com o registro na fila. Faça polling de obter um explicativo até estar ready.

{
  "input": "Explain how DNS resolves a domain name",
  "length": "0:30",
  "aspect": "16:9",
  "voice": "sketchie:sulafat",
  "language": "en"
}

Retorna o registro do explicativo: id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl (null até ficar pronto) e sceneGraph (null até ser gerado). Um 400 volta para um input vazio sem source, um length malformado, ou um aspect, preset, fillMode ou language inválido.

Obter um explicativo

Retorna o registro completo: status atual, a videoUrl quando ready, o sceneGraph editável, o histórico de versões (versions) e os chunks de cena da versão principal. Um id inexistente retorna 404.

Listar explicativos

Lista os explicativos da chave chamadora, do mais novo primeiro. Restrito ao dono da chave. limit é limitado de 1 a 100 (padrão 50). Retorna resumos leves (sem scene graph ou versões). Use obter um explicativo para o registro completo.

Editar um explicativo

A cunha da editabilidade. Transforme uma instrução em linguagem simples em um re-render direcionado. Só as cenas afetadas são renderizadas de novo, produzindo uma nova versão. Retorna 202 com a versão na fila. Faça polling de obter um explicativo até a versão principal ficar ready. Isto acrescenta ao vídeo existente, então não consome outra criação de vídeo grátis. O primeiro re-render de cada vídeo é grátis. Os seguintes usam minutos do plano pago, e contas grátis são convidadas a iniciar um plano. O explicativo já deve estar ready (senão 409).

{ "instruction": "Make the title scene shorter and warmer" }

Reverter para uma versão

Reaponta a versão principal para uma versão pronta anterior e espelha o grafo e o vídeo dela no registro. O alvo deve ser uma versão ready com vídeo (senão 409).

{ "versionId": "..." }

Stream de status ao vivo

Um stream de Server-Sent Events (text/event-stream). Abra uma conexão e cada transição de status de qualquer um dos seus explicativos chega como um frame event: status, então você pode atualizar um estado "vídeo pronto" no instante em que o worker termina em vez de fazer polling. O stream é restrito ao dono da sua chave.

Vozes

O catálogo de vozes de narração. O opcional ?language=<code> filtra por vozes nativas daquele idioma. Retorna voices (cada uma com um name amigável, o id para passar como voice, language, isDefault e um preview_url reproduzível) mais o default global. Veja Vozes.

Idiomas

Os idiomas de narração suportados, como { code, label, native }. Cada code é um language válido na criação. Veja Idiomas.

Estado da conta

Retorna videosGenerated (total), a image da conta e isAdmin. Requer autenticação.

Status de cobrança

Requer autenticação e retorna 200 tanto para contas grátis quanto pagas. Uma conta grátis retorna plan: "free" com videoAllowance, videosUsed e videosRemaining. Uma conta paga também retorna planLabel, billingInterval, trialStatus, quotaMinutes, minutesUsedThisPeriod, minutesRemaining e bonusMinutes.

Config de runtime e saúde

Público. Retorna { "authEnforced": true }. Um liveness check fica em GET /health.