Creare video brevi con wan2.7-video/text-to-video@pro: flusso di lavoro API hiapi end-to-end

Il successo di un video breve dipende dalla velocità di iterazione: servono molti clip candidati, in formato verticale, con audio, e velocemente. Questa guida ruota proprio attorno a questo, usando wan2.7-video/text-to-video@pro su hiapi — il modello text-to-video Tongyi Wanxiang 2.7 di Alibaba, con output fino a 1080P, audio nativo e clip fino a 15 secondi. Ogni struttura di richiesta, limite di parametro e messaggio di errore riportato di seguito è stato verificato eseguendolo realmente contro l'API in produzione al momento della stesura, e i due clip dimostrativi incorporati sono stati generati esattamente dal codice mostrato.

Cosa offre il modello

wan2.7-video/text-to-video@pro è servito tramite l'endpoint unificato per attività asincrone di hiapi (/v1/tasks). Caratteristiche principali, verificate rispetto allo schema in produzione:

• Output: MP4 H.264, fino a 1080P, con traccia audio AAC nativa — il modello genera suoni ambientali ed effetti sonori in base al tuo prompt, senza bisogno di un passaggio audio separato.
• Durata: 2–15 secondi per clip (secondi interi).
• Proporzioni: 16:9, 9:16, 1:1, 4:3, 3:4 — vero verticale 9:16, adatto a formati tipo Shorts/Reels/TikTok, senza ritaglio.
• Fatturazione: in base ai secondi di video prodotto, a partire da $0.167/secondo al momento della stesura — una clip 1080P da 5 secondi costa circa $0.84. Prima di generare in batch, verifica sempre sulla pagina dei prezzi.

Il video non ha modalità sincrona: devi creare un'attività, eseguire polling finché non è completata, poi scaricare il risultato.

Esempio minimo funzionante (curl)

Crea l'attività:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video@pro",
    "input": {
      "prompt": "Macro da studio: una goccia di inchiostro blu zaffiro cade in acqua limpida, si apre al rallentatore, i filamenti d'inchiostro si espandono in forme di nuvola, sfondo bianco seamless luminoso, illuminazione high-key pulita, leggero ronzio ambientale",
      "ratio": "16:9",
      "resolution": "1080P",
      "duration": 4
    }
  }'

Risposta:

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

Polling del risultato:

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R" \
  -H "Authorization: Bearer sk-YOUR_KEY"

Durante il rendering, data.status è handling; al completamento diventa success e data.output[0].url contiene l'MP4. Questa richiesta ha generato esattamente questo clip:

⚠️ L'URL di output è un link temporaneo con timestamp expireAt. Dopo il successo dell'attività, scarica subito il file nel tuo storage — non fare hotlinking né salvarlo direttamente nel database.

Schema di input completo (verificato rispetto all'API in produzione)

L'API valida rigorosamente input e rifiuta campi sconosciuti; di seguito l'elenco completo dei campi accettati — ottenuto sondando direttamente l'endpoint, non copiato da nessuna parte:

Campo	Tipo	Vincoli	Obbligatorio
prompt	string	Descrizione della scena; guida anche l'audio generato	✅
ratio	string	Uno tra 16:9, 9:16, 1:1, 4:3, 3:4	Opzionale
resolution	string	720P o 1080P	Opzionale
duration	integer	2–15 (secondi)	Opzionale
negative_prompt	string	Contenuti da sopprimere (es. filigrane, sovrapposizioni di testo)	Opzionale
seed	integer	Riproducibile tra tentativi	Opzionale
watermark	boolean	Attiva/disattiva la filigrana del fornitore	Opzionale

Due insidie che ti aiutano a evitare un 400:

• Il nome del campo è ratio, non aspect_ratio — i modelli di immagini su hiapi usano aspect_ratio, questo modello video no. Inviare aspect_ratio restituisce additional properties 'aspect_ratio' not allowed.
• duration è validato lato server: duration: minimum: got 1, want 2 e maximum: got 999, want 15 sono gli errori esatti che ottieni quando superi l'intervallo 2–15.

Python end-to-end: input un prompt, output un MP4 pubblicabile

Questo è il flusso completo — creazione, polling, download — senza SDK, usando solo requests:

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def make_short(prompt: str, out_path: str, duration: int = 5,
               ratio: str = "9:16", seed: int | None = None) -> str:
    payload = {
        "model": "wan2.7-video/text-to-video@pro",
        "input": {
            "prompt": prompt,
            "ratio": ratio,               # 9:16 = video breve verticale
            "resolution": "1080P",
            "duration": duration,          # 2..15 secondi
            "negative_prompt": "sovrapposizioni di testo, filigrana, mani distorte",
        },
    }
    if seed is not None:
        payload["input"]["seed"] = seed

    task_id = requests.post(API, headers=HEADERS, json=payload).json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)

    video_url = task["output"][0]["url"]   # link temporaneo — scarica subito
    with open(out_path, "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    return out_path

make_short(
    "Inquadratura verticale a mano al mercato notturno durante l'ora d'oro: un venditore di cibo di strada "
    "salta noodles sfrigolanti in un wok con fiamme che si alzano, vapore e scintille arancioni "
    "si avvolgono verso la fotocamera, insegne al neon in un morbido rosa e ciano sullo sfondo sfocato, "
    "profondità di campo ridotta, sensazione documentaristica dinamica a mano, con suoni di sfrigolio e crepitio",
    "night-market.mp4",
    duration=5,
    seed=20260702,
)

Di seguito il clip effettivamente generato da questa chiamata — verticale 1080×1920, 5 secondi, con lo sfrigolio generato dal testo del prompt:

Nella mia esecuzione, un clip 16:9 da 4 secondi si è completato in circa 3 minuti, un clip 9:16 da 5 secondi un po' più a lungo — prevedi qualche minuto per clip, esegui il polling ogni 10 secondi circa e non martellare l'endpoint.

Consigli per i prompt dei video brevi: movimento e audio dipendono entrambi dal prompt

Lo schema non ha parametri per il controllo della camera o del movimento — tutto ciò che riguarda movimento, ritmo e suono viene guidato dal linguaggio del prompt. Cosa ha funzionato nei miei test:

• Nomina esplicitamente il comportamento della camera: come "handheld" (a mano), "slow push-in" (avvicinamento lento), "macro" (macro), "shallow depth of field" (profondità di campo ridotta). L'ondeggio documentaristico del clip del mercato notturno deriva interamente dalla parola "handheld".
• Descrivi l'audio che desideri: il modello genera il suono in base al prompt. "sizzling and crackling sounds" (suoni di sfrigolio e crepitio) e "gentle ambient hum" (leggero ronzio ambientale) sono entrambi comparsi nella traccia audio di output.
• Metti l'aggancio all'inizio: per i video brevi, il primo secondo decide tutto. Metti l'elemento più dinamico (fiamme nel wok, goccia d'inchiostro in acqua) all'inizio della descrizione del prompt.
• Usa negative_prompt in modo difensivo: "text overlay, watermark, distorted hands" (sovrapposizioni di testo, filigrana, mani distorte) ripulisce i difetti più comuni senza influenzare il prompt principale.
• Fissa seed durante l'iterazione: con un seed fisso, modifica una solo frase del prompt alla volta e osserva cosa fa effettivamente quella frase.

Serve il controllo del primo fotogramma? Usa la variante image-to-video

Se il tuo flusso inizia da un fotogramma chiave progettato — un'immagine prodotto, un primo fotogramma in stile brand — il text-to-video non accetta input immagine. Il modello complementare wan2.7-video/image-to-video@pro sì: accetta un array media di oggetti {"url": "...", "type": "image"}, con gli stessi campi prompt / resolution / duration, e anima il fotogramma che gli fornisci invece di generarne uno dal nulla. Stesso flusso basato su attività, stessa fatturazione al secondo. Una pipeline pratica: genera fotogrammi fissi con il modello di immagini, poi anima i fotogrammi approvati dopo la revisione — così paghi la generazione video solo per i fotogrammi già validati.

Errori comuni e cosa significano davvero

• invalid input: prompt: missing required field "prompt" — prompt è l'unico campo obbligatorio.
• invalid input: ratio: value must be one of '16:9', '9:16', '1:1', '4:3', '3:4' — hai passato una proporzione non supportata dal modello (o l'hai scritta male).
• invalid input: <root>: additional properties '...' not allowed — campo sconosciuto; lo schema è rigoroso, controlla la tabella sopra.
• status: "fail" con TASK_FAILED — l'attività è fallita dopo la creazione; creane una nuova (riutilizzando il tuo seed per mantenere la riproducibilità).
• Il file scaricato è piccolo o non riproducibile — probabilmente hai recuperato un URL di output scaduto. Ricontrolla expireAt e scarica subito dopo success.

In sintesi

Un POST, un ciclo di polling, un download — questa è tutta la distanza da un prompt testuale a un MP4 verticale con audio pubblicabile. Se stai costruendo una pipeline per video brevi, ottieni una API key dalla console, parti dalla funzione Python sopra e sfoglia il resto del catalogo dei modelli — lo stesso schema /v1/tasks (come mostrato nella nostra guida a seedance-2.0-fast) vale per tutti i modelli video della piattaforma, quindi cambiare modello in seguito richiede solo una riga.