Guida alla produzione di video brevi con seedance-2-0: ricette pratiche per l'API hiapi

Panoramica rapida

• Cos'è: una ricetta eseguibile e riproducibile che ti insegna a creare video brevi verticali (TikTok / Reels / Shorts) con seedance-2.0 su hiapi. Il breve video incorporato qui sotto è stato generato esattamente con il prompt stampato sopra di esso: nessuna demo presa in prestito da altri.
• Due modalità, un solo modello: seedance-2.0 supporta nello stesso endpoint sia la generazione di video da testo sia la generazione di video da immagine: puoi partire da un prompt oppure animare un'immagine statica esistente.
• Fatti sull'API (verificati sulla piattaforma): seedance-2.0 gira su un endpoint a task asincrono (/v1/tasks). L'oggetto input richiede prompt, aspect_ratio (obbligatorio: usa 9:16 per i video brevi), resolution (480p / 720p / 1080p) e duration in secondi. Il risultato viene restituito come MP4 in output[0].url.
• Prezzi (per secondo di output): 480p a $0.136/secondo, 720p a $0.293/secondo, 1080p a $0.729/secondo. Un video di 4 secondi a 480p costa $0.54. Per i prezzi in tempo reale consulta la pagina dei prezzi.
• Come si esegue: invia una POST all'API a task, esegui il polling finché lo stato non è success, poi scarica l'MP4 da output[0].url: quell'URL è temporaneo e scade, quindi salva subito i dati binari. Gli script completi copiabili (entrambe le modalità + ciclo batch) sono in fondo all'articolo.

Perché scegliere seedance-2.0 per i video brevi

Le piattaforme di video brevi hanno una grammatica fissa: verticale 9:16, pochi secondi di durata, un chiaro battito d'azione. È esattamente la forma per cui seedance-2.0 è nato. Basta un flag di proporzioni per ottenere un movimento cinematografico, quindi non devi lottare con il modello per avere il formato verticale: chiedi 9:16 e lo comporrà in quel formato.

L'altro motivo è il flusso di lavoro: ogni video breve è un singolo task asincrono. Invii il job, esegui il polling dell'ID del task e recuperi un MP4 completato. Nessun socket in streaming da sorvegliare, nessun timeout di 100 secondi da evitare: è esattamente lo stesso protocollo a task usato da tutti gli altri modelli generativi di hiapi, quindi se hai già chiamato i modelli di immagini, qui il flusso di controllo è identico.

Modalità 1: testo in video

È la via più rapida per ottenere un video breve: descrivi l'inquadratura, scegli formato e durata, invia.

Il prompt qui sotto è proprio quello che ho eseguito davvero. Scrivi come un regista: soggetto, illuminazione, movimento di camera, non come un elenco di parole chiave.

Prompt: Un barista estrae un caffè espresso in una caffetteria illuminata dal sole, primo piano sulla crema che si avvolge nella tazza, luce calda del mattino, vapore delicato che sale, profondità di campo ridotta, carrello fluido a mano che avanza.

Impostazioni: aspect_ratio: 9:16, resolution: 480p, duration: 4

Il video è in formato nativo 9:16 e può essere inserito direttamente nella timeline di Reels/Shorts. Il rendering ha richiesto circa due minuti, con una stima di circa $0.54 alla tariffa attuale a 480p: abbastanza economico da generare alcune varianti e tenere la migliore.

Il corpo della richiesta è minuscolo. Un campo che spesso viene dimenticato è aspect_ratio: è obbligatorio e, se manca, l'API rifiuta il task con missing required field "aspect_ratio".

import os, json, requests

TOKEN = os.environ["HIAPI_TOKEN"]
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

payload = {
    "model": "seedance-2.0",
    "input": {
        "prompt": (
            "A barista pulls a shot of espresso in a sunlit cafe, close-up on the "
            "crema swirling into the cup, warm morning light, gentle steam rising, "
            "shallow depth of field, smooth handheld camera push-in."
        ),
        "aspect_ratio": "9:16",   # required — 9:16 for short-form
        "resolution": "480p",     # 480p | 720p | 1080p
        "duration": 4,            # seconds
    },
}

r = requests.post(BASE, headers=HEADERS, data=json.dumps(payload), timeout=60)
task_id = r.json()["data"]["taskId"]
print("submitted:", task_id)

Modalità 2: immagine in video

La seconda modalità anima un'immagine statica che fornisci tu, invece di creare una scena da zero. È esattamente ciò che serve per il lavoro di brand: scatta (o genera) un'immagine pulita del prodotto, poi lascia che seedance-2.0 aggiunga il battito d'azione, così composizione e prodotto restano conformi al brand.

La forma della chiamata è la stessa di quella a task: mantieni aspect_ratio, resolution e duration, mentre il prompt ora descrive il movimento da applicare all'immagine ("lento avvicinamento", "la modella si gira verso la camera", "il vapore inizia a salire") e non l'intera scena. Abbinalo a un'immagine statica proveniente dai modelli di immagini e avrai una pipeline in due passaggi: genera il key visual, poi fallo muovere.

Suggerimento: per i video brevi da immagine, mantienili corti (4 secondi) e rendi il movimento sottile. I video brevi premiano un battito pulito, non un'inquadratura affollata.

Calcolo dei costi per batch di video brevi

Poiché la fatturazione è per secondo di output, il tuo costo è facilmente prevedibile: scegli la risoluzione e moltiplica per la durata del video:

Risoluzione	Prezzo / secondo	Video da 4 secondi	Video da 8 secondi
480p	$0.136	$0.54	$1.09
720p	$0.293	$1.17	$2.34
1080p	$0.729	$2.92	$5.83

Per iterare più volte sull'hook, abbozza in 480p: costa un quarto del 720p ed è sufficiente per valutare composizione e movimento. Riproduci in 720p o 1080p solo la versione vincente per la pubblicazione finale. Per le tariffe attuali dei vari modelli consulta la pagina dei prezzi.

Script completo: invio, polling, download

Questa è la versione end-to-end: invia un job di testo in video, esegui il polling del task fino al completamento, poi salva l'MP4. Il passaggio di download è importante: output[0].url è un link temporaneo che scade, quindi scrivi subito i dati binari su disco appena il task ha successo.

import os, json, time, requests

TOKEN = os.environ["HIAPI_TOKEN"]
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}


def submit(prompt, aspect_ratio="9:16", resolution="480p", duration=4):
    payload = {
        "model": "seedance-2.0",
        "input": {
            "prompt": prompt,
            "aspect_ratio": aspect_ratio,  # required
            "resolution": resolution,      # 480p | 720p | 1080p
            "duration": duration,          # seconds
        },
    }
    r = requests.post(BASE, headers=HEADERS, data=json.dumps(payload), timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]


def wait(task_id, timeout_s=600, poll=8):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        data = r.json().get("data", {})
        status = data.get("status")
        if status == "success":
            return data
        if status == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(poll)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


def download(task, path):
    out = task["output"][0]
    assert out["type"] == "video", f"unexpected output type: {out['type']}"
    # output[0].url is temporary (see expireAt) — save immediately.
    resp = requests.get(out["url"], timeout=120)
    resp.raise_for_status()
    with open(path, "wb") as f:
        f.write(resp.content)
    return path


if __name__ == "__main__":
    prompt = (
        "A barista pulls a shot of espresso in a sunlit cafe, close-up on the crema "
        "swirling into the cup, warm morning light, gentle steam rising, shallow "
        "depth of field, smooth handheld camera push-in."
    )
    tid = submit(prompt, aspect_ratio="9:16", resolution="480p", duration=4)
    print("submitted:", tid)
    task = wait(tid)
    print("saved:", download(task, "espresso_9x16.mp4"))

Per trasformare un hook in un intero batch, avvolgi submit / wait / download in un ciclo che scorre i prompt:

HOOKS = {
    "espresso":  "A barista pulls a shot of espresso in a sunlit cafe, close-up on the crema, gentle steam, handheld push-in.",
    "matcha":    "A whisk froths bright green matcha in a ceramic bowl, top-down light, slow spiral motion, calm morning mood.",
    "pour-over": "Hot water spirals over fresh coffee grounds in a dripper, close macro, steam rising, warm backlight.",
}

for name, prompt in HOOKS.items():
    tid = submit(prompt, aspect_ratio="9:16", resolution="480p", duration=4)
    task = wait(tid)
    download(task, f"{name}_9x16.mp4")
    print("done:", name)

Abbozza questo batch a 480p, scegli i vincitori, riproduci questi ultimi a 1080p e pubblica. Questo è l'intero ciclo dei video brevi su un solo modello e un solo endpoint.

Punti chiave

• seedance-2.0 è un singolo task asincrono su /v1/tasks che restituisce un MP4: lo stesso flusso di controllo dei modelli di immagini di hiapi.
• aspect_ratio è obbligatorio; per TikTok / Reels / Shorts usa 9:16.
• La fatturazione è per secondo di output: 480p $0.136/secondo, 720p $0.293/secondo, 1080p $0.729/secondo. Quindi abbozza a basso costo in 480p e finalizza ad alta risoluzione solo i vincitori.
• L'URL di output è temporaneo: appena il task riporta success, scarica subito i dati binari.
• La stessa chiamata fa sia testo in video sia immagine in video; abbina immagine in video a un'immagine statica generata per ottenere un movimento del prodotto conforme al brand.