Blog

Tutoriale

Come chiamare happyhorse-1.1/text-to-video tramite l'API HiAPI: esempi curl e Python funzionanti

Struttura delle richieste per un'integrazione funzionante, polling asincrono e gestione dell'audio nativo

Nov 12, 2026
Immagine di copertina: su uno sfondo verde pino profondo, alcuni prismi astratti suddivisi in superfici piatte di colore, che compongono una sobria costruzione geometrica con blocchi di verde grigio e verde nebbia.
In questa pagina

Cosa copre questa integrazione

Questa guida ti accompagna nel processo completo di chiamata a happyhorse-1.1/text-to-video tramite l'API unificata HiAPI. Al termine avrai una richiesta funzionante: inviare un prompt testuale, eseguire il polling fino al completamento e salvare il video generato con la sua traccia audio nativa. Inizieremo con la struttura della richiesta, così da comprendere il payload prima di scrivere qualsiasi codice; poi forniremo una chiamata curl pronta da copiare; quindi spiegheremo il pattern di polling asincrono necessario per la generazione video; infine porteremo tutto in Python aggiungendo una gestione degli errori di base. Non è necessaria esperienza con le API video: ti servono solo una chiave API HiAPI e un terminale o un ambiente Python. L'obiettivo è offrire un esempio di integrazione minimo ma completo, che tu possa adattare alla tua pipeline.

Struttura della richiesta per happyhorse-1.1/text-to-video

Prima di effettuare la chiamata, è utile comprendere i campi che compongono una richiesta text-to-video. L'endpoint accetta un payload JSON che contiene almeno l'identificatore del modello e il tuo prompt testuale. Altri campi comuni controllano dimensioni e durata dell'output, ma i nomi esatti dei parametri e i valori accettati vanno verificati nella documentazione del modello su HiAPI. Un payload valido in genere si presenta così:

{
  "model": "happyhorse-1.1/text-to-video",
  "prompt": "All'alba, la camera esegue una lenta panoramica su una foresta avvolta nella nebbia"
}

Mantieni il payload piatto e usa solo i campi indicati nella documentazione del modello. Campi non riconosciuti o tipi formattati in modo errato sono la causa più comune di rifiuto delle richieste. In caso di dubbi, inizia con un payload minimo contenente solo model e prompt, poi aggiungi i parametri opzionali uno alla volta per individuare eventuali problemi.

Prima richiesta con curl

Una volta pronto il payload, puoi inviare il job con curl. Effettuerai una richiesta POST con corpo JSON e la chiave API nell'header Authorization. La risposta di solito contiene l'identificatore del job, che userai in seguito per interrogare lo stato. Ecco un esempio funzionante:

curl -X POST https://api.hiapi.ai/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "prompt": "All'alba, la camera esegue una lenta panoramica su una foresta avvolta nella nebbia"
  }'

Sostituisci $HIAPI_API_KEY con la tua chiave effettiva oppure esportala nella shell. La risposta sarà in JSON e conterrà un campo id (o un identificatore con nome simile) e uno stato che indica che il job è stato accettato. Leggi attentamente la risposta: se lo stato non è quello di accettazione, controlla il messaggio di errore prima di procedere. Non dare per scontato che il video sia già pronto: il job è appena entrato in coda.

Gestione del polling asincrono

La generazione video non è istantanea, quindi HiAPI restituisce nella risposta iniziale un identificatore del job anziché il video finale. Devi interrogare l'endpoint di stato finché il job non raggiunge uno stato terminale. Il pattern generale è: inviare il job, ottenere l'ID, quindi richiedere ripetutamente lo stato del job a intervalli brevi. Fermati quando lo stato indica successo o fallimento. Ecco la logica in pseudocodice:

  1. Invia il job e leggi l'id del job.
  2. Attendi qualche secondo.
  3. Richiedi lo stato del job usando quell'id.
  4. Se lo stato è "completed" o "succeeded", recupera l'URL di output ed esci dal ciclo.
  5. Se lo stato è "failed", registra l'errore ed esci.
  6. Altrimenti, attendi di nuovo e ripeti fino a raggiungere un numero massimo ragionevole di tentativi.

Evita di interrogare troppo frequentemente. Per i job video, di solito è sufficiente attendere qualche secondo tra un tentativo e l'altro. Inoltre, non aspettarti che una singola risposta bloccante contenga il video finale: il modello asincrono è intenzionale ed è coerente in tutti i job di generazione di lunga durata.

Audio nativo nell'output

I video generati da happyhorse-1.1/text-to-video includono audio nativo nell'output. Al completamento del job, la risposta punta al file video generato, che contiene già la traccia audio. Non devi generare o recuperare l'audio separatamente. Per salvare e verificare il risultato, scarica il file video dall'URL fornito e conserva il formato del container. Se elabori il file a livello di codice, verifica la presenza del flusso audio, ad esempio usando uno strumento multimediale per ispezionare il file. A meno che la pipeline a valle non lo richieda, non rimuovere né ricodificare l'audio, perché così facendo potresti ridurne la qualità o eliminare del tutto la traccia. Considera il file restituito come un asset audiovisivo completo.

La stessa richiesta in Python

Portare la chiamata curl in Python è semplice: riutilizza lo stesso payload JSON e aggiungi il ciclo di polling. L'esempio seguente usa requests, attende tra un tentativo e l'altro e solleva un'eccezione in caso di fallimento. Sostituisci il percorso dell'endpoint e i nomi dei campi di stato con quanto indicato nella documentazione di happyhorse-1.1/text-to-video su HiAPI.

import os
import time
import requests

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

payload = {
    "model": "happyhorse-1.1/text-to-video",
    "prompt": "All'alba, la camera esegue una lenta panoramica su una foresta avvolta nella nebbia",
}

resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json=payload)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]

for attempt in range(60):
    status_resp = requests.get(f"{BASE}/video/generations/{job_id}", headers=HEADERS)
    status_resp.raise_for_status()
    status = status_resp.json()
    state = status.get("status")
    if state in ("completed", "succeeded"):
        video_url = status["output"]["url"]
        print("Video pronto:", video_url)
        break
    if state == "failed":
        raise RuntimeError(status.get("error", "Generazione non riuscita"))
    time.sleep(5)
else:
    raise TimeoutError("Timeout del polling")

Questo segue la logica di "polling fino al completamento" descritta in precedenza. Usa raise_for_status() per esporre subito gli errori HTTP e mantieni un intervallo di attesa ragionevole per evitare richieste inutili.

Risoluzione dei problemi comuni

La maggior parte dei problemi di integrazione rientra in poche categorie. Un payload malformato, ad esempio con il campo model mancante o un tipo JSON errato, viene rifiutato immediatamente; controlla attentamente il tuo JSON rispetto alla documentazione del modello. Un polling troppo frequente può causare limiti di frequenza o carichi inutili; aumenta l'intervallo di attesa. Un altro errore comune è scambiare la risposta iniziale per il video finale; esegui sempre il polling fino a uno stato terminale. Gli errori di autenticazione di solito indicano un header Authorization mancante o malformato, quindi verifica che la tua chiave API sia esportata correttamente. Infine, se il job fallisce dopo il polling, controlla il messaggio di errore nella risposta di stato; di solito indica un prompt non valido o un parametro non supportato. Dopo aver corretto questi problemi, riprova con un payload minimo valido.

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