Endpoint

Video (job asincroni)

Genera video con Veo 3.1, Sora 2 Pro e altri modelli: crea un job con POST /videos, controlla lo stato con GET /videos/{id} e scarica il risultato.

Provalo nel playground

Genera video con Veo 3.1, Sora 2 Pro, Kling, Seedance, Runway, Wan, Hailuo e altri. La generazione video richiede da decine di secondi a diversi minuti, quindi funziona come un job asincrono: crei un job, ne controlli lo stato a intervalli, poi scarichi il risultato.

Passo	Richiesta
1. Creazione	`POST /api/v1/videos`
2. Polling	`GET /api/v1/videos/{id}`
3. Download	`GET /api/v1/videos/{id}/content?index=0`

Creare un job

POST https://api14.com/api/v1/videos

Parametro	Tipo	Obbligatorio	Descrizione
`model`	string	sì	L'id di un modello video, ad es. `google/veo-3.1-fast`.
`prompt`	string	sì	Cosa succede nel video.
`duration`	number	no	Durata in secondi. Per impostazione predefinita è la prima durata supportata dal modello.
`resolution`	string	no	Ad es. `720p`, `1080p`. Deve essere supportata dal modello.
`aspect_ratio`	string	no	Ad es. `16:9`, `9:16`.
`generate_audio`	boolean	no	Genera una colonna sonora dove supportato (predefinito `true`).
`image`	string	no	Primo fotogramma come URL o URI `data:` (image-to-video).

Durate, risoluzioni e proporzioni supportate per ogni modello: GET /videos/models (pubblico) o la pagina del modello.

Controllo del saldo

Prima dell'invio del job, il gateway stima il suo prezzo come durata × prezzo al secondo per la risoluzione richiesta (e l'opzione audio). Se il tuo saldo è inferiore alla stima, la richiesta fallisce con 402 insufficient_balance e non viene avviato nulla.

Risposta

{
  "id": "vid_01JABCDEF",
  "status": "queued",
  "polling_url": "/api/v1/videos/vid_01JABCDEF"
}

Controllare il job

GET https://api14.com/api/v1/videos/{id}

{
  "id": "vid_01JABCDEF",
  "status": "completed",
  "generation_id": "gen-1791100000-abc",
  "unsigned_urls": ["/api/v1/videos/vid_01JABCDEF/content?index=0"],
  "usage": { "cost": 1.2 }
}

`status`	Significato
`queued`	In attesa del provider.
`in_progress`	Rendering in corso.
`completed`	Terminato; `unsigned_urls` elenca gli output.
`failed`, `cancelled`, `expired`	Terminato senza output; vedi `error`. Non ti viene addebitato nulla.

Controlla ogni 5-10 secondi. Solo l'account che ha creato il job può leggerlo; gli altri id restituiscono 404 not_found.

Scaricare il risultato

GET https://api14.com/api/v1/videos/{id}/content?index=0

Restituisce i byte del video (di solito video/mp4) con la tua chiave API. Gli URL di output puntano sempre al gateway, mai al provider upstream. Se il file non è pronto o è scaduto ottieni content_unavailable.

Esempio

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api14.com/api/v1",
  apiKey: process.env.API14_API_KEY,
});

// Video generation is asynchronous: submit, then poll until completed.
let job = await client.post("/videos", { body: {
  "model": "google/veo-3.1-fast",
  "prompt": "A drone shot over turquoise ocean waves at sunrise",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9"
} });
while (!["completed", "failed"].includes(job.status)) {
  await new Promise((r) => setTimeout(r, 5000));
  job = await client.get(`/videos/${job.id}`);
}
console.log(job.status, job.unsigned_urls);

Fatturazione

L'addebito avviene una sola volta, quando il job raggiunge completed, usando il costo effettivo del provider. I job falliti, annullati e scaduti sono gratuiti. I job si completano anche in background, quindi un job di cui non fai mai il polling viene comunque saldato e compare in Utilizzo.

Errori

Stato	Codice	Quando
402	`insufficient_balance`	Il saldo è inferiore al prezzo stimato del job.
403	`plan_required`	Il tuo piano non include i modelli video.
404	`model_not_found` / `not_found`	Modello sconosciuto, oppure id del job non tuo.
502	`upstream_unavailable`	Non è stato possibile leggere lo stato; riprova.

Vedi Errori.