Blog

Tutoriale

Come chiamare seedance-2.5-flash text-to-video tramite l'API HiAPI (curl e Python)

Una guida pratica per sviluppatori alle richieste funzionanti: endpoint, parametri, gestione dei task asincroni ed esempi eseguibili in curl e Python

Nov 19, 2026
Immagine di copertina: su uno sfondo blu indaco profondo, ampie frecce annidate avanzano a gradi con il bordo anteriore color pesca, componendo una geometria simile a un flusso di segnale.
In questa pagina

Cosa offre seedance-2.5-flash/text-to-video

seedance-2.5-flash/text-to-video è un endpoint di generazione video da testo sull'API HiAPI. Invii un prompt testuale che descrive la scena desiderata e il modello restituisce un video generato. Il contratto è semplice: testo in ingresso, video in uscita.

Poiché la generazione video richiede più tempo di un tipico completamento chat, questo endpoint è asincrono. Una singola chiamata non si blocca in attesa che il video sia pronto, ma crea un task di generazione; recuperi il risultato quando il task raggiunge lo stato terminale. Se hai già integrato API media a esecuzione prolungata, questa forma ti sarà familiare: invia, salva l'identificatore del task, quindi recupera il risultato.

Il lavoro di integrazione da parte tua si divide quindi in tre punti: costruire una richiesta di invio valida, persistere l'ID del task e recuperare in modo affidabile il video completato. Questo tutorial percorre questi tre passi con codice curl e Python eseguibile, per poi illustrare la validazione dei parametri, il compromesso tra polling e callback e i pattern di errore in cui incappa la maggior parte delle prime integrazioni.

Questa guida fa per te se stai costruendo una pipeline che converte prompt in brevi clip video in modo programmatico — strumenti di contenuto, backend prototipali o servizi di generazione interni. Se hai bisogno di una risposta sincrona, o se cerchi la generazione di immagini anziché di video, un altro endpoint è più adatto. Se questo corrisponde al tuo caso d'uso, continua a leggere i prerequisiti.

Prerequisiti e ottenimento della API Key

Prima di inviare la prima richiesta, verifica tre cose.

Account HiAPI e API Key

Tutte le richieste a questo endpoint vengono autenticate con una API Key associata al tuo account HiAPI. Crea la Key nella dashboard dell'account ed evita di inserirla nel controllo del codice sorgente. Gli esempi seguenti la leggono da una variabile d'ambiente, così puoi incollarla direttamente nel terminale o in uno script senza modificare la chiave inline:

export HIAPI_API_KEY="your_api_key_here"

Un client in grado di effettuare richieste HTTPS

Per la parte curl ti serve curl, già presente su macOS e sulla maggior parte delle distribuzioni Linux. Per la parte Python ti servono Python 3 e la libreria requests (pip install requests). Non serve alcun SDK specifico del fornitore: l'endpoint è un semplice HTTPS con corpo JSON, quindi qualsiasi client HTTP va bene, da fetch di Node a httpx di Python.

Un modo per conservare lo stato tra le richieste

Poiché la generazione è asincrona, ti serve un posto dove salvare l'identificatore del task restituito dalla chiamata di invio: una riga di database, una coda di task, un file JSON durante i test. Se prevedi di usare i callback invece del polling, ti serve anche un endpoint HTTPS raggiungibile da HiAPI.

Con la Key e un client funzionante, sei pronto a inviare la richiesta.

Inviare la prima richiesta funzionante con curl

La chiamata di invio è un POST con corpo JSON. Il percorso esatto dell'endpoint e il nome dell'header di autenticazione sono documentati nella pagina del modello: usa quei valori così come sono, senza dedurli da altre API. La struttura della chiamata è la seguente:

curl -X POST "$HIAPI_BASE_URL/v1/models/seedance-2.5-flash/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
  }'

Alcune note sulle varie parti:

  • Metodo e percorso. POST crea un nuovo task di generazione. Il percorso identifica il modello; prima di copiarlo nella tua configurazione, verificalo sulla pagina del modello.
  • Header. L'header Authorization trasporta la tua Key, Content-Type: application/json indica al server come interpretare il corpo della richiesta.
  • Corpo. Come minimo devi inviare una stringa prompt. Il prompt è l'input creativo: tutto ciò che il modello rende deriva da esso, quindi specifica chiaramente soggetto, movimento, illuminazione e comportamento della camera.

Se la richiesta viene accettata, la risposta contiene un oggetto task. Non ottieni immediatamente l'URL del video. Estrai l'identificatore del task dalla risposta e salvalo. Il nome esatto del campo fa parte dello schema di risposta documentato nella pagina del modello; consideralo l'unica fonte di verità e non codificare ipotesi nel client prima di aver visto una risposta reale.

Puoi prima controllare la risposta grezza con curl, poi spostare la stessa chiamata nel codice dopo averne compreso la forma.

Scegliere i parametri: prompt, risoluzione e durata

Solo prompt è strettamente obbligatorio, ma diversi parametri opzionali determinano il risultato e il costo della richiesta. Impostali in modo consapevole, anziché accettare i valori predefiniti alla cieca.

Prompt

Il prompt è il parametro con il maggiore impatto. Scrivilo come un briefing per un operatore di ripresa: soggetto, azione, ambiente, illuminazione e stile di ripresa. "A cyclist weaving through a neon-lit Tokyo street at night, handheld camera, shallow depth of field" fornisce al modello molte più informazioni rispetto a "a city". Mantieni il prompt entro il limite di lunghezza documentato nella pagina del modello.

Risoluzione

Una risoluzione più alta significa più dettaglio e file di output più grandi, e può richiedere tempi di generazione più lunghi. La generazione video viene in genere fatturata in base alla durata dell'output, ma verifica la base di fatturazione attuale ed eventuali livelli di risoluzione nel pannello dei prezzi e nella documentazione del modello, anziché fare supposizioni. Scegli la risoluzione più bassa che soddisfa l'obiettivo di consegna: un successivo upscaling è di solito più economico che generare tutto alla massima qualità.

Durata

La durata controlla quanti secondi di video genera il modello e di solito influisce sia sulla latenza sia sul costo. Le clip più brevi sono migliori per l'iterazione: affina il prompt con durate brevi finché il movimento non è corretto, poi rigenera con la lunghezza finale.

Validazione prima dell'invio

Prima di collegare i valori al codice di produzione, consulta la pagina del modello per gli intervalli consentiti di ogni parametro: durate ammesse, risoluzioni supportate ed eventuali valori enumerati. Poi valida sul client: rifiuta durate fuori intervallo e risoluzioni sconosciute prima che la richiesta lasci il tuo processo. In questo modo trasformi una classe di errori di validazione lato server in fallimenti immediati e a basso costo nei tuoi log.

La stessa regola vale per i nomi dei parametri. Copiali dalla documentazione: un errore di battitura come un underscore in più nel campo della durata viene di solito rifiutato o ignorato silenziosamente, e l'ignoramento silenzioso è il bug più difficile da individuare.

Inviare la stessa richiesta in Python

Di seguito il codice di invio equivalente in Python. Legge la Key dalla variabile d'ambiente, invia il corpo JSON, controlla il codice di stato e restituisce l'identificatore del task dal campo di risposta documentato.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def submit_video(prompt: str, **options) -> str:
    payload = {
        "prompt": prompt,
        **options,  # e.g. resolution="720p", duration=5
    }
    response = requests.post(
        f"{BASE_URL}/v1/models/seedance-2.5-flash/text-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    body = response.json()
    task_id = body["id"]  # confirm the field name on the model page
    return task_id


if __name__ == "__main__":
    task_id = submit_video(
        "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
    )
    print("submitted task:", task_id)

In questo codice ci sono alcune scelte deliberate:

  • Timeout. La chiamata di invio dovrebbe restituire rapidamente, ma un timeout esplicito impedisce che un socket bloccato blocchi il tuo worker.
  • raise_for_status(). Fallisce immediatamente in caso di errore HTTP, invece di interpretare un corpo di risposta di errore come risposta di successo.
  • Opzioni come keyword. Passare **options mantiene leggibile il punto di chiamata e rende molto semplice aggiungere resolution o duration dopo aver confermato i nomi esatti sulla pagina del modello.
  • Restituisce l'ID. Il compito della funzione termina all'invio. Persisti quell'ID in un archivio durevole: la sezione successiva lo userà per recuperare il risultato.

In una pipeline reale, considera submit_video come un passo di un flusso di lavoro guidato da una coda: accodalo, salva l'ID del task restituito insieme al record del tuo task e lascia che un worker separato si occupi del recupero del risultato.

Gestione dei risultati asincroni: polling e callback

Dopo l'invio hai un ID task, ma non ancora un video. Ci sono due modi per colmare questo divario.

Polling

Interroga l'endpoint dello stato del task a intervalli regolari finché il task non raggiunge uno stato terminale, quindi recupera l'URL dell'output dalla risposta di completamento.

import time
import requests


def wait_for_video(task_id: str, timeout_s: int = 600) -> dict:
    deadline = time.time() + timeout_s
    delay = 2.0
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",  # confirm path on the model page
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()
        state = task["status"]
        if state == "completed":
            return task
        if state == "failed":
            raise RuntimeError(task.get("error", "generation failed"))
        time.sleep(delay)
        delay = min(delay * 1.5, 15)  # gentle backoff, capped
    raise TimeoutError(f"task {task_id} did not finish in time")

Tre regole pratiche per il polling:

  • Backoff. Inizia con un ritardo breve e aumentalo gradualmente. Interrogare costantemente ad alta frequenza spreca quota e aumenta il carico senza alcun beneficio.
  • Imposta un limite. Ogni ciclo di polling ha bisogno di una scadenza. La generazione video può richiedere tempo, ma un ciclo illimitato finirà per bloccare il tuo worker all'infinito a causa di un task bloccato.
  • Distingui gli stati. Gestisci esplicitamente failed, così un prompt scadente non venga silenziosamente trattato come un timeout.

Callback

Se registri un URL di callback HTTPS, HiAPI può notificarti al completamento del task, evitando del tutto il polling. Due regole rendono i callback sicuri e affidabili:

  • Verifica prima di fidarti. Tratta il callback come input non autenticato finché non ne hai verificato la firma o l'origine tramite il meccanismo documentato dalla piattaforma.
  • Mantieni l'idempotenza. Un callback può essere consegnato più volte. Usa l'ID del task come chiave dell'handler e rendi le consegne duplicate un'operazione nulla: salva il risultato una sola volta e conferma le consegne duplicate.

Qualunque approccio tu scelga, il recupero del risultato è idempotente: recuperare l'URL del risultato per un task completato dovrebbe restituire lo stesso video, quindi riprovare dopo un errore di rete è sicuro.

Errori comuni e come risolverli

La maggior parte dei fallimenti rientra in poche categorie. Prima di supporre comportamenti non documentati, esamina questa lista punto per punto.

Errori di autenticazione

401 o 403 significano quasi sempre che la Key è mancante, malformata o scaduta. Controlla che l'header Authorization sia presente, che lo schema di autenticazione corrisponda esattamente alla documentazione e che la variabile d'ambiente contenga davvero la Key: una stringa vuota produce un fallimento confuso ma legato all'autenticazione.

Validazione rifiutata

Un 4xx con un messaggio di validazione significa che il server ha rifiutato i tuoi parametri. Rileggi gli intervalli consentiti sulla pagina del modello e verifica i nomi dei parametri carattere per carattere. Se la durata o la risoluzione sono fuori intervallo, la soluzione è la validazione lato client descritta prima: fallisci rapidamente nel tuo codice anziché fare un round trip verso il server.

Task bloccato in uno stato non terminale

Se il polling non vede mai completed o failed, il task potrebbe essere ancora in esecuzione, oppure il tuo ciclo di polling interroga un ID task errato. Registra l'ID che hai inviato e quello che stai interrogando e confrontali. Il tuo ciclo dovrebbe anche imporre una scadenza; quando scatta, esponi l'ID del task anziché riprovare alla cieca.

Il risultato non arriva dopo il callback

Se ti affidi ai callback, verifica che il tuo endpoint sia pubblicamente accessibile via HTTPS, che restituisca rapidamente uno stato di successo anziché eseguire lavoro pesante inline e che le consegne duplicate siano gestite in modo idempotente. Se l'handler del callback va in errore alla seconda consegna dello stesso task, sembrerà che il risultato sia andato perso.

Invio duplicato dello stesso job

Se il tuo worker riprova la chiamata di invio dopo un timeout, potrebbe creare task duplicati. Prima di chiamare l'endpoint, registra una chiave di richiesta lato client o un ID job nel tuo database e controllala prima di riprovare, mantenendo idempotente l'invio dalla tua parte.

Principio generale: quando si verifica un errore, leggi prima il corpo della risposta di errore e la documentazione del modello, poi modifica il codice. Se un valore o un campo non è documentato, evita di supporre che esista: verificalo sulla pagina del modello e adatta la richiesta di conseguenza.

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