Blog

Tutoriale

Tutorial API per video da immagine con muse-video-1.0: curl e Python Requests

Nov 13, 2026
Copertina del tutorial di muse-video-1.0: sezione trasversale di un minerale sfaccettato piatto in verde acqua su un fondo blu petrolio profondo.
In questa pagina

Cosa richiede l'endpoint video da immagine di muse-video-1.0

L'endpoint muse-video-1.0/image-to-video trasforma una singola immagine statica in un breve video. Prima di scrivere la prima riga di codice, comprendere la struttura della richiesta ti aiuta a comporre il payload corretto al primo tentativo.

A livello alto, una chiamata coinvolge quattro aspetti:

  • Routing del modello — specifichi il modello come muse-video-1.0/image-to-video tramite l'API unificata HiAPI.
  • Immagine di input — il frame statico da cui parte l'animazione. È l'input creativo obbligatorio.
  • Opzioni di generazione — il comportamento dell'audio e i livelli di durata, che modellano le caratteristiche dell'output e non il materiale di origine.
  • Esecuzione asincrona — la generazione non restituisce il video finito inline. Invii prima un'attività, poi esegui il polling per ottenere il risultato.

Quest'ultimo punto è quello più spesso trascurato dagli sviluppatori. Poiché il rendering richiede tempo, l'endpoint si basa su un meccanismo a attività: la chiamata iniziale conferma la richiesta e restituisce un handle, poi si procede con le interrogazioni di stato finché il video non è pronto. Progetta il client fin dall'inizio attorno a questo flusso a due fasi, invece di aggiungere il polling solo in seguito.

Il corpo della richiesta è JSON. I campi sono organizzati in gruppi: l'immagine si trova in un blocco input dedicato, mentre audio e durata sono ad esso affiancati come impostazioni di generazione. Mantieni questo modello mentale — input, opzioni e ciclo di vita dell'attività separati — e il resto del tutorial sarà diretto.

Autenticazione

Ogni richiesta viene autenticata con la tua chiave API HiAPI, sotto forma di credenziale bearer nell'header Authorization. Tratta la chiave come segreto: caricala da una variabile d'ambiente, non codificarla direttamente in script che potresti condividere.

export HIAPI_API_KEY="your_api_key_here"

Dopo aver esportato la chiave, hai tutto il necessario per comprendere la richiesta. Le sezioni successive costruiscono il payload passo dopo passo.

Prepara e carica l'immagine del primo frame

L'immagine del primo frame è l'ancora creativa dell'intera attività. Il contenuto che fornisci diventa il frame zero e il modello anima a partire da lì. Farlo bene evita di sprecare generazioni.

Consigli pratici per il frame di origine

  • Usa un'immagine statica chiara e di alta qualità. Ciò che si legge bene come singolo frame offre al modello il miglior punto di partenza.
  • Scegli un rapporto d'aspetto coerente con l'output desiderato. Immagini orizzontali ampie e verticali alte producono composizioni molto diverse, quindi decidi l'orientamento prima del caricamento effettivo.
  • Evita motion blur marcato o soggetti ambigui. Un'immagine statica già stabile visivamente genera animazioni più prevedibili.
  • Assicurati che il file sia accessibile al momento della richiesta. Che tu passi un URL o un payload codificato, verifica che il riferimento sia raggiungibile nell'istante in cui invii l'attività.

Come l'immagine entra nella richiesta

L'immagine viene fornita nel blocco input del corpo JSON della richiesta. Un input immagine minimo è simile a questo:

{
  "input": {
    "image": "https://your-host.example/first-frame.jpg"
  }
}

Se la tua immagine di origine è memorizzata localmente, ospitala in una posizione accessibile alla richiesta oppure passala nella forma codificata accettata dall'endpoint. La regola chiave è: il valore in input.image deve risolversi in contenuto immagine reale al momento della creazione dell'attività — link corrotti o scaduti falliscono al momento dell'invio, non durante il polling, il che è in realtà un utile segnale precoce.

Verifica prima di generare

Un rapido controllo di sanità è prezioso: apri l'URL dell'immagine nel browser, conferma che si carichi, poi verifica che le dimensioni siano adatte all'output previsto. Due secondi di controllo qui evitano un debug confuso in seguito.

Una volta che il primo frame è pronto e accessibile, puoi passare alle opzioni di generazione.

Configura i parametri audio e i livelli di durata

Oltre all'immagine, muse-video-1.0/image-to-video offre due categorie di opzioni che modificano le caratteristiche dell'output: comportamento dell'audio e durata.

Parametro audio

L'audio è rappresentato da un campo nel corpo della richiesta, affiancato al tuo input. Stabilisci l'intento prima della chiamata:

  • Output muto — mantieni l'audio disattivato se prevedi di aggiungere la tua colonna sonora in post-produzione o se ti serve una traccia video pulita.
  • Audio abilitato — attiva l'audio se la clip deve avere un proprio suono. Verifica esplicitamente questa opzione nel payload piuttosto che assumere il valore predefinito.

Poiché l'elaborazione audio è una proprietà della richiesta stessa e non un passaggio di post-produzione, vale la pena definirla prima di scalare. Se la tua pipeline mixa clip mute e clip con audio, modella la scelta come parametro esplicito nel codice del tuo client, per evitare che avvenga accidentalmente.

Livelli di durata

L'endpoint ti permette di scegliere un livello di durata per la clip. Considera la durata come una decisione intenzionale sia creativa che di costo:

  • Livelli più brevi sono adatti a anteprime rapide, clip social e test di storyboard, quando vuoi riscontri rapidi su molte immagini di origine.
  • Livelli più lunghi danno all'animazione più spazio per svilupparsi, e sono più adatti a riprese hero o sequenze che necessitano di respiro.

La durata viene fatturata in secondi di output, quindi il livello che scegli influisce direttamente sul consumo. Non c'è vantaggio nel renderizzare clip lunghe solo per un rapido controllo visivo — usa livelli brevi durante l'iterazione del primo frame, poi promuovi le impostazioni vincenti a livelli più lunghi.

Combina insieme queste opzioni

In JSON, le impostazioni audio e durata sono affiancate al blocco input:

{
  "input": {
    "image": "https://your-host.example/first-frame.jpg"
  },
  "audio": true,
  "duration": "<duration_tier>"
}

Usa gli identificatori esatti dei livelli forniti nella documentazione dell'endpoint, invece di indovinare i valori. La sezione successiva li trasforma in una richiesta eseguibile.

Una richiesta curl funzionante

Una volta assemblato il payload, ecco il comando curl per l'invio iniziale. Crea l'attività; non restituisce il video finito.

curl -X POST "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "image": "https://your-host.example/first-frame.jpg"
    },
    "audio": true,
    "duration": "<duration_tier>"
  }'

Alcune note su questo comando:

  • L'URL specifica il modello per nome. Non hai bisogno di un client separato per ogni modello; il percorso identifica già muse-video-1.0/image-to-video.
  • L'header trasporta la tua chiave. $HIAPI_API_KEY viene espansa dalla variabile d'ambiente che hai esportato in precedenza, quindi la chiave non appare mai nello script stesso.
  • Il corpo è il payload che hai appena costruito. L'URL dell'immagine, il flag audio e il livello di durata vengono passati insieme.

La risposta è una conferma dell'attività: contiene l'identificatore dell'attività appena creata. Copia quell'identificatore — servirà nel passaggio di polling. Se stai solo esplorando, puoi formattare la risposta con uno strumento JSON per trovare più facilmente il job ID.

Se l'invio fallisce, l'errore è di solito immediato e specifico: corpo JSON malformato, riferimento immagine mancante o valore di opzione non riconosciuto. Questo ciclo di feedback rapido è proprio il motivo per cui vale la pena testare l'invio separatamente prima di integrare il polling.

La stessa richiesta in Python

La maggior parte delle integrazioni finisce per essere realizzata in Python, quindi ecco l'invio equivalente usando la libreria standard — nessun SDK di terze parti necessario.

import json
import os
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video"

payload = {
    "input": {
        "image": "https://your-host.example/first-frame.jpg"
    },
    "audio": True,
    "duration": "<duration_tier>",
}

request = urllib.request.Request(
    ENDPOINT,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    method="POST",
)

with urllib.request.urlopen(request) as response:
    result = json.loads(response.read().decode("utf-8"))

job_id = result["id"]
print("Submitted job:", job_id)

Lo script corrisponde campo per campo alla chiamata curl. Alcune abitudini che vale la pena adottare:

  • Conserva il payload in un dizionario. Costruirlo come dizionario Python significa che puoi passare la stessa struttura a qualsiasi libreria HTTP — urllib, requests o un client asincrono — senza riscrivere la logica.
  • Leggi la chiave dall'ambiente. os.environ tiene le credenziali fuori dal controllo del codice sorgente.
  • Analizza subito la risposta come JSON. Estrarre il job ID in una variabile denominata rende più chiaro il passaggio di polling.

Se preferisci la libreria requests, l'unico cambiamento è il livello di trasporto: costruisci lo stesso dizionario payload e invialo con il tuo set di header, poi chiama .json() sulla risposta. Endpoint, header e corpo restano identici.

Dopo aver inviato l'attività e catturato il suo identificatore, resta solo da attendere il risultato nel modo corretto.

Esegui il polling dell'attività asincrona e ottieni il video

La generazione video non è istantanea, quindi l'endpoint è asincrono. Dopo l'invio, esegui il polling dello stato dell'attività per sapere quando il rendering è terminato, poi recuperi l'output.

Ciclo di polling

Un ciclo robusto fa tre cose: attende tra un controllo e l'altro, imposta un limite per non girare all'infinito e distingue tra "ancora in elaborazione", "completato" e "fallito".

import time
import urllib.request

STATUS_ENDPOINT = "https://api.hiapi.ai/v1/jobs/{job_id}"

def wait_for_video(job_id, max_attempts=60, interval=5):
    for attempt in range(max_attempts):
        url = STATUS_ENDPOINT.format(job_id=job_id)
        request = urllib.request.Request(
            url,
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        with urllib.request.urlopen(request) as response:
            status = json.loads(response.read().decode("utf-8"))

        state = status.get("status")
        if state == "succeeded":
            return status.get("output")
        if state == "failed":
            raise RuntimeError(f"Job {job_id} failed: {status}")

        time.sleep(interval)

    raise TimeoutError(f"Job {job_id} did not finish in time")

Punti di progettazione per la produzione

  • Usa un intervallo ragionevole. Cinque secondi è un buon punto di partenza; non martellare l'endpoint di stato.
  • Limita sempre il numero di tentativi. Il limite max_attempts trasforma un'attesa infinita in un errore chiaro da registrare e su cui generare avvisi.
  • Gestisci esplicitamente gli stati di fallimento. Le attività fallite contengono informazioni diagnostiche — esponile, invece di ritentare silenziosamente lo stesso input.
  • Persisti il job ID. Se il tuo processo si riavvia, puoi riprendere il polling senza pagare una nuova generazione.

Recupera l'output

Quando l'attività ha successo, la risposta di stato include il riferimento all'output del video finito. Scaricalo prontamente nel tuo storage, invece di affidarti a link a lunga scadenza. Una volta che hai il file in locale o nel tuo bucket, dal punto di vista della pipeline la generazione è completa.

Questo è l'intero ciclo di vita: invio, polling, recupero. Mantieni le due fasi separate nel codice e ciascuna resterà semplice.

Insidie comuni e tecniche di debug

La maggior parte dei problemi di integrazione con muse-video-1.0/image-to-video rientra in poche categorie. Ecco cosa controllare quando qualcosa va storto.

Problemi con l'immagine di input

  • Riferimento immagine non raggiungibile. Se l'URL richiede autenticazione o è scaduto, l'attività fallisce all'invio. Ospita il frame in una posizione pubblicamente leggibile durante la richiesta.
  • Rapporto d'aspetto non corrispondente. Forzare un'immagine statica verticale in un output orizzontale porta a ritagli scomodi o bande nere. Imposta l'orientamento di origine per corrispondere al target.
  • Contenuto sbagliato. È facile puntare a una miniatura o a un'immagine segnaposto invece del frame reale. Verifica che l'URL apra l'immagine prevista.

Errori nei parametri

  • Indovinare i valori di durata. Usa gli identificatori di livello esattamente come indicati nella documentazione dell'endpoint. I valori non riconosciuti sono una causa comune di rifiuto.
  • Dimenticare il flag audio. Se ometti l'impostazione audio ma ti aspetti il suono, potresti ottenere una clip muta. Specifica esplicitamente se l'audio è necessario.
  • Confondere i campi di primo livello con i campi input. L'immagine va dentro input; audio e durata sono fratelli di input, non suoi figli. Un annidamento errato produce messaggi di validazione confusi.

Errori di polling

  • Trattare l'invio come completamento. La prima risposta è solo una conferma, non il video. Esegui sempre il controllo di stato successivo.
  • Polling illimitato. Un ciclo senza limite blocca il tuo worker se l'attività si blocca. Aggiungi un limite e un errore di timeout.
  • Ignorare i fallimenti. Un'attività terminata con stato di fallimento non produrrà mai un video; catturala ed esamina le informazioni diagnostiche, invece di continuare ad attendere.
  • Attendere a lungo su input errati. Quando il rendering continua a fallire, smetti di rigenerare. Correggi prima il frame di origine o i parametri, poi invia di nuovo.

Un ordine di debug efficace

  1. Verifica che l'URL dell'immagine si carichi nel browser.
  2. Invia un payload minimo con la sola immagine, per isolare i problemi di parametri.
  3. Verifica che il job ID venga restituito correttamente.
  4. Esegui prima il polling manualmente, osservando le transizioni di stato.
  5. Solo dopo, automatizza il ciclo e aggiungi retry per gli errori di rete transitori.

Affrontare questi passaggi in ordine restringe rapidamente il problema a uno strato specifico — immagine, opzioni o ciclo di vita — e mantiene l'integrazione in movimento. Una volta compresi la struttura della richiesta, le opzioni e il flusso di polling, sei pronto a costruire su questo endpoint.

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