Blog

Tutoriale

Come chiamare l'API image-to-video di seedance-2.5: esempi curl e Python disponibili

Nov 12, 2026
Copertina astratta: lastre di vetro traslucide sovrapposte che proiettano fasce blu fredde su un campo grigio pallido, piatto e architettonico.
In questa pagina

Cosa offre l'endpoint image-to-video di seedance-2.5

seedance-2.5 image-to-video è un endpoint modello asincrono su HiAPI che converte una o due immagini statiche in una breve clip video. Gli invii un'immagine (o una coppia di immagini che fungono rispettivamente da punto di partenza e di arrivo del movimento), descrivi il cambiamento desiderato e la piattaforma restituisce un'attività che, al termine della generazione, si risolve in un URL di file video.

In un tipico stack di generazione video, questo endpoint si colloca al livello "dai vita all'immagine statica". Hai già le immagini di partenza — foto di prodotto, render di personaggi, fotogrammi di storyboard — e ciò che ti serve è l'animazione, non una nuova immagine. Poiché la chiamata è asincrona, il tuo compito è inviare l'attività, conservarne l'identificatore e interrogarla ripetutamente finché il risultato non è pronto. Questo schema di invio e successiva interrogazione è comune agli endpoint di generazione a esecuzione prolungata di HiAPI, quindi il client che scrivi qui può essere riutilizzato con altri modelli.

L'endpoint offre anche opzioni di audio nativo, il che è importante se il tuo flusso di lavoro richiede una clip con sonoro anziché un materiale muto a cui aggiungere la musica in seguito. Se ti serve un movimento di camera preciso al fotogramma o un'animazione in loop, l'image-to-video con first frame e last frame espliciti è di solito la scelta più controllabile senza costruire una scena 3D.

Prerequisiti e autenticazione

Prima della prima chiamata, prepara tre cose.

1. Una chiave API HiAPI

Ogni richiesta si autentica con la tua chiave, inviata come bearer token nell'header Authorization. Non inserirla nel controllo del codice sorgente — leggila da una variabile d'ambiente, così lo stesso script può essere eseguito sia in locale sia in CI.

export HIAPI_API_KEY="your_key_here"

2. Immagini di partenza accessibili all'API

Gli input immagine sono URL. Ospita le immagini in una posizione accessibile al servizio — object storage con URL firmati, una CDN o qualsiasi indirizzo HTTPS pubblico. Se non vuoi esporre pubblicamente le immagini, genera un URL firmato a breve scadenza anziché rendere pubblico il bucket.

Per il flusso di lavoro first frame/last frame ti serve un'immagine (solo first frame) o due immagini (first frame e last frame).

3. Un client HTTP

Qualsiasi strumento in grado di inviare JSON va bene: curl per test rapidi, requests o httpx in Python, fetch in Node. Non serve un SDK speciale.

L'URL di base, il percorso e i nomi dei campi specifici del modello si trovano nella pagina del modello nella console HiAPI; usa questi valori alla lettera negli esempi seguenti. Una volta che hai la chiave e gli URL delle immagini, puoi inviare la richiesta.

Input first frame e input last frame

I due input immagine controllano estremità diverse della clip e scegliere l'uno o l'altro cambia il tuo grado di controllo sul movimento.

Solo first frame. Fornisci un'immagine e il modello genera in avanti da essa. È la scelta giusta quando vuoi che il modello inventi il movimento: un ritratto che si gira lentamente, un prodotto che ruota, un paesaggio con nuvole che si spostano. Rinunci alla certezza su dove finirà la clip, ma ottieni maggiore libertà creativa e ti serve un solo materiale.

First frame e last frame. Fornisci due immagini e il modello genera il percorso tra esse. È la scelta giusta quando l'arrivo è importante: un logo che si ricompone nel marchio finale, un personaggio che passa dalla posa A alla posa B, un oggetto che scorre da sinistra a destra nell'inquadratura. Fornire il last frame vincola il movimento, il che di solito significa meno sorprese e una migliore riproducibilità in loop se prevedi di ripetere la clip.

Una regola pratica: se riesci a descrivere la clip come "questa immagine cambia in qualche modo", usa solo il first frame. Se riesci a descriverla come "questa immagine diventa quell'immagine", forniscine due. Quando ne fornisci due, mantieni le immagini coerenti per composizione, rapporto d'aspetto e illuminazione — coppie di immagini non abbinate costringono il modello a gestire un salto che appare come un glitch.

Il tuo prompt dovrebbe integrare le immagini, non contraddirle. Descrivi il movimento, non il contenuto statico che il modello può già vedere.

Inviare la prima richiesta con curl

La seguente richiesta invia un'attività image-to-video. Sostituisci il percorso dell'endpoint, l'identificatore del modello e i nomi dei campi con i valori mostrati nella pagina del modello image-to-video seedance-2.5 nella console HiAPI, e inserisci gli URL delle tue immagini.

curl -X POST "$HIAPI_BASE_URL/<image-to-video-path>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5/image-to-video",
    "prompt": "The camera slowly pushes in as the subject turns toward the light",
    "first_frame_image": "https://your-cdn.example.com/frame-01.jpg",
    "last_frame_image": "https://your-cdn.example.com/frame-02.jpg"
  }'

Alcune cose da notare sulla struttura della richiesta:

  • prompt descrive il movimento. Mantienilo breve e specifico; lunghi elenchi di aggettivi tendono a diluire l'istruzione.
  • first_frame_image è obbligatorio per image-to-video. last_frame_image è facoltativo — per la generazione con solo first frame ometti completamente il campo.
  • Se ti servono le opzioni audio, sono campi aggiuntivi nello stesso corpo JSON (descritti di seguito).

La risposta è un oggetto attività contenente un identificatore e uno stato. Salva l'identificatore; ti servirà a ogni interrogazione. Se la chiamata restituisce un errore di autenticazione o di validazione, controlla prima gli header e l'URL dell'immagine, poi riprova.

La stessa richiesta in Python

Di seguito il codice di invio equivalente in Python, ristrutturato per catturare facilmente l'identificatore dell'attività.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<image-to-video-path>"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_video(first_frame, last_frame=None, prompt="", audio=False):
    payload = {
        "model": "seedance-2.5/image-to-video",
        "prompt": prompt,
        "first_frame_image": first_frame,
    }
    if last_frame:
        payload["last_frame_image"] = last_frame
    if audio:
        payload["audio"] = True

    resp = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    data = resp.json()
    return data["task_id"], data

task_id, raw = submit_video(
    first_frame="https://your-cdn.example.com/frame-01.jpg",
    last_frame="https://your-cdn.example.com/frame-02.jpg",
    prompt="The camera slowly pushes in as the subject turns toward the light",
)
print(task_id)

Due abitudini che vale la pena adottare presto. Primo, imposta un timeout esplicito sulle chiamate di invio — una richiesta bloccata dovrebbe fallire rapidamente anziché bloccare il tuo worker. Secondo, conserva la risposta grezza durante lo sviluppo. Il campo che contiene l'identificatore dell'attività potrebbe differire da task_id a seconda della versione dell'endpoint; stampare una volta il JSON grezzo può risparmiarti un ciclo di debug.

Interrogare l'attività asincrona finché il video non è pronto

La generazione image-to-video richiede più tempo di quanto una singola richiesta HTTP dovrebbe restare aperta, quindi la piattaforma adotta un ciclo di vita basato su invio e successiva interrogazione. L'invio restituisce l'identificatore dell'attività; poi interroghi periodicamente l'endpoint delle attività finché il suo stato non raggiunge uno stato terminale.

import time
import requests

def wait_for_video(task_id, interval=5, max_wait=600):
    url = f"{BASE_URL}/<task-path>/{task_id}"
    deadline = time.time() + max_wait
    while time.time() < deadline:
        resp = requests.get(url, headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()
        status = task.get("status")
        if status == "succeeded":
            return task["video_url"]
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"Task {task_id} ended as {status}: {task.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} not ready after {max_wait}s")

Progetta l'interrogazione attorno a quattro regole:

  • Interroga a intervalli moderati. Cinque secondi è un valore predefinito ragionevole. Saturare l'endpoint non renderizza il video più velocemente.
  • Imposta sempre una scadenza. Le attività possono fallire o restare in coda più del previsto; un ciclo senza limiti trasforma un problema temporaneo in un worker bloccato.
  • Considera failed e cancelled come stati terminali. Espone il campo di errore invece di riprovare all'infinito la stessa attività.
  • Usa il backoff durante le interrogazioni continue. Se interroghi molte attività contemporaneamente, aumenta gradualmente l'intervallo per evitare picchi di traffico.

In produzione, interroga da un worker in background o da una coda, non all'interno del gestore di richieste web. Il risultato è un URL video; scaricalo tempestivamente e copialo nel tuo storage, poiché gli URL delle risorse generate di solito non sono permanenti.

Gestire il flag dell'audio nativo

seedance-2.5 può generare clip con audio nativo; questo controllo è un campo della richiesta accanto agli input immagine e al prompt — non un endpoint separato. Il nome esatto del campo e i valori accettati sono elencati nella pagina del modello; la funzione helper Python sopra lo illustra passando un valore booleano audio.

Se abilitarlo dipende da come verrà utilizzata la clip.

Richiedi l'audio quando: l'output è destinato direttamente al pubblico — post social, anteprime, demo — e vuoi che la clip risulti completa senza un secondo montaggio. L'audio nativo aiuta anche i revisori a giudicare il ritmo, perché il suono rende più leggibile la scansione temporale del movimento.

Salta l'audio quando: il tuo flusso di lavoro sovrappone una propria colonna sonora, la clip deve essere inviata a uno strumento di compositing o montaggio, oppure prevedi di generare molte varianti e aggiungere musica solo alla versione finale scelta. La generazione muta mantiene il materiale neutro ed evita problemi di sincronizzazione successivi.

Una nota pratica per restringere il campo: considera l'audio come una decisione per singola richiesta, non come un'impostazione globale. Come mostrato sopra, un'unica funzione helper che accetta un flag audio consente allo stesso percorso di codice di servire sia l'elaborazione batch silenziosa in background sia il rendering finale rifinito.

Se il flag è presente ma il risultato è muto, verifica prima che il valore sia serializzato come previsto — la stringa "true" e il booleano true sono un disallineamento comune — prima di supporre che il modello lo abbia ignorato.

Punti di errore comuni e passi successivi

La maggior parte dei problemi di prima integrazione rientra in quattro categorie.

Input non recuperabili dal servizio

Un URL che funziona nel tuo browser può fallire lato server: bucket privati, link scaduti o host che bloccano user agent non browser. Usa URL firmati con una durata sufficiente a coprire l'intera generazione e verifica che le immagini si carichino da una macchina esterna alla tua rete.

Frame non corrispondenti

Quando first frame e last frame differiscono per rapporto d'aspetto, ritaglio o temperatura colore, il modello deve riconciliare questo salto. Prima dell'invio, preprocessa la coppia di immagini con dimensioni identiche e una gradazione cromatica simile.

Nomi di campo o identificatori di modello errati

Gli esempi qui usano la struttura di richiesta della pagina del modello; copia alla lettera dalla console i nomi dei campi e la stringa del modello, anziché a memoria o da frammenti obsoleti. Un errore di battitura nel nome di un campo tende a essere ignorato silenziosamente anziché rifiutato.

Interrogazioni che non terminano mai

Se il tuo ciclo va ripetutamente in timeout, registra ogni valore di stato che osservi. Vedere uno stato inatteso di solito spiega l'empasse — il tuo controllo degli stati terminali potrebbe semplicemente non corrispondere a ciò che restituisce l'API.

Una volta che una singola clip funziona end-to-end, i passi successivi naturali sono elaborare in batch più immagini tramite la stessa funzione helper di invio e interrogazione, aggiungere tentativi con backoff attorno all'invio e scrivere i risultati in uno storage persistente. Puoi trovare i dettagli dell'endpoint, i campi della richiesta e il riferimento dei parametri nella pagina del modello image-to-video seedance-2.5, e adattare il codice sopra alle tue immagini.

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