Tutorial di integrazione API Wan 3.0: curl, Python e tutti i parametri

Wan 3.0 Standard (wan3.0-video) su HiAPI usa l'interfaccia asincrona unificata: invio con POST /v1/tasks, ottieni il taskId, poi recuperi il risultato con GET /v1/tasks/{taskId}. Basta scrivere un solo prompt per ottenere un video con audio; puoi anche aggiungere primo frame, ultimo frame, oppure fino a 10 immagini di riferimento, 5 video di riferimento e 5 audio di riferimento per controllare insieme la generazione. Questo articolo fornisce esempi curl e Python pronti all'uso, tutti i parametri attuali e alcune cose da sapere prima della messa in produzione.

Prima i prezzi

Risoluzione	Al secondo	5 secondi
480P	$0.04	$0.20
720P	$0.08	$0.40
1080P (predefinito)	$0.16	$0.80

Prezzo attuale HiAPI, verificato il 18 ottobre 2026. L'audio è attivo per impostazione predefinita e non ha costi aggiuntivi.

Attenzione ai valori predefiniti: se non specifichi resolution ottieni 1080P, se non specifichi duration ottieni 5 secondi, quindi $0.80 per video. Quando provi i prompt ricordati di scrivere esplicitamente "resolution": "480P".

Per ottenere risultati più veloci puoi usare la versione accelerata wan3.0-video-prime, con un prezzo più che doppio rispetto alla standard (480P $0.0875 al secondo).

Un video reale

480P, 16:9, 5 secondi, con audio:

A steaming noodle stall at a night market, close on the cook's hands as she lifts a tangle of noodles from a boiling pot and swirls them into a blue-rimmed bowl; slow push-in, warm tungsten light against cool blue street glow, steam drifting through the frame. Sound: rolling boil, the clink of a ladle, crowd murmur and a scooter passing in the distance.

Genera con questo prompt →

wan3.0-video, 480P, 5 secondi, $0.20.

Esegui il primo test

Preparazione: crea una API Key nella console. I nuovi utenti ricevono 200 crediti alla registrazione.

curl: invio del task

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "A steaming cup of coffee on a wooden table, soft morning light, gentle steam rising. Sound: a quiet cafe.",
      "resolution": "480P",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

Restituisce subito il taskId, la generazione avviene in background:

{"code": 200, "message": "success", "data": {"taskId": "tk-hiapi-..."}}

curl: recupero del risultato

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Quando data.status diventa success, data.output[0].url è l'indirizzo del video. L'indirizzo temporaneo scade dopo circa 7 giorni, quindi scaricalo e salvalo al più presto. fail indica un fallimento, senza addebito.

Python

import os, time, requests

KEY = os.environ["HIAPI_KEY"]
BASE = "https://api.hiapi.ai/v1"
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

r = requests.post(f"{BASE}/tasks", headers=H, json={
    "model": "wan3.0-video",
    "input": {
        "prompt": "A steaming cup of coffee on a wooden table, soft morning light, gentle steam rising. Sound: a quiet cafe.",
        "resolution": "480P",
        "duration": 5,
    },
})
task_id = r.json()["data"]["taskId"]

while True:
    d = requests.get(f"{BASE}/tasks/{task_id}", headers=H).json()["data"]
    if d["status"] in ("success", "fail"):
        break
    time.sleep(10)

print(d["output"][0]["url"] if d["status"] == "success" else d)

I video brevi richiedono di solito qualche minuto; un intervallo di polling di 10 secondi è sufficiente.

Tutti i parametri

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	Testo	Scena, azioni, inquadratura, luce e audio si scrivono qui; in modalità reference usa Image1, Video1, Audio1 per riferirti ai materiali
resolution	No	480P / 720P / 1080P (predefinito)	Determina il prezzo al secondo
duration	No	Intero 2–30, predefinito 5	La durata totale dei video di riferimento più la durata di output non può superare 30 secondi
aspect_ratio	No	adaptive (predefinito) / 16:9 / 4:3 / 1:1 / 3:4 / 9:16	adaptive sceglie automaticamente in base ai materiali e al prompt
audio	No	Booleano, predefinito true	Se includere una traccia audio sincronizzata
seed	No	0–2147483647	Fissarlo facilita la riproducibilità
first_frame_url	No	1 URL immagine	Modalità primo frame
last_frame_url	No	1 URL immagine	Da usare con il primo frame per specificare l'ultimo frame
reference_image_urls	No	Massimo 10	Immagini di riferimento
reference_video_urls	No	Massimo 5, singolo segmento 1–15 secondi, totale ≤15 secondi	Video di riferimento
reference_audio_urls	No	Massimo 5 WAV/MP3	Da usare insieme a immagini o video
reference_file_urls	No	Massimo 1	Documento o presentazione
reference_link_urls	No	Massimo 1	Pagina web senza login

Le due modalità non sono combinabili: modalità primo/ultimo frame e modalità reference reference_* sono mutuamente esclusive, una richiesta può usarne solo una.

Esempio di scrittura in modalità reference:

{
  "model": "wan3.0-video",
  "input": {
    "prompt": "Use Image1 as the product: slow quarter orbit around it on a wooden counter, soft morning window light. Sound: gentle pouring water.",
    "reference_image_urls": ["https://example.com/product.jpg"],
    "resolution": "480P",
    "duration": 5
  }
}

Errori comuni

Sono tutti restituiti in modo sincrono all'invio con HTTP 400, senza creare il task e senza addebito:

• duration: maximum: got 99, want 30: la durata supera i 30 secondi.
• resolution: value must be one of '480P', '720P', '1080P': la P della risoluzione deve essere maiuscola.
• additional properties 'negative_prompt', 'image_urls' not allowed: questo modello non ha il prompt negativo; il campo per le immagini di riferimento si chiama reference_image_urls, non image_urls.
• API Key errata restituisce HTTP 401, saldo insufficiente restituisce 402.

Se il task fallisce dopo essere stato creato, nel risultato della query compare status: "fail", ma il codice di stato HTTP resta 200, quindi controlla data.status.

Da sapere prima della messa in produzione

• Usa il callback al posto del polling: aggiungi al livello superiore del body della richiesta "callback": {"url": "https://tuo-dominio/hiapi/callback", "when": "final"}, e HiAPI ti notificherà al termine del task. callback va al livello superiore, non dentro input.
• Evita addebiti duplicati: includi l'header Idempotency-Key all'invio. In caso di retry per timeout di rete, usando la stessa key viene restituito il taskId originale, senza creare un task aggiuntivo.
• Salva subito i file: gli indirizzi temporanei scadono dopo circa 7 giorni. Se devi conservarli a lungo, passa "storage": "persistent" alla creazione, oppure convertili successivamente in archiviazione persistente; vedi la documentazione per la creazione dei task.

Domande frequenti

Si può usare senza immagini di riferimento?

Sì. Basta scrivere prompt per generare un video; i materiali di riferimento sono opzionali.

L'audio ha un costo aggiuntivo?

No. audio è attivo per impostazione predefinita; il prezzo dipende solo da risoluzione e secondi. Se non vuoi l'audio, passa false.

Vuoi un formato verticale?

Passa 9:16 come aspect_ratio.

Si possono usare insieme primo frame e immagini di riferimento?

No, bisogna scegliere uno dei due.

Per altri esempi di prompt vedi la raccolta completa di prompt per Wan 3.0, con video reali per tutti e 4 gli scenari. Puoi anche copiare direttamente il prompt del banco di noodles qui sopra e generarne uno con $0.20.