ShengshuGuida

Come usare l’API di Vidu Q4

Una guida passo passo all’API di Vidu Q4 con Node.js, Python e cURL: invia un job da immagine a video, controllane lo stato o ricevi un webhook e scarica il video. L’esempio qui sotto costa $0,35.

Endpoint: 2; Da immagine a video · Da riferimento a video
Richiesta di esempio: $0,35; Da immagine a video
Linguaggi: 3; Node.js · Python · cURL
Generazioni non riuscite: $0; rimborsate automaticamente

Ottieni una chiave API Crea con Vidu Q4 Documentazione API

Ottieni una chiave API

Crea un account, aggiungi crediti e crea una chiave nella Dashboard → Chiavi API. Salvala come CHEAPERGEN_API_KEY sul tuo server. Ogni richiesta la invia come token Bearer.

Come ottenere una chiave API Vidu Q4

Scegli un endpoint Vidu Q4

Ogni attività ha il proprio endpoint. Tutti accettano un corpo JSON e restituiscono una generazione di cui puoi controllare lo stato.

Endpoint API di Vidu Q4, input obbligatori e prezzi
Attività	Endpoint	Obbligatorio	Da
Da immagine a video	shengshu/vidu-q4/image-to-video	prompt, image_url	$0,0331 al secondo
Da riferimento a video	shengshu/vidu-q4/reference-to-video	prompt, reference_image_urls	$0,0331 al secondo

Invia un job da immagine a video

Questo programma invia il job, controlla ogni 3 secondi finché non termina e stampa l’URL video. Sostituisci il prompt e le impostazioni con i tuoi.

const API = "https://cheapergen.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Submit the job
let job = await fetch(`${API}/run/shengshu/vidu-q4/image-to-video`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": "Lei alza lo sguardo dal libro e sorride mentre fuori dalla finestra inizia a nevicare",
    "image_url": "https://cdn.cheapergen.com/samples/portrait.jpg",
    "resolution": "720p",
    "duration": 5
  }),
}).then((r) => r.json());

// 2. Poll until it finishes (or pass webhook_url and skip polling)
while (job.status === "queued" || job.status === "running") {
  await new Promise((r) => setTimeout(r, 3000));
  job = await fetch(`${API}/generations/${job.id}`, { headers }).then((r) => r.json());
}

console.log(job.status === "succeeded" ? job.output.video.url : job.error);

import os, time, requests

API = "https://cheapergen.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"}

# 1. Submit the job
job = requests.post(f"{API}/run/shengshu/vidu-q4/image-to-video", headers=headers, json={
    "prompt": "Lei alza lo sguardo dal libro e sorride mentre fuori dalla finestra inizia a nevicare",
    "image_url": "https://cdn.cheapergen.com/samples/portrait.jpg",
    "resolution": "720p",
    "duration": 5
}).json()

# 2. Poll until it finishes (or pass "webhook_url" and skip polling)
while job["status"] in ("queued", "running"):
    time.sleep(3)
    job = requests.get(f"{API}/generations/{job['id']}", headers=headers).json()

print(job["status"], job["output"]["video"]["url"] if job["status"] == "succeeded" else job["error"])

curl -X POST https://cheapergen.com/api/v1/run/shengshu/vidu-q4/image-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Lei alza lo sguardo dal libro e sorride mentre fuori dalla finestra inizia a nevicare",
  "image_url": "https://cdn.cheapergen.com/samples/portrait.jpg",
  "resolution": "720p",
  "duration": 5
}'

Imposta i parametri rilevanti

Le impostazioni di shengshu/vidu-q4/image-to-video e il loro effetto sul prezzo.

Parametri Vidu Q4 Da immagine a video e relativo effetto sul prezzo
Parametro	Tipo · predefinito	Descrizione	Effetto sul prezzo
resolution	string (enum) · 720p	Risoluzione dell’output. Le risoluzioni più alte costano di più al secondo. 540p · 720p · 1080p · 2K · 4k	540p: $0,0331 al secondo 720p: $0,0699 al secondo 1080p: $0,0882 al secondo 2K: $0,1397 al secondo 4K: $0,2867 al secondo
duration	integer · 5	Durata della clip generata in secondi (3–16 s). Paghi al secondo.	Fatturato al secondo
generate_audio	boolean · true	Genera dialoghi ed effetti sonori sincronizzati. Inclusi nel prezzo.	Nessuno
seed	integer	Usa lo stesso seed e le stesse impostazioni per riprodurre un risultato. Lascia vuoto per un valore casuale.	Nessuno

Gli altri endpoint Vidu Q4 hanno la stessa struttura, ma input diversi:

POST /api/v1/run/shengshu/vidu-q4/reference-to-video

{
  "prompt": "@Image1 saluta @Image2 nel caffè di @Image3 e pronuncia la battuta di @Audio1",
  "reference_image_urls": [
    "https://cdn.cheapergen.com/samples/reference-1.jpg",
    "https://cdn.cheapergen.com/samples/reference-2.jpg",
    "https://cdn.cheapergen.com/samples/reference-3.jpg"
  ],
  "reference_audio_urls": [
    "https://cdn.cheapergen.com/samples/reference-1.mp3"
  ],
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}

Ottieni il risultato

Un job passa da queued a running, poi a succeeded, failed o canceled. Interroga GET /api/v1/generations/{id} oppure imposta webhook_url: invieremo il risultato con POST. Scarica l’output e conservalo tu.

200 — completata

{
  "id": "gen_8c2QmX1nq0k4",
  "object": "generation",
  "model": "shengshu/vidu-q4",
  "endpoint": "shengshu/vidu-q4/image-to-video",
  "mode": "image-to-video",
  "status": "succeeded",
  "input": {
    "prompt": "Lei alza lo sguardo dal libro e sorride mentre fuori dalla finestra inizia a nevicare",
    "image_url": "https://cdn.cheapergen.com/samples/portrait.jpg",
    "resolution": "720p",
    "duration": 5
  },
  "output": {
    "video": {
      "url": "https://cdn.cheapergen.com/outputs/gen_8c2Q.mp4",
      "content_type": "video/mp4",
      "duration": 5,
      "width": 1280,
      "height": 720
    }
  },
  "error": null,
  "cost": {
    "amount_usd": 0.2255,
    "currency": "usd",
    "estimated": false,
    "official_usd": 0.264,
    "list_price_source": "official",
    "list_price_label": "Official",
    "saved_usd": 0.0385
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04Z",
  "started_at": "2026-10-15T09:21:06Z",
  "completed_at": "2026-10-15T09:22:31Z"
}

Verifica le firme dei webhook

Calcola il prezzo prima dell'avvio

L'endpoint dei preventivi è gratuito e non richiede una chiave. Restituisce il prezzo, il prezzo ufficiale e lo sconto applicato per l'input esatto che invii.

curl -X POST https://cheapergen.com/api/v1/quote/shengshu/vidu-q4/image-to-video \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Lei alza lo sguardo dal libro e sorride mentre fuori dalla finestra inizia a nevicare","image_url":"https://cdn.cheapergen.com/samples/portrait.jpg","resolution":"720p","duration":5}'

Errori API e come risolverli
Stato	Codice	Descrizione
400	invalid_request	Manca un parametro o il suo valore è fuori intervallo: il messaggio indica quale.
401	unauthorized	Chiave API mancante, non valida o revocata.
402	insufficient_balance	Crediti insufficienti per il prezzo indicato; aggiungine altri o attiva la ricarica automatica.
429	rate_limited	Troppe richieste o generazioni in corso: attendi e riprova con backoff.
502	upstream_error	Il fornitore del modello ha avuto un errore; l'importo bloccato viene rimborsato e puoi riprovare.
503	model_unavailable	Al momento non ci sono percorsi di elaborazione disponibili: riprova più tardi o scegli un altro modello.

Documentazione API completa di Vidu Q4

FAQ

Domande sull’API di Vidu Q4

No. L'API usa HTTPS semplice e JSON, quindi gli esempi con Node.js (fetch) e Python (requests) in questa pagina sono programmi completi. Funziona qualsiasi linguaggio in grado di inviare una richiesta HTTP.

Sì. Aggiungi "webhook_url" al corpo della richiesta e invieremo la generazione completata con una richiesta POST, firmata nell'intestazione CheaperGen-Signature (HMAC-SHA256 del timestamp e del corpo grezzo). Puoi anche eseguire il polling con GET /api/v1/generations/{id}.

Passa URL pubblici in "image_url", "reference_image_urls", "reference_audio_urls". Se i file non hanno un URL pubblico, caricali prima con POST /api/v1/uploads: la risposta contiene un URL da usare nella richiesta.

Da immagine a video parte da $0,0331 al secondo; l'esempio di richiesta in questa pagina costa $0,35, 26% in meno rispetto a il prezzo ufficiale. Le generazioni non riuscite vengono rimborsate automaticamente.

Come usare l’API di Vidu Q4

Ottieni una chiave API

Scegli un endpoint Vidu Q4

Invia un job da immagine a video

Imposta i parametri rilevanti

Ottieni il risultato

Calcola il prezzo prima dell'avvio

Domande sull’API di Vidu Q4

Mi serve un SDK per usare l'API Vidu Q4?

Posso usare un webhook invece del polling?

Come invio immagini all'API Vidu Q4?

Quanto costa una chiamata API Vidu Q4?