Creare video brevi con seedance-2.0-mini: workflow end-to-end con l'API hiapi

TL;DR

• Di cosa si tratta: un workflow end-to-end per realizzare video brevi verticali in stile TikTok/Reels con seedance-2.0-mini tramite l'API hiapi — dalla prima chiamata curl fino allo script che renderizza in batch il contenuto di un'intera settimana. Le clip dimostrative di questa pagina sono state generate esattamente con le richieste mostrate qui sotto.
• Perché scegliere questo modello per i video brevi: supporto nativo per 9:16, audio sincronizzato integrato (nessun post-processing audio separato necessario), durata flessibile tra 4 e 15 secondi, e una bozza in 480p costa solo $0.0272 al secondo — una bozza verticale di 4 secondi viene circa $0.11 (prezzi).
• Fatti API verificati: prompt, duration (intero tra 4 e 15) e resolution (480p | 720p) sono obbligatori; aspect_ratio accetta 1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive. Per image-to-video si usano first_frame_url / last_frame_url. Lo schema è rigoroso — campi sconosciuti come seed vengono rifiutati con un 400.
• Workflow: genera in 480p per iterare sul prompt, ri-renderizza in 720p le clip che tieni, e invia i task in parallelo in batch — la coda asincrona di /v1/tasks gestisce il fan-out al posto tuo.

Perché seedance-2.0-mini è adatto al ciclo dei video brevi

La produzione di video brevi è un lavoro quantitativo: abbozzi molte clip, ne tieni poche, pubblichi ogni giorno. Questo workflow richiede che un'API video faccia tre cose — iterazione a basso costo, output verticale e audio — e seedance-2.0-mini le soddisfa tutte e tre:

• Il costo di una singola bozza è abbastanza basso da poter iterare più volte. In 480p il modello costa $0.0272 per secondo di output, quindi una bozza di 4 secondi viene circa $0.11, e persino una clip completa di 15 secondi costa solo circa $0.41. Il livello 720p è $0.0586/secondo. (Prezzi verificati sulla pagina dei prezzi in tempo reale; i video sono fatturati al secondo, quindi duration è la tua leva sui costi.)
• 9:16 nativo. Renderizza direttamente in verticale, invece di ritagliare una clip orizzontale perdendo la composizione.
• Audio sincronizzato nativo. L'MP4 di output include una traccia AAC generata insieme alla scena — ambienza, foley, rumore di fondo della stanza. Per i contenuti da feed che si riproducono automaticamente con l'audio, questo elimina un intero passaggio di montaggio.

Se vuoi un modello più grande della stessa famiglia per i contenuti hero, lo stesso workflow vale per seedance-2-0 — cambia solo il livello di prezzo.

Configurazione

Ti serve solo una chiave API hiapi, nient'altro — nessun SDK. Conserva la chiave in una variabile d'ambiente:

export HIAPI_API_KEY="sk-..."

Tutti i modelli video su hiapi funzionano tramite un endpoint task asincrono unificato: POST https://api.hiapi.ai/v1/tasks restituisce immediatamente un taskId, poi si esegue il polling di GET /v1/tasks/{taskId} fino al completamento. Dettagli nella documentazione.

La tua prima clip verticale (T2V)

La richiesta minima valida richiede prompt, duration e resolution. Per i video brevi aggiungi aspect_ratio: "9:16":

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini",
    "input": {
      "prompt": "Video breve verticale. Su un bancone di caffè baciato dal sole, un fresco matcha latte viene versato lentamente in un bicchiere di vetro trasparente, un vortice verde sboccia tra il latte, luce morbida dalla finestra, profondità di campo ridotta. Audio nativo: dolce ambienza del caffè, suono del liquido versato. Nitido, invitante, fotorealistico.",
      "duration": 4,
      "resolution": "480p",
      "aspect_ratio": "9:16"
    }
  }'

La risposta arriva immediatamente:

{"code": 200, "data": {"taskId": "tk-hiapi-01KWTTFDPHSDWZ0FP1QAS5J79Q"}, "message": "success"}

Esegui il polling del task finché status non è success, poi scarica subito output[0].url — gli URL di output sono temporanei e scadono. Ecco la clip effettiva generata da quella richiesta (4 secondi, 480p, 9:16, con audio nativo di versamento e ambienza — togli il muto per ascoltare):

Due note pratiche da questo render: l'output verticale "480p" misura in realtà 496×864 pixel, e l'audio arriva nell'MP4 come traccia AAC standard — nessun file separato da comporre.

Schemi di input, verificati sull'API in tempo reale

Lo schema è rigoroso. Di seguito le risposte di validazione reali, riprodotte alla lettera, così puoi riconoscerle nei log:

Campo	Tipo	Obbligatorio	Valori
prompt	string	✅ (lunghezza minima 3)	la descrizione della tua inquadratura
duration	integer	✅	4–15 (secondi)
resolution	string	✅	480p, 720p
aspect_ratio	string	opzionale	1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive
first_frame_url	string	opzionale	URL immagine del frame iniziale per I2V
last_frame_url	string	opzionale	URL immagine per controllare il frame finale
image_input	array	opzionale	riferimento immagine multimodale
reference_video_urls	array	opzionale	video di riferimento per stile/movimento (tariffa al secondo più bassa)

Se ometti un campo obbligatorio, il task viene rifiutato prima della creazione (senza addebito):

{"code": 400, "error_code": "INVALID_REQUEST", "message": "invalid input: resolution: missing required field \"resolution\"; duration: missing required field \"duration\""}

I valori fuori intervallo indicano il limite esatto — duration: maximum: got 16, want 15 — e i campi sconosciuti vengono rifiutati anziché ignorati:

{"code": 400, "error_code": "INVALID_REQUEST", "message": "invalid input: <root>: additional properties 'seed' not allowed"}

Vale la pena interiorizzare quest'ultimo comportamento: se riusi la struttura di richiesta di altri modelli (un seed, un size, un flag audio), seedance-2.0-mini restituisce un 400 anziché scartare silenziosamente il campo.

Una funzione Python riutilizzabile

Tutto ciò che serve in produzione sta in circa 40 righe — invio, polling, download:

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def submit(prompt: str, duration: int = 4, resolution: str = "480p",
           aspect_ratio: str = "9:16", **extra) -> str:
    r = requests.post(API, headers=HEADERS, json={
        "model": "seedance-2.0-mini",
        "input": {"prompt": prompt, "duration": duration,
                  "resolution": resolution, "aspect_ratio": aspect_ratio, **extra},
    }, timeout=60)
    data = r.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"submit failed: {data}")
    return task_id

def wait(task_id: str, timeout_s: int = 900) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(8)
    raise TimeoutError(task_id)

def make_clip(prompt: str, out_path: str, **kw):
    task = wait(submit(prompt, **kw))
    url = task["output"][0]["url"]          # URL temporaneo — scarica subito
    with open(out_path, "wb") as f:
        f.write(requests.get(url, timeout=120).content)

Una clip di 4 secondi in 480p di solito si completa in pochi minuti; nelle ore di punta concedi fino a circa 10 minuti prima di dichiarare un timeout.

Image-to-video: bloccare il primo frame

Per i video brevi orientati al prodotto, la deriva del prompt è il nemico — vuoi il tuo prodotto nell'inquadratura, non l'immaginazione che ne ha il modello. La soluzione è l'I2V con first_frame_url: genera (o scatta) un'immagine fissa, poi animarla. Un'immagine di riferimento verticale come questa, realizzata con gpt-image-2 tramite lo stesso endpoint /v1/tasks, è perfetta come frame iniziale:

La richiesta richiede solo un campo in più:

task_id = submit(
    "L'acqua calda viene versata lentamente in cerchio dall'alto, il dripper inizia a sprigionare vapore, "
    "gocce cadono nella caraffa di vetro sottostante, la luce del sole illumina il vapore. Lento e delicato push-in. "
    "Audio nativo: leggero scroscio d'acqua, quieto rumore di fondo di una stanza al mattino.",
    duration=4, resolution="480p", aspect_ratio="9:16",
    first_frame_url="https://your-cdn.example/pourover-ref.jpg",
)

Ecco il risultato reale dell'animazione del primo frame — un'immagine fissa dalla nostra libreria di ricette seedance-2.0-mini e la clip che ha generato, stesso modello e stessa struttura di richiesta (in questo caso 16:9):

Composizione, tonalità e soggetto restano bloccati sulla tua immagine fissa; il prompt deve solo descrivere il movimento. Se ti serve che la clip termini su un frame specifico, c'è anche last_frame_url — utile per loop che tornano su una scheda prodotto.

Produrre in batch il contenuto di una settimana

Poiché /v1/tasks è asincrono, produrre in batch significa: invia tutti i task, poi esegui il polling. Nessuna coda lato client.

briefs = [
    ("mon-hook",  "Clip verticale. Espresso in estrazione lenta, ..."),
    ("tue-loop",  "Clip verticale in loop continuo. Vapore che si arriccia dalla tazza, ..."),
    ("wed-recipe","Clip verticale. Sequenza dall'alto di un pour-over, ..."),
    # ... una per ogni giorno di pubblicazione
]

tasks = {name: submit(p, duration=6) for name, p in briefs}   # fan-out
for name, tid in tasks.items():                                 # raccolta
    make = wait(tid)
    url = make["output"][0]["url"]
    open(f"{name}.mp4", "wb").write(requests.get(url, timeout=120).content)

Il calcolo dei costi resta prevedibile perché si fattura per secondo di output:

Scenario	Specifiche	Costo
1 iterazione di bozza	4 secondi · 480p	circa $0.11
1 clip pronta da pubblicare	6 secondi · 480p	circa $0.16
7 clip (una settimana, una al giorno)	7 × 6 secondi · 480p	circa $1.14
Ri-render del contenuto hero	6 secondi · 720p	circa $0.35

Un workflow che funziona: abbozza ogni idea in 480p, tieni i vincitori e ri-renderizza solo quelli in 720p. Per altre leve (livelli di risoluzione, taglio della durata, pianificazione batch), consulta la nostra guida su come controllare i costi delle API di generazione immagini e video.

Tecniche di prompting per il feed

Cosa ha funzionato nei nostri render di test, ottimizzato per i video brevi:

• Scrivi "verticale" e componi per il verticale. Inizia con "Video breve verticale." e aggiungi aspect_ratio: "9:16", centrando il soggetto nell'inquadratura alta invece di comporre una scena orizzontale che poi verrà ritagliata.
• Metti l'hook nel primo secondo. Il feed decide nel primo secondo — fai in modo che l'azione iniziale sia già la ricompensa (il versamento già in corso, il vapore già che sale), non un lento establishing shot.
• Scrivi il copione audio. Una frase come "Audio nativo: ..." con 2–3 suoni specifici (versamento di liquido, ambienza del caffè) modella in modo affidabile la traccia. Senza prompt ottieni solo un rumore di fondo generico.
• Per clip in loop, minimizza la differenza tra inizio e fine. Particelle alla deriva, aloni pulsanti, vapore che si arriccia — descrivi un movimento stazionario, e i frame iniziale e finale saranno abbastanza vicini per il loop.

Conclusione

Produrre video brevi con seedance-2.0-mini si riduce a un endpoint asincrono, tre campi obbligatori e una fatturazione al secondo che rende economica l'iterazione: abbozza clip verticali in 480p a circa venticinque centesimi l'una, blocca le inquadrature di prodotto con first_frame_url, invia in batch il tuo calendario editoriale e ri-renderizza in 720p quelle che tieni. Ottieni una chiave API, poi parti dalla richiesta curl di 4 secondi qui sopra — la pagina del modello seedance-2.0-mini ha il riferimento dei parametri e i prezzi in tempo reale per continuare da lì.