Tutoriale
Chiamare muse-video-1.0/text-to-video tramite l'API HiAPI: guida a curl e Python
Campi della richiesta, polling asincrono ed esempi di richiesta eseguibili
In questa pagina
Prima di inviare: autenticazione, endpoint e identificatore del modello
muse-video-1.0/text-to-video converte un prompt testuale in una clip video generata. Invii un prompt e alcuni parametri di controllo, il servizio renderizza la clip e poi restituisce un URL o un riferimento scaricabile.
Il dettaglio architetturale chiave è questo: la chiamata è asincrona. Il rendering video richiede tempo e l'API non mantiene aperta la tua connessione HTTP fino a quando il file è pronto. Il flusso si articola quindi in due fasi:
- Invio: invii via POST il prompt e i parametri. La risposta arriva rapidamente e contiene l'identificatore del task e lo stato iniziale del task.
- Polling: a intervalli, esegui una GET del task tramite l'identificatore finché il suo stato non diventa terminale (successo o fallimento), quindi recuperi il risultato.
Questa forma "prima invia, poi esegui il polling" è il punto più importante da interiorizzare prima di scrivere codice. Cambia la struttura dell'applicazione: il video non compare nella risposta alla richiesta di invio e qualsiasi errore che incontri appartiene a una fase specifica: invio, validazione, rendering o recupero. Distinguere queste fasi nel tuo codice (usando funzioni diverse e registrandole separatamente) renderà più facile applicare il resto di questa guida.
La stringa del modello passata deve essere esatta: muse-video-1.0/text-to-video. La forma vendor/model è la convenzione comune per gli endpoint dei modelli HiAPI e l'API usa proprio questa per instradare la chiamata al generatore corretto.
Costruire la richiesta: prompt, durata e campi audio
Prima della prima richiesta devi preparare tre cose.
Chiave API
Ogni richiesta deve essere autenticata tramite bearer token. Conservala in una variabile d'ambiente anziché nel codice sorgente, per evitare che finisca nei commit:
export HIAPI_API_KEY="your_key_here"
Inviala nell'header Authorization: Bearer $HIAPI_API_KEY. Se una richiesta fallisce con un errore di autenticazione, controlla per prima cosa questo header: i nomi di variabile scritti male, gli spazi finali o un valore non impostato nella shell corrente sono le cause più comuni.
URL di base
Tutte le chiamate condividono un unico URL di base della piattaforma HiAPI. Usa il valore corrente presente nel pannello dell'account o nel riferimento API, non copiarlo da vecchi frammenti di codice; salvalo in una variabile così devi modificarlo in un solo punto.
Identificatore del modello
La stringa del modello è muse-video-1.0/text-to-video. Trattala come un letterale sensibile alle maiuscole. Non costruire né indovinare varianti, come maiuscole diverse o suffissi mancanti: un identificatore di modello sconosciuto produce un errore di validazione, non un fallback.
Con questi tre elementi pronti, puoi costruire il corpo della richiesta.
Una richiesta curl funzionante
Il corpo della richiesta è JSON. Concettualmente contiene tre gruppi di campi.
Prompt
Il prompt è l'istruzione creativa e determina gran parte della qualità dell'output. Un prompt efficace descrive in modo specifico soggetto, azione, comportamento della camera, illuminazione e stile, invece di accumulare solo aggettivi. È un normale campo stringa.
Durata
I modelli text-to-video devono sapere quanto deve durare la clip. La durata è un campo della richiesta e influisce anche sul costo: la generazione viene fatturata in base ai secondi di output. Poiché l'intervallo accettabile e il valore predefinito sono definiti dal modello in un dato momento, leggi il nome esatto del campo e i valori consentiti dal riferimento API aggiornato di muse-video-1.0/text-to-video, senza indovinare. Una durata fuori intervallo causa un errore di validazione.
Audio
muse-video-1.0/text-to-video supporta, oltre alla generazione visiva, anche controlli legati all'audio. Anche questi sono campi della richiesta, di solito interruttori o input in stile prompt audio, e il loro nome esatto e i valori accettabili sono documentati nello stesso riferimento API. Per la prima integrazione, l'approccio prudente è omettere del tutto i campi audio opzionali, verificare che il video venga restituito correttamente e poi aggiungere le opzioni audio una alla volta.
Il corpo minimo della richiesta è quindi più o meno questo (i nomi dei campi sono solo esempi: verificali sul riferimento):
{
"model": "muse-video-1.0/text-to-video",
"prompt": "All'alba, una lenta ripresa aerea avanza su una pineta avvolta dalla nebbia, luce volumetrica soffusa, atmosfera cinematografica",
"duration": 5
}
Poiché l'insieme dei parametri può evolvere, l'abitudine affidabile è: recupera la documentazione di riferimento del modello, copia i nomi dei campi alla lettera e validali localmente prima dell'invio.
La stessa richiesta in Python
La chiamata di invio è un normale POST HTTP. Il percorso esatto della risorsa è definito dal riferimento API HiAPI; l'esempio seguente usa il consueto endpoint dei task, con il modello nel corpo della richiesta.
curl -sS -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "muse-video-1.0/text-to-video",
"prompt": "Un robot di cartone attraversa un vicolo al neon sotto la pioggia, riflessi sull'asfalto bagnato, grana pellicola 35mm",
"duration": 5
}'
La risposta è piccola e torna rapidamente. Ciò che conta è l'identificatore del task e lo stato. La struttura tipica è questa:
{
"id": "job_abc123",
"status": "queued"
}
Registra id: è l'handle per tutte le chiamate successive. Che status sia queued o processing è normale: indica che la richiesta è stata accettata, non che c'è un problema.
Polling manuale nella shell:
curl -sS "$HIAPI_BASE_URL/v1/video/generations/job_abc123" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Eseguilo alcune volte a intervalli per osservare il passaggio di status verso uno stato terminale. In pratica, vuoi mettere questo ciclo nel codice anziché nella cronologia del terminale.
Gestire i risultati asincroni e il polling senza martellare l'API
La versione Python fa le stesse due cose, invio e poi polling, ma aggiunge gestione dei timeout, retry con limite e salvataggio del risultato, così può essere eseguita senza supervisione in sicurezza.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}
MODEL = "muse-video-1.0/text-to-video"
def submit(prompt: str, duration: int) -> str:
resp = requests.post(
f"{BASE}/v1/video/generations",
headers={**HEADERS, "Content-Type": "application/json"},
json={"model": MODEL, "prompt": prompt, "duration": duration},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for(job_id: str, max_wait: int = 900) -> dict:
deadline = time.time() + max_wait
interval = 5
while time.time() < deadline:
r = requests.get(
f"{BASE}/v1/video/generations/{job_id}",
headers=HEADERS,
timeout=30,
)
if r.status_code >= 500 or r.status_code == 429:
time.sleep(interval)
interval = min(interval * 2, 30)
continue
r.raise_for_status()
job = r.json()
if job["status"] == "succeeded":
return job
if job["status"] == "failed":
raise RuntimeError(job.get("error") or "generation failed")
time.sleep(interval)
interval = min(interval * 1.5, 30)
raise TimeoutError(f"job {job_id} did not finish in time")
def save(job: dict, path: str) -> None:
url = job["result"]["video_url"]
with requests.get(url, stream=True, timeout=120) as r:
r.raise_for_status()
with open(path, "wb") as f:
for chunk in r.iter_content(8192):
f.write(chunk)
if __name__ == "__main__":
job_id = submit(
"Un piccolo terrario in vetro su un tavolo di legno, luce del mattino, particelle di polvere sospese, macro",
5,
)
job = wait_for(job_id)
save(job, "output.mp4")
print("saved output.mp4")
Ci sono tre scelte ponderate. I retry sono limitati da una scadenza, non da un numero di cicli, così non si bloccano all'infinito. Il backoff cresce in caso di errori transitori e cresce lentamente nel percorso di polling riuscito. Il download è una richiesta streaming separata, evitando di far passare file grandi attraverso il percorso JSON.
Errori comuni e come risolverli
La frequenza di polling è una vera scelta progettuale. Un polling ogni 200 ms genera solo carico inutile; un polling ogni cinque minuti spreca tempo reale dopo che il rendering è terminato.
Strategia pratica:
- Parti da un intervallo moderato (pochi secondi) e cresci gradualmente: moltiplicare per 1,5 a ogni polling, con un tetto di circa mezzo minuto, funziona bene.
- Aumenta il backoff sulle risposte
429e5xx: raddoppia l'intervallo e riprova, trattandole come segnale di capacità e non come stato del task. - Imposta un tempo massimo di attesa totale e genera un errore allo scadere, invece di eseguire polling per sempre. I rendering più lunghi richiedono effettivamente più tempo, quindi il limite va impostato in base al proprio carico di lavoro.
- Registra la transizione una sola volta, solo quando lo stato cambia, non a ogni polling: log rumorosi rendono difficile individuare i veri fallimenti.
La risposta di un task completato contiene di solito lo status terminale, l'id del task e un payload del risultato con l'URL del video scaricabile, talvolta con metadati e scadenza dell'URL. Scarica il file tempestivamente dopo il successo. Se il task riporta failed, leggi il messaggio di errore nella risposta prima di riprovare: gli errori di validazione non avranno mai successo con un retry, mentre gli errori interni di rendering potrebbero riuscirci.
Passi successivi
Inizia con il corpo minimo della richiesta, verifica un'esecuzione end-to-end riuscita, poi aggiungi i controlli di durata e audio confrontando la documentazione di riferimento aggiornata di muse-video-1.0/text-to-video. Lo stesso schema "prima invia, poi esegui il polling" è trasferibile ad altri endpoint dei modelli HiAPI, quindi il codice client che scrivi qui è riutilizzabile.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
Guida pratica a gpt-6.2-sol: 5 utilizzi ad alto valore dei modelli testuali nel business
-
Tutoriale
Guida pratica a gpt-6.2-astra: integrazione e punti chiave per 5 scenari testuali ad alto valore
Checklist dal punto di vista dello sviluppatore, dalla selezione degli scenari all'implementazione ingegneristica
-
Tutoriale
Scenari pratici di Tripo H3.1: 5 utilizzi ad alto valore e punti di implementazione
Da text-to-3D alla ricostruzione multi-view: scegliere modalità e parametri giusti per ogni scenario di business