Blog

Tutoriale

Come usare pixverse-v6-max/text-to-video tramite l'API HiAPI: curl, Python ed esempi di richiesta eseguibili

Nov 13, 2026
Copertina piatta con un motivo a intreccio di espresso corposo, avena e ottone che forma una griglia simile a un telaio.
In questa pagina

Cosa fa questo endpoint e quando usarlo

pixverse-v6-max/text-to-video è l'endpoint di text-to-video su HiAPI. Invii un prompt testuale che descrive la scena desiderata e l'endpoint restituisce un video renderizzato. Poiché la generazione video richiede tempo, l'endpoint è asincrono: la prima richiesta non restituisce direttamente il video, ma un identificatore di attività che usi per interrogare l'avanzamento e ottenere il risultato finale.

Questa forma "richiesta—conferma—polling" è il modello mentale centrale di tutto il tutorial. Il flusso interno è sempre coerente:

  1. Invia un'attività di generazione con prompt e parametri.
  2. Ricevi immediatamente un identificatore di attività.
  3. Esegui il polling dell'attività finché non segnala il completamento (o il fallimento).
  4. Scarica o incorpora l'URL del video risultante.

Quando è adatto usare questo endpoint

Scegli pixverse-v6-max/text-to-video quando hai solo una descrizione e nessun materiale di origine — ad esempio per creare un trailer di prodotto da un brief testuale, generare clip di sfondo per un'app o realizzare anteprime di storyboard. Se hai già un'immagine e vuoi animarla, rientra nel flusso image-to-video, non in questo endpoint. Se desideri che il modello iteri ripetutamente il prompt in modo conversazionale, si tratta di un'altra modalità di interazione. Questo endpoint è il percorso diretto e a singola generazione dal testo al video.

Poiché la generazione è asincrona, è adatto anche ad architetture basate su coda: un backend Web riceve la richiesta dell'utente, invia l'attività, poi un processo worker esegue il polling e consegna il risultato in un secondo momento. Nessun passaggio dell'intera chiamata si blocca fino al termine del rendering completo.

Prima di iniziare: autenticazione e basi della richiesta

Prima di scrivere qualsiasi codice, verifica tre cose.

1. Una chiave API

Ogni richiesta HiAPI deve essere autenticata con una chiave API. Trattala come una password: non inserirla nel repository del codice sorgente, caricala da una variabile d'ambiente e ruotala immediatamente in caso di fuga. Gli esempi seguenti la leggono da HIAPI_API_KEY, quindi esportala prima nella shell:

export HIAPI_API_KEY="your_key_here"

2. L'URL di base corretto

Tutte le richieste vanno inviate all'URL di base dell'API HiAPI, aggiungendo il percorso dell'endpoint. Usa l'URL di base indicato nel tuo account HiAPI, non un hostname codificato in un articolo di blog — se hai dubbi, consulta la documentazione di riferimento API nella dashboard. Gli esempi seguenti usano $HIAPI_BASE_URL come segnaposto per quel valore.

3. Convenzioni JSON

Invio e interrogazione dello stato sono JSON su HTTPS:

  • Invia Content-Type: application/json per ogni richiesta con corpo.
  • Invia Authorization: Bearer $HIAPI_API_KEY per ogni richiesta (incluse le interrogazioni di stato).
  • Aspettati JSON in risposta, anche in caso di errore — leggi il corpo della risposta di errore, non solo il codice di stato HTTP.

Verifica rapida di integrità

Se hai a disposizione un endpoint leggero (ad esempio una route models o account), chiamalo una volta prima di toccare l'endpoint video. Un 200 restituito lì dimostra che chiave, URL di base e formato delle intestazioni sono corretti, eliminando tre variabili dal debug successivo.

Una richiesta curl eseguibile

Di seguito la chiamata di invio completa. Il percorso dell'endpoint è pixverse-v6-max/text-to-video; il corpo della richiesta trasporta il prompt e i parametri di generazione.

curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Notte, un vicolo al neon bagnato dalla pioggia, lento movimento di carrello in avanti, atmosfera cinematografica",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Descrizione campo per campo

  • prompt — la descrizione testuale. Specifica soggetto, movimento, movimento di camera e atmosfera. È la leva più importante per la qualità dell'output.
  • duration — la durata richiesta della clip. Vedi la sezione su durata e proporzioni più avanti.
  • aspect_ratio — le proporzioni dell'output, ad esempio 16:9, 9:16, 1:1.

Cosa viene restituito

Un invio riuscito restituisce un oggetto JSON contenente l'identificatore di attività — cioè l'handle per il polling. Per i nomi esatti dei campi fai riferimento alla documentazione di riferimento API; in questo tutorial lo chiamiamo task_id. Salvalo:

TASK_ID=$(curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Notte, un vicolo al neon bagnato dalla pioggia, lento movimento di carrello in avanti, atmosfera cinematografica","duration":5,"aspect_ratio":"16:9"}' \
  | python -c 'import sys,json; print(json.load(sys.stdin)["task_id"])')
echo "$TASK_ID"

Nota cosa non contiene la risposta: il video. La generazione avviene in background. Considera la risposta di invio come una ricevuta, non come un risultato.

La versione Python della stessa richiesta

La versione Python corrisponde esattamente alla chiamata curl. Per brevità usiamo requests, ma vanno bene anche httpx o urllib — l'unico requisito sono le stesse intestazioni e lo stesso corpo JSON.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "prompt": "Notte, un vicolo al neon bagnato dalla pioggia, lento movimento di carrello in avanti, atmosfera cinematografica",
    "duration": 5,
    "aspect_ratio": "16:9",
}

resp = requests.post(
    f"{BASE_URL}/pixverse-v6-max/text-to-video",
    headers=headers,
    json=payload,
    timeout=30,
)

if resp.status_code >= 400:
    # Stampa il corpo della risposta di errore del server — di solito indica il campo problematico
    raise RuntimeError(f"submit failed {resp.status_code}: {resp.text}")

data = resp.json()
task_id = data["task_id"]
print("submitted:", task_id)

Punti da copiare

  • json=payload serializza automaticamente il corpo della richiesta e imposta il content type. Se usi invece data=json.dumps(payload), devi mantenere l'intestazione esplicita Content-Type.
  • Impostare un timeout client all'invio evita connessioni appese. Non limita il tempo di generazione — la generazione avviene lato server, ed è proprio per questo che serve il polling.
  • Controlla il codice di stato prima di fare il parsing. I corpi delle risposte 4xx di solito forniscono più informazioni del codice di stato stesso; stampali.
  • Non registrare mai la chiave API. Registra invece task_id — può essere memorizzato in sicurezza ed è il tuo handle di debug.

Parametri durata e proporzioni

Questi due campi sono la fonte più comune di richieste rifiutate, quindi meritano attenzione.

duration

duration imposta la lunghezza richiesta della clip, in secondi. I valori richiedibili sono limitati dall'intervallo supportato dall'endpoint; inviare un valore fuori da tale intervallo di solito produce un errore di validazione dei parametri, non un troncamento silenzioso della clip. Scegli tra i valori supportati documentati nel riferimento API e mantienilo come numero intero. Clip più lunghe richiedono più tempo di rendering, quindi in fase di sviluppo privilegia la durata minima supportata — stai verificando la pipeline, non la fotografia.

aspect_ratio

aspect_ratio è una stringa nella forma L:A. Fallo corrispondere al luogo in cui il video sarà infine mostrato:

  • 16:9 — orizzontale: hero section di siti Web, player in stile YouTube, sfondi desktop.
  • 9:16 — verticale: feed di video brevi e storie su mobile.
  • 1:1 — quadrato: layout a griglia e miniature.

Scegliere qui la forma sbagliata è economico da correggere ma costoso se scoperto tardi: un nuovo rendering consuma un altro ciclo completo di generazione, quindi determina lo scenario di visualizzazione target prima di inviare.

Cosa controllare quando la richiesta viene rifiutata

  • Mancata corrispondenza di tipo — duration scritta come stringa ("5") invece che come numero, o aspect_ratio scritta come due numeri. Mantieni duration numerica e aspect ratio come stringa.
  • Valori non supportati — durata o proporzioni fuori dall'intervallo documentato. Confronta ciascun valore con l'elenco di riferimento.
  • Nomi dei campi — errori di battitura come aspectRatio o durationSeconds, nella migliore delle ipotesi vengono gestiti silenziosamente come campi sconosciuti. Copia i nomi dei campi dalla documentazione di riferimento.

Metodo rapido per individuare il campo problematico: invia di nuovo solo con prompt, poi aggiungi un parametro alla volta. Il primo rifiuto indica il campo problematico.

Eseguire il polling dell'attività asincrona finché il video non è pronto

Il polling è un ciclo che segue tre regole: controlla lo stato, attendi, fermati allo stato terminale. Aggiungi un limite massimo per evitare che un'attività bloccata giri a vuoto all'infinito.

import time
import requests

def wait_for_video(task_id, base_url, api_key, timeout=600):
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"{base_url}/tasks/{task_id}"   # la route di stato è nel riferimento API
    deadline = time.time() + timeout
    delay = 2

    while time.time() < deadline:
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        task = r.json()
        status = task["status"]

        if status == "succeeded":
            return task["result"]["video_url"]
        if status == "failed":
            raise RuntimeError(f"generation failed: {task.get('error')}")

        time.sleep(delay)
        delay = min(delay * 1.5, 15)   # backoff graduale con limite massimo

    raise TimeoutError(f"task {task_id} not finished in {timeout}s")

Perché il backoff è importante

Eseguire il polling a intervalli fissi ogni secondo per un'attività di generazione che richiede un minuto spreca decine di richieste. Inizia con un intervallo piccolo e aumentalo gradualmente — il moltiplicatore con limite massimo mostrato sopra si stabilizza su un intervallo comodo senza martellare l'API. Se esegui molte attività, una coda con un singolo processo worker di polling è più rispettosa che un ciclo per ogni richiesta.

Gestire il risultato

Dopo il successo dell'attività, la risposta contiene l'URL del video. Recuperalo prontamente e, se il risultato deve essere conservato, copialo nel tuo storage — gli URL firmati non sono permanenti. Prima di consegnare il file all'utente, controlla il content type e la dimensione al download, e registra task_id insieme all'asset memorizzato, così qualsiasi problema futuro potrà essere ricondotto alla registrazione di generazione esatta.

Risolvere gli errori più comuni

Quando una chiamata fallisce, segui questa checklist punto per punto. La maggior parte dei fallimenti rientra in una delle quattro categorie seguenti.

Autenticazione e accesso

  • 401 / unauthorized — chiave mancante, formattata male o non inviata. Verifica che l'intestazione sia esattamente Authorization: Bearer <key> e che la variabile d'ambiente sia effettivamente valorizzata nella shell o nel processo che effettua la chiamata.
  • 403 / forbidden — la chiave è valida, ma non è consentito accedere a questo endpoint. Controlla gli scope di permesso della chiave nella dashboard.

Validazione della richiesta

  • 400 / 422 — JSON malformato o valore di campo errato. Stampa il corpo completo della risposta di errore; di solito indica il campo. Ricontrolla il tipo di duration e il formato stringa di aspect_ratio.
  • 404 all'invio — percorso dell'endpoint errato. Verifica che il percorso sia esattamente pixverse-v6-max/text-to-video e che il tuo URL di base non abbia segmenti di percorso duplicati o mancanti.

Fallimenti a livello di attività

  • Stato failed — l'attività è stata accettata ma la generazione è fallita. Leggi il messaggio di errore sull'attività; distingue il rifiuto del contenuto dal guasto interno. Un prompt rifiutato è un problema del prompt, non dell'API — modificalo e invia di nuovo.
  • Bloccato in stato di esecuzione — imposta una scadenza per il polling e tratta il timeout come un fallimento da gestire, non come un'eccezione che fa crollare il servizio.

Problemi operativi

  • 429 / limite di frequenza raggiunto — troppi invii o polling in corso. Riduci la concorrenza e rispetta eventuali indicazioni di retry nella risposta.
  • Timeout di connessione all'invio — problema di rete o proxy, non di generazione. Riprova l'invio con backoff, ma solo se puoi tollerare la possibile creazione di attività duplicate.
  • 404 dell'URL video al download — l'URL è scaduto. Recupera di nuovo il risultato dell'attività invece di riutilizzare il vecchio URL.

Un'abitudine ripetibile

Per ogni fallimento registra tre valori: codice di stato HTTP, corpo della risposta e (se disponibile) task_id. Questi tre elementi trasformano "si è rotto" in "si è rotto qui", ed è l'unica chiave per rendere il debug più rapido.

Cosa fare dopo

Ora hai il ciclo completo: autenticazione, invio, ottenimento dell'identificatore di attività, polling con backoff e recupero del risultato. Per andare in produzione, incapsula invio e polling in una piccola classe client, memorizza task_id e prompt insieme a ogni asset per la tracciabilità, e sposta il polling in un processo worker in background, così le richieste rivolte all'utente non vengono mai bloccate dal rendering.

Successivamente, esplora gli endpoint adiacenti nella documentazione di riferimento HiAPI — image-to-video per animare fotogrammi statici esistenti, e la modalità di interazione iterativa dei prompt per rifinire lo stile visivo prima di impegnarti in una generazione completa. La forma della richiesta che hai imparato qui è trasferibile quasi invariata.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API