Referência da API

Convenções

Cada endpoint /v1/* requer o cabeçalho Authorization: Bearer sk_.... Os 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"
}

Os endpoints de geração têm um limite de 20 pedidos por minuto. Todos os outros endpoints partilham um limite de 200 por minuto.

Criar um explicativo

Inicia uma geração e devolve 202 Accepted com o registo em 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"
}

Devolve o registo do explicativo: id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl (null até estar 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

Devolve o registo completo: status atual, o 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 em falta devolve 404.

Listar explicativos

Lista os explicativos da chave que chama, mais recentes primeiro. Restrito ao dono da chave. limit é limitado de 1 a 100 (predefinição 50). Devolve resumos leves (sem scene graph ou versões). Use obter um explicativo para o registo completo.

Editar um explicativo

A cunha da editabilidade. Transforme uma instrução em linguagem simples num re-render direcionado. Só as cenas afetadas são renderizadas de novo, produzindo uma nova versão. Devolve 202 com a versão em fila. Faça polling de obter um explicativo até a versão principal estar ready. Isto acrescenta ao vídeo existente, portanto não consome outra criação de vídeo gratuito. O primeiro re-render de cada vídeo é gratuito. Os seguintes usam minutos do plano pago, e às contas gratuitas é pedido que iniciem 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 cabeça para uma versão pronta anterior e espelha o seu grafo e vídeo no registo. O alvo deve ser uma versão ready com um vídeo (senão 409).

{ "versionId": "..." }

Stream de estado ao vivo

Um stream de Server-Sent Events (text/event-stream). Abra uma ligação e cada transição de estado em qualquer um dos seus explicativos chega como um frame event: status, para poder 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 desse idioma. Devolve voices (cada uma com um name amigável, o id a passar como voice, language, isDefault e um preview_url reproduzível) mais o default global. Consulte Vozes.

Idiomas

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

Estado da conta

Devolve videosGenerated (vitalício), a image da conta e isAdmin. Requer autenticação.

Estado de faturação

Requer autenticação e devolve 200 tanto para contas gratuitas como pagas. Uma conta gratuita devolve plan: "free" com videoAllowance, videosUsed e videosRemaining. Uma conta paga também devolve planLabel, billingInterval, trialStatus, quotaMinutes, minutesUsedThisPeriod, minutesRemaining e bonusMinutes.

Configuração de runtime e saúde

Público. Devolve { "authEnforced": true }. Uma verificação de vivacidade fica em GET /health.