Blog

Tutoriale

Tutorial API seedance-2.5-flash image-to-video: curl e Python Requests

Un'esercitazione pratica di integrazione per sviluppatori: struttura della richiesta, input del primo/ultimo fotogramma, polling asincrono e risoluzione degli errori

Nov 19, 2026
Immagine di copertina: su uno sfondo marrone scuro, strisce di tessuto color beige e rame di larghezza variabile si intrecciano, formando un motivo geometrico piatto a tessitura diagonale.
In questa pagina

Cosa fa realmente una chiamata image-to-video

Prima di scrivere la prima riga di codice, è utile capire cosa fa l'API dall'altra parte. Una chiamata a seedance-2.5-flash/image-to-video non è una richiesta sincrona che blocca fino alla restituzione del file video. È un flusso di lavoro asincrono in due fasi: prima invii un'attività, poi ne verifichi periodicamente il risultato.

Fase di invio

Invii una richiesta POST con l'immagine di input e le impostazioni di generazione. L'API convalida il corpo della richiesta, accoda l'attività e restituisce immediatamente una risposta contenente un identificatore dell'attività e lo stato iniziale. L'operazione è rapida, di solito istantanea, perché in questa fase non è ancora stato renderizzato alcun pixel. Il tuo compito è acquisire quell'identificatore e conservarlo con cura.

Fase di rendering

La generazione avviene in background. A seconda della durata del clip e delle impostazioni, può richiedere un tempo reale considerevole. Durante questa finestra, non aspettarti che l'URL del video finale sia già disponibile. Dovresti invece interrogare lo stato dell'attività.

Fase del risultato

Prima o poi l'attività raggiunge uno stato terminale: successo, con un artefatto video scaricabile, oppure fallimento, con un errore su cui indagare. Una volta raggiunto lo stato terminale, smetti di eseguire il polling.

Perché questo è importante per il tuo codice

Poiché il modello è asincrono, gli errori di integrazione più comuni sono architetturali, non sintattici: presumere che la prima risposta contenga già il video, attendere a intervalli fissi invece di interrogare il campo di stato e non riuscire a distinguere lo stato transitorio processing da un fallimento definitivo. Tutto in questo tutorial ruota attorno a un ciclo pulito "invio → polling → uscita", quindi tieni presenti queste tre fasi durante la lettura.

Prerequisiti e struttura della richiesta

Cosa serve prima della prima chiamata

  • Credenziali API. La tua chiave API HiAPI, inviata con ogni richiesta. Conservala in una variabile d'ambiente (HIAPI_API_KEY), non nel controllo del codice sorgente: gli esempi seguenti la leggono proprio così.
  • Identificatore del modello. In questo tutorial la stringa è fissa: seedance-2.5-flash/image-to-video. Trattala come una costante opaca; non concatenarla a partire dalle sue parti.
  • Immagine di origine. Un URL pubblico o un riferimento a un'immagine inline supportato. Il modello richiede almeno un'immagine del primo fotogramma.
  • Client HTTP. curl per uno smoke test e requests per tutto ciò che intendi mantenere.

I campi logici del corpo della richiesta

Indipendentemente dal linguaggio, il corpo di una richiesta image-to-video è composto da alcuni gruppi concettuali. Conoscerli separatamente rende il JSON più facile da comprendere:

Modello e input

  • L'identificatore del modello.
  • Un oggetto di input contenente l'immagine del primo fotogramma e, facoltativamente, l'immagine dell'ultimo fotogramma. Il capitolo 4 spiega come interagiscono.

Impostazioni di output

  • Opzioni relative a risoluzione e durata.
  • L'interruttore dell'audio nativo, che determina se il clip generato include una traccia audio. Il capitolo 5 spiega quando attivarlo.

Cosa viene restituito

Un invio riuscito restituisce un oggetto attività. I campi che ti servono davvero sono l'identificatore dell'attività e lo stato corrente. Tutto il resto sono metadati che puoi registrare o ignorare. Il primo giorno non convertire l'intera risposta in un modello tipizzato: registra, esamina, poi restringi.

Prima di procedere, fai un rapido controllo di realtà: se il corpo della tua richiesta contiene campi di cui non sai spiegare il nome in una frase, rimuovili e parti dal minimo. La pagina del modello seedance-2.5-flash/image-to-video è il riferimento per i nomi esatti dei campi accettati.

Inviare un'attività con curl

Parti dalla richiesta minima che può funzionare, poi aggiungi un campo alla volta. Di seguito è riportato l'invio minimo con curl:

curl -X POST "$HIAPI_BASE_URL/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-flash/image-to-video",
    "input": {
      "first_frame_image": "https://your-bucket.example.com/frame-001.jpg"
    }
  }'

Annotazioni campo per campo

  • Authorization — la tua chiave API, come bearer token. Se qui c'è un errore, riceverai un errore di autenticazione prima che venga eseguita qualsiasi convalida, quindi controllalo per primo durante il debug.
  • Content-Type: application/json — obbligatorio; ometterlo produce errori a valle poco chiari.
  • model — l'identificatore fisso del modello. Un errore di battitura qui restituisce un 4xx, non un fallback silenzioso.
  • input.first_frame_image — l'immagine di apertura del clip. Usa un URL effettivamente raggiungibile dalla tua rete; gli URL privati o scaduti falliscono al momento del recupero, non dell'invio.

Leggere la risposta

La risposta è un JSON contenente l'identificatore dell'attività e lo stato. Salva subito l'identificatore: è ciò che interrogherai nel capitolo 7. Un modo rapido per estrarlo nella shell:

# dopo il curl precedente, passa l'output a jq
# {"job_id": "...", "status": "queued"}

Aggiungere l'ultimo fotogramma

Per controllare anche il fotogramma finale, aggiungi una seconda immagine dentro lo stesso oggetto input. Il nome del campo e i formati accettati sono quelli della documentazione del modello: non indovinare grafie alternative; l'API rifiuta le chiavi sconosciute invece di ignorarle.

Una volta che la richiesta minima funziona, hai uno smoke test da rieseguire quando qualcosa va storto. Conservalo in un file; quando il servizio si guasta alle due di notte, vale più di qualsiasi lungo discorso.

Input del primo e dell'ultimo fotogramma

Le immagini di input sono il fattore che più determina il successo di un'attività. Plasmano il contenuto del clip e sono anche la fonte più comune di rifiuto delle richieste.

Cosa controlla il primo fotogramma

L'immagine del primo fotogramma stabilisce lo stato iniziale del clip generato: composizione, soggetto, illuminazione e colore. Il modello genera movimento e continuazione da quel punto di partenza, quindi l'immagine dovrebbe apparire come il fotogramma che vorresti davvero vedere al tempo zero. Un'immagine di origine sfocata, ritagliata o molto compressa non migliorerà magicamente nelle fasi successive.

Cosa controlla l'ultimo fotogramma

Fornire un'immagine dell'ultimo fotogramma fissa lo stato finale. È utile quando il clip deve terminare su un'inquadratura specifica: un fotogramma di prodotto curato, la rivelazione di un logo, un cambio di campo in montaggio. Se lo ometti, il modello sceglie da solo il finale, il che va bene per il lavoro esplorativo ma è imprevedibile in produzione.

Come interagiscono

Quando sono forniti entrambi, il modello interpola tra di essi. Questo ha conseguenze pratiche:

  • La continuità conta più del contrasto. Due fotogrammi della stessa scena con un movimento moderato producono un clip più coerente rispetto a due immagini non correlate. Se i fotogrammi sono molto diversi, aspettati una deformazione visibile, non una transizione plausibile.
  • Le proporzioni devono corrispondere. Proporzioni non corrispondenti tra primo e ultimo fotogramma costringono il modello a un ricomposizione scomoda. Ritaglia entrambi allo stesso rapporto prima di inviare.
  • Le risoluzioni devono essere simili. Inviare un primo fotogramma nitido e un ultimo fotogramma a bassa risoluzione dà al modello segnali contraddittori.

Checklist prima dell'invio

Prima di inviare, verifica che: entrambi gli URL delle immagini siano accessibili pubblicamente e non scadano a metà attività; entrambe siano in un formato supportato; entrambe abbiano lo stesso rapporto d'aspetto; nessuna delle due sia uno screenshot con elementi di interfaccia che non vuoi renderizzare. Una rapida richiesta HEAD su ogni URL intercetta la maggior parte di questi problemi a un costo inferiore rispetto a un'attività di generazione fallita.

Se ricevi comunque un rifiuto, il messaggio di errore di solito punta all'oggetto di input. Convalida prima le immagini in locale (dimensioni, formato e accessibilità), poi sospetta l'API.

Impostazioni di risoluzione e audio nativo

Le impostazioni di output sono il punto in cui gli sviluppatori tendono a configurare troppo. La buona notizia è che i valori predefiniti sono ragionevoli; il rischio è copiare valori dalla documentazione di un altro modello.

Risoluzione

La risoluzione determina le dimensioni del video consegnato e quindi influisce sul tempo di generazione e sul volume dell'output. Due regole pratiche:

  • Scegli in base alla destinazione, non al numero. Un clip per un feed mobile non ha bisogno di essere renderizzato in grande per poi essere ridotto. Scegli la risoluzione minima che soddisfa la piattaforma di destinazione.
  • Preferisci uno dei preset documentati. Passare valori arbitrari o non supportati è una causa comune di rifiuto della richiesta. Se ti serve un fotogramma specifico, ritaglia o ridimensiona dopo la generazione invece di scontrarti con il validatore della richiesta.

Audio nativo

L'interruttore dell'audio nativo determina se il clip generato include una traccia audio prodotta insieme al video. Valuta se ti serve:

  • Attivalo quando il clip è il prodotto finale da guardare con l'audio: contenuti social, brevi promozioni, scene di personaggi in cui l'audio ambientale esalta la sensazione di movimento.
  • Disattivalo quando aggiungerai musica o voce fuori campo nel tuo editor, o quando il clip è un asset intermedio. Generare audio che poi scarterai è lavoro sprecato e rende l'elaborazione a valle più pesante.

Durata

La durata è legata a tutto il resto: i clip più lunghi richiedono più tempo per la generazione e tendono maggiormente alla deriva della coerenza del soggetto. Per la prima integrazione, inizia con clip brevi. Conferma che la pipeline funzioni end-to-end con un clip breve, poi allunga quando ti fidi della pipeline.

Mantieni piccolo l'oggetto delle impostazioni

Se ti ritrovi ad aggiungere impostazioni per correggere problemi di qualità, fermati e controlla se il problema è in realtà nelle immagini di input. La maggior parte degli output deludenti è riconducibile al capitolo 4, non alla mancanza di una manopola. Configura in modo intenzionale, registra l'oggetto esatto delle impostazioni insieme a ogni identificatore di attività e potrai attribuire le variazioni di qualità a modifiche specifiche.

La stessa richiesta in Python

La richiesta curl si trasferisce direttamente in Python. L'obiettivo qui non è un framework, ma un piccolo client leggibile che invia l'attività e restituisce l'identificatore, così che il livello di polling possa restare separato.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "seedance-2.5-flash/image-to-video"


def submit_job(first_frame_url: str, last_frame_url: str | None = None) -> dict:
    payload = {
        "model": MODEL,
        "input": {"first_frame_image": first_frame_url},
    }
    if last_frame_url:
        payload["input"]["last_frame_image"] = last_frame_url

    response = requests.post(
        f"{BASE_URL}/image-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Perché è strutturato così

  • Configurazione tramite variabili d'ambiente. L'URL di base e la chiave restano fuori dal codice, così lo stesso client può essere eseguito in ambienti diversi.
  • timeout=30 sull'invio. L'invio è rapido; un invio che si blocca indica un problema di rete o di autenticazione, e vuoi scoprirlo presto invece di bloccare indefinitamente un worker.
  • raise_for_status() prima dell'analisi. Il corpo di una risposta 4xx è di solito un oggetto di errore JSON, non un'attività. Sollevare un'eccezione per prima cosa mantiene pulito il percorso normale e consente al chiamante di gestire esplicitamente il fallimento.
  • Invio e polling separati. submit_job fa una sola cosa. Il ciclo di polling del capitolo successivo riceve il dizionario restituito e si occupa dell'attesa.

Portarlo in un servizio

In un servizio reale, avvolgi la chiamata in modo che i fallimenti si presentino come eccezioni tipizzate che trasportano codice di stato e corpo della risposta: durante il debug in produzione vorrai il corpo originale della risposta. Registra il corpo della richiesta insieme all'identificatore dell'attività restituito; quando un collega chiederà perché un clip sembra sbagliato, quella riga di log sarà l'intera indagine.

I nomi dei campi sono esattamente quelli dell'esempio curl. Se sai leggere uno, sai leggere l'altro: è proprio questo il motivo per cui vale la pena dedicare cinque minuti a partire da curl.

Eseguire il polling dei risultati senza martellare l'API

Ora l'attività esiste e ha un identificatore. L'approccio ingenuo (dormire sessanta secondi e sperare) fallisce in due modi: spreca tempo quando l'attività è pronta prima, e fallisce del tutto quando l'attività richiede più tempo.

Interroga il campo di stato, non l'orologio

Scrivi un ciclo che interroga lo stato corrente dell'attività e dirama in base a esso:

import time
import requests


def wait_for_job(job_id: str, timeout_s: int = 600) -> dict:
    deadline = time.monotonic() + timeout_s
    delay = 2.0
    while time.monotonic() < deadline:
        r = requests.get(
            f"{BASE_URL}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        r.raise_for_status()
        job = r.json()
        status = job.get("status")

        if status == "succeeded":
            return job
        if status == "failed":
            raise RuntimeError(f"job failed: {job.get('error')}")

        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)  # backoff esponenziale limitato

    raise TimeoutError(f"job {job_id} not terminal after {timeout_s}s")

Le caratteristiche importanti

  • Stati terminali espliciti. Solo succeeded e failed terminano il ciclo. Qualsiasi altro stato è transitorio. Non trattare gli stati sconosciuti come fallimenti: nel tempo emergono nuovi stati intermedi, e il tuo ciclo dovrebbe tollerarli.
  • Backoff limitato. Parti da un valore piccolo (pochi secondi), cresci con un fattore moderato e imponi un limite di circa dieci-quindici secondi. Questo mantiene reattive le attività brevi senza martellare l'endpoint durante lunghi rendering.
  • Scadenza rigida. Limita sempre il tempo totale di attesa. Senza di essa, un'attività bloccata occupa un worker per sempre. Scegli il limite in base al tuo tempo di rendering realistico più lungo, con un margine.
  • Separa i fallimenti dai timeout. Un'attività failed è un errore di generazione da segnalare all'utente. Un timeout è una condizione dell'infrastruttura da ritentare o indagare separatamente. Confondere i due rende l'analisi post-incidente dolorosa.

In un servizio web

Non eseguire questo ciclo nel gestore della richiesta in cui l'utente è in attesa. Invia, memorizza l'identificatore dell'attività, restituisci immediatamente e lascia che un worker in background esegua il polling e consegni il risultato, tramite webhook, coda o aggiornamenti di riga osservati dal frontend. Il ciclo sopra è una preoccupazione del worker, non di HTTP.

Diagnosticare i fallimenti comuni

La maggior parte dei fallimenti rientra in tre categorie. Determina prima la categoria, poi la causa specifica.

Categoria 1: errori di convalida dell'input

Sintomo: un 4xx immediato al momento dell'invio, prima di qualsiasi rendering.

Diagnostica in questo ordine:

  1. L'URL dell'immagine è accessibile? Recuperalo tu stesso dalla stessa rete. Gli URL firmati scaduti e i bucket privati sono la causa principale.
  2. Il formato è supportato? Ricodifica in un formato standard invece di discuterne.
  3. Primo e ultimo fotogramma sono coerenti? Proporzioni non corrispondenti o scene molto diverse si manifestano spesso come problemi di convalida o di qualità.
  4. Hai aggiunto campi con il nome sbagliato? Le chiavi sconosciute di solito vengono rifiutate invece di essere ignorate. Confronta con il riferimento del modello.

Categoria 2: parametri non corrispondenti

Sintomo: la richiesta viene rifiutata a causa di un'impostazione, oppure l'output ignora la tua configurazione.

  • Risoluzione o durata non supportate. Usa solo i valori della documentazione; i numeri arbitrari sono una causa comune di rifiuto.
  • Identificatore del modello scritto male. È una stringa fissa: copiala, non ridigitarla.
  • Annidamento errato. Impostazioni che appartengono al livello superiore messe dentro input, o viceversa, producono errori poco chiari. Usa la struttura della richiesta del capitolo 3 come riferimento.

Categoria 3: timeout del polling e attività fallite

Sintomo: l'attività viene accettata ma non raggiunge mai uno stato terminale di successo.

  • Verifica di interrogare l'identificatore corretto. Gli errori di copia-incolla tra le attività negli script batch sono sorprendentemente comuni.
  • Controlla se lo stato avanza davvero. Registra lo stato a ogni polling per vedere se l'attività progredisce o è bloccata.
  • Distingui un fallimento dell'API da un fallimento della generazione. Se la richiesta di polling stessa fallisce, è un problema di trasporto. Se l'attività riporta failed, leggi il corpo dell'errore: di solito indica l'input che ha causato il problema.
  • Riesegui lo smoke test curl minimo. Se fallisce anche lo smoke test, il problema è nelle credenziali o nel servizio; se riesce, il problema è nel tuo corpo della richiesta.

Approccio generale al debug

Registra tre cose per ogni attività: il corpo esatto della richiesta, l'identificatore dell'attività restituito e lo stato finale con il corpo dell'errore. Con questi tre elementi, quasi ogni incidente diventa una diagnosi di cinque minuti invece di un pomeriggio. In caso di dubbio, riduci la richiesta alla forma minima del capitolo 3 e aggiungi i campi uno alla volta finché non si rompe: l'ultimo campo aggiunto è il colpevole.

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