Riferimento API

Convenzioni

Ogni endpoint /v1/* richiede l’header Authorization: Bearer sk_.... Gli errori tornano come JSON con un flag error e un message:

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

Gli endpoint di generazione hanno un limite di 20 richieste al minuto. Tutti gli altri condividono un limite di 200 al minuto.

Creare un esplicativo

Avvia una generazione e restituisce 202 Accepted con il record in coda. Interroga ottenere un esplicativo finché è ready.

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

Restituisce il record dell’esplicativo: id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl (null finché non è pronto) e sceneGraph (null finché non è generato). Un 400 torna per un input vuoto senza source, una length malformata, o un aspect, preset, fillMode o language non valido.

Ottenere un esplicativo

Restituisce il record completo: status corrente, la videoUrl una volta ready, lo sceneGraph modificabile, la cronologia versioni (versions) e i chunks di scena della versione principale. Un id mancante restituisce 404.

Elencare esplicativi

Elenca gli esplicativi della chiave chiamante, dal più recente. Limitato al proprietario della chiave. limit viene limitato da 1 a 100 (predefinito 50). Restituisce riassunti leggeri (senza scene graph né versioni). Usa ottenere un esplicativo per il record completo.

Modificare un esplicativo

Il cuneo della modificabilità. Trasforma un’istruzione in linguaggio naturale in un re-render mirato. Solo le scene interessate vengono ri-renderizzate, producendo una nuova versione. Restituisce 202 con la versione in coda. Interroga ottenere un esplicativo finché la versione principale è ready. Questo si aggiunge al video esistente, quindi non consuma un altro slot di creazione video gratis. Il primo re-render di ogni video è gratis. I successivi usano i minuti del piano a pagamento, e agli account gratuiti viene chiesto di avviare un piano. L’esplicativo deve essere già ready (altrimenti 409).

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

Ripristinare una versione

Ripunta la versione principale a una versione pronta precedente e ne rispecchia grafo e video sul record. Il target deve essere una versione ready con un video (altrimenti 409).

{ "versionId": "..." }

Stream di stato dal vivo

Uno stream di Server-Sent Events (text/event-stream). Apri una connessione e ogni transizione di stato su uno qualsiasi dei tuoi esplicativi arriva come frame event: status, così puoi aggiornare uno stato "video pronto" nel momento in cui il worker finisce invece di interrogare. Lo stream è limitato al proprietario della tua chiave.

Voci

Il catalogo delle voci di narrazione. L’opzionale ?language=<code> filtra per voci native di quella lingua. Restituisce voices (ciascuna con un name comodo, l’id da passare come voice, language, isDefault e un preview_url riproducibile) più il default globale. Vedi Voci.

Lingue

Le lingue di narrazione supportate, come { code, label, native }. Ogni code è un language valido alla creazione. Vedi Lingue.

Stato dell’account

Restituisce videosGenerated (a vita), l’image dell’account e isAdmin. Richiede autenticazione.

Stato della fatturazione

Richiede autenticazione e restituisce 200 sia per account gratuiti sia a pagamento. Un account gratuito restituisce plan: "free" con videoAllowance, videosUsed e videosRemaining. Un account a pagamento restituisce anche planLabel, billingInterval, trialStatus, quotaMinutes, minutesUsedThisPeriod, minutesRemaining e bonusMinutes.

Config di runtime e salute

Pubblico. Restituisce { "authEnforced": true }. Un liveness check si trova a GET /health.