Creare video brevi con l'API text-to-video happyhorse-1.1: workflow end-to-end

I video brevi sono un gioco di quantità. TikTok, Reels e Shorts premiano gli account che pubblicano ogni giorno, e il collo di bottiglia produttivo più grande è di solito il B-roll: quelle clip verticali da 3–8 secondi che reggono l'hook, il momento clou del prodotto o il loop soddisfacente. HappyHorse 1.1 text-to-video è particolarmente adatto a questo scenario perché genera audio nativo nella stessa chiamata — nessuna colonna sonora o foley separata — e supporta direttamente l'output verticale 9:16, quindi niente ritaglio in post-produzione.

Questa guida è un workflow end-to-end: pattern di prompt ottimizzati per i video brevi, il ciclo di vita dei task asincroni, uno script di produzione in batch che rende una settimana di video in un'unica esecuzione, e il calcolo dei costi per piattaforma. Ogni clip incorporata qui sotto è stata generata con esattamente la stessa richiesta mostrata accanto — audio attivo, direttamente dall'API.

Prerequisiti. Ti serve una chiave hiapi (Authorization: Bearer sk-…). Se non hai mai chiamato /v1/tasks, consulta prima la documentazione creazione API asincrona o il tutorial curl + Python di happyhorse-1.1 — questo articolo si basa su quel tutorial e si concentra sul workflow per i video brevi.

Perché questo modello è adatto ai video brevi

Tre caratteristiche contano per questo formato:

• Audio nativo. Ambiente, foley ed effetti sonori una tantum vengono generati insieme al video. Per i contenuti "inspiegabilmente soddisfacenti" e il B-roll, il suono è il contenuto — le clip con audio reale superano nettamente le clip AI mute riempite dai creator con musica di repertorio.
• 9:16 di prima classe. aspect_ratio accetta 9:16 (oltre a 16:9, 1:1, 4:5, 21:9, 9:21 e altri), quindi puoi rendere nativamente in verticale invece di ritagliare un master orizzontale perdendo la composizione.
• Intervallo 3–15 secondi. duration accetta qualsiasi numero intero da 3 a 15 — esattamente l'intervallo dei video brevi. L'hook è da 3 secondi, il momento clou del prodotto da 4–6 secondi, una micro-storia completa sta in 12–15 secondi.

Lo schema di input è volutamente compatto. Solo prompt è obbligatorio; i parametri utili sono:

Campo	Valore	Default per video brevi
prompt	stringa (obbligatorio)	vedi i pattern sotto
aspect_ratio	16:9, 9:16, 3:4, 4:3, 4:5, 5:4, 1:1, 9:21, 21:9	9:16
resolution	720p, 1080p	720p per le bozze, 1080p per i post principali
duration	intero 3–15 (secondi)	3–5

Ci sono due cose che non accetta, così non sprechi una richiesta per scoprirlo: nessun interruttore audio (l'audio è sempre attivo) e nessun seed. Inviare uno dei due restituisce un errore di validazione 400.

Tre clip reali, tre tipi di video brevi

Questi sono i tre formati che dominano i feed dei video brevi, ognuno generato in una singola chiamata API. I prompt seguono uno schema ripetibile che puoi adattare: etichetta del formato → soggetto e azione → composizione → luce → indicazione audio.

1. B-roll lifestyle (il classico del caffè)

{
  "model": "happyhorse-1.1/text-to-video",
  "input": {
    "prompt": "Test video breve verticale: un barista crea latte art in un caffè luminoso, composizione verticale in stile smartphone, audio naturale del latte montato e delle chiacchiere del caffè.",
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }
}

Nota l'indicazione audio alla fine del prompt ("latte montato e chiacchiere del caffè"). Dire esplicitamente quali suoni vuoi è il trucco con più leva quando usi questo modello — senza prompt genera comunque l'audio, ma descriverlo produce una traccia ambientale utilizzabile.

2. Teaser di lancio prodotto

{
  "model": "happyhorse-1.1/text-to-video",
  "input": {
    "prompt": "Teaser di lancio prodotto, verticale 9:16: una scarpa da running retrò massiccia color crema e arancio bruciato ruota lentamente su un piatto girevole nero opaco, una luce di contorno dura ne delinea la silhouette, sottili particelle di polvere fluttuano nel fascio di luce, sfondo da studio scuro, ampio spazio vuoto sopra per sovrapporre un titolo. Impatto forte, cinematografico. Audio nativo: un basso profondo che ronza e un morbido sibilo quando la scarpa completa la rotazione.",
    "duration": 3,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }
}

Qui ci sono due trucchi specifici per i video brevi. Primo, "ampio spazio vuoto sopra per sovrapporre un titolo" — metterai del testo su questa clip nell'editor, quindi chiedi al modello di lasciare spazio negativo invece di far competere i tuoi sottotitoli con l'inquadratura. Secondo, l'audio è progettato, non ambientale: un basso che ronza più un sibilo sincronizzato con il ritmo dell'azione, esattamente ciò che usano i teaser di prodotto.

3. Loop macro inspiegabilmente soddisfacente

{
  "model": "happyhorse-1.1/text-to-video",
  "input": {
    "prompt": "Macro inspiegabilmente soddisfacente, verticale 9:16: una spatola affilata taglia nettamente un blocco di sabbia cinetica color menta pallido su un tavolo bianco, la superficie tagliata si sbriciola al rallentatore, i granelli si riversano, luce da studio morbida e uniforme, primo piano estremo che riempie l'inquadratura. Audio nativo: lo scricchiolio secco e granuloso del taglio, senza musica.",
    "duration": 3,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }
}

"Senza musica" è importante: per i contenuti in stile ASMR il modello dovrebbe spendere il suo budget audio nel foley (lo scricchiolio dei granelli), e dirlo esplicitamente gli impedisce di aggiungere una colonna sonora generica.

Pattern di prompt adatti ai video brevi

Estratti dalle clip sopra e dalle esecuzioni che ci stanno dietro:

1. Inizia con il formato. Apri con "video breve verticale", "teaser di lancio prodotto, verticale 9:16", "macro inspiegabilmente soddisfacente". Il modello compone per il formato che specifichi — una composizione in stile smartphone non ha lo stesso aspetto di un'inquadratura cinematografica widescreen.
2. Un soggetto, un'azione. 3–5 secondi sono un battito. "Il barista crea latte art" funziona; raccontare una storia in tre atti in 4 secondi ti dà solo una macchia confusa. Se ti servono più battiti, genera più clip e montale insieme — è così che si montano i veri video brevi.
3. Scrivi l'audio in una frase. Ogni prompt termina con Audio nativo: <1–3 suoni che vuoi>. Il rumore di fondo ambientale ("chiacchiere del caffè"), il foley ("scricchiolio secco e granuloso") o un effetto sonoro progettato una tantum ("un basso profondo che ronza e un morbido sibilo") funzionano tutti.
4. Riserva spazio per le sovrapposizioni. Se la clip deve ospitare sottotitoli o titoli, chiedi "spazio vuoto sopra" o "spazio negativo pulito nel terzo superiore". Costa meno che ricomporre in post-produzione.
5. Termina in uno stato ciclico. I feed vanno in loop automaticamente. I prompt che finiscono dove iniziano ("la scarpa completa la rotazione") si ripetono in modo pulito e accumulano silenziosamente visualizzazioni ripetute.

Workflow asincrono: invia, interroga, scarica

Ogni generazione è un task asincrono: POST /v1/tasks restituisce immediatamente un taskId, tu interroghi GET /v1/tasks/:id finché status non è success, poi scarichi output[0].url. Una clip da 4 secondi a 720p di solito si renderizza in circa 1–3 minuti.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.1/text-to-video",
    "input": {
      "prompt": "Test video breve verticale: un barista crea latte art in un caffè luminoso, composizione verticale in stile smartphone, audio naturale del latte montato e delle chiacchiere del caffè.",
      "duration": 4,
      "resolution": "720p",
      "aspect_ratio": "9:16"
    }
  }'
# → {"code":200,"data":{"taskId":"tk-hiapi-…"},"message":"success"}

Una regola operativa che fa cadere molti nella trappola: gli URL di output scadono. L'output[0].url nella risposta ha un expireAt — scarica l'mp4 immediatamente dopo il successo del task e mettilo nel tuo storage. Non inserire URL hotlink in un CMS o in uno strumento di schedulazione.

Produzione in batch: una settimana di clip in un'unica esecuzione

L'API dei task dà il meglio di sé quando invii in parallelo. Poiché la creazione ritorna immediatamente, lo schema corretto è invia prima tutti i task, poi interroga tutti i task — cinque clip si renderizzano in circa il tempo reale di una sola clip.

import os, time, requests

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

BATCH = [
    ("mon-coffee",  "Video breve verticale: caffè pour-over che sbuffa al rallentatore, vapore che si arriccia, calda luce mattutina. Audio nativo: flusso d'acqua, morbido ambiente del caffè.", 4),
    ("tue-sneaker", "Teaser di lancio prodotto, verticale 9:16: una scarpa da running neon schizza in acqua bassa, gocce sospese a mezz'aria, sfondo scuro. Audio nativo: un tonfo profondo.", 3),
    ("wed-sand",    "Macro inspiegabilmente soddisfacente, verticale 9:16: un blocco di sabbia cinetica color lavanda tagliato da un filo sottile, la superficie tagliata si sbriciola. Audio nativo: scricchiolio secco e granuloso, senza musica.", 3),
    ("thu-city",    "Video breve verticale: strada al neon piovosa di notte, ombrelli che passano, riflessi che ondeggiano. Audio nativo: pioggia e traffico in lontananza.", 5),
    ("fri-dessert", "Macro video breve verticale: un cucchiaio rompe la crosta caramellata di una crème brûlée, la crema sottostante cede. Audio nativo: uno scricchiolio nitido, poi silenzio.", 3),
]

def submit(prompt, duration):
    r = requests.post(API, headers=HEADERS, json={
        "model": "happyhorse-1.1/text-to-video",
        "input": {"prompt": prompt, "duration": duration,
                  "resolution": "720p", "aspect_ratio": "9:16"},
    }, timeout=60)
    return r.json()["data"]["taskId"]

# 1) invia prima tutti i task
tasks = {key: submit(p, d) for key, p, d in BATCH}

# 2) interroga finché tutti non sono in stato terminale
while tasks:
    time.sleep(10)
    for key, tid in list(tasks.items()):
        t = requests.get(f"{API}/{tid}", headers=HEADERS, timeout=30).json()["data"]
        if t["status"] == "success":
            url = t["output"][0]["url"]          # scade — scarica subito
            open(f"{key}.mp4", "wb").write(requests.get(url, timeout=180).content)
            print(f"done: {key}.mp4")
            del tasks[key]
        elif t["status"] == "fail":
            print(f"FAILED {key}: {t.get('error')}")
            del tasks[key]

Note di produzione per eseguire script di questa forma su larga scala:

• Reinvia in caso di errore, non interrogare di nuovo. I task falliti sono in stato terminale; invia un nuovo task con lo stesso input (se fallisce due volte per motivi di contenuto, ogni tanto riscrivi il prompt).
• Mantieni un manifest. Scrivi {key, prompt, taskId, local_path} su un file JSON strada facendo, e al riavvio salta le chiavi il cui mp4 esiste già. I job in batch vengono interrotti; la ripartibilità è gratuita se la pianifichi in anticipo.
• Attenzione ai limiti di concorrenza. Se devi inviare decine di task, distanzia gli invii di uno o due secondi invece di lanciarne 50 nello stesso istante.

Quanto costa

La fatturazione è sui secondi di video prodotto (pagina dei prezzi): 720p a $0.16/secondo, 1080p a $0.21/secondo, indipendentemente dal rapporto d'aspetto. La durata è l'unica leva di costo, il che rende i video brevi il posto più economico per usare questo modello:

Clip	Specifiche	Costo
Hook / loop soddisfacente	3 sec · 720p	$0.48
Battito B-roll standard	4 sec · 720p	$0.64
Teaser di prodotto	5 sec · 720p	$0.80
Post principale	5 sec · 1080p	$1.05
Pubblicazione giornaliera, 30 × 4 sec di bozza al mese	720p	~$19.20

Un flusso pratico a due livelli: itera i prompt a 3 sec/720p (circa mezzo dollaro per tentativo), e ri-renderizza a 1080p solo i vincitori per la pubblicazione. I prompt si trasferiscono in modo pulito tra le risoluzioni, quindi non stai rifacendo il lavoro creativo — paghi i pixel solo dopo aver capito che la clip vale la pena.

Dall'output API al post pubblicato

Il modello ti consegna una clip verticale finita con audio; il resto è confezionamento:

• Durata per piattaforma: le clip da 3–5 secondi funzionano bene come loop su TikTok e Reels; per gli Shorts, concatenare due o tre battiti in 10–15 secondi spesso trattiene il pubblico più a lungo. Con duration fino a 15 secondi puoi coprire una micro-storia completa in una sola chiamata, se non vuoi montare.
• Sovrapposizioni di testo: aggiungi i sottotitoli nell'editor (CapCut, Premiere, ffmpeg drawtext). È qui che conta il trucco del prompt "lascia spazio vuoto".
• Mantieni l'audio nativo come livello di base, anche se aggiungi musica — un foley reale sotto un letto musicale comunica più valore produttivo della sola musica.
• Serie coerenti: i video brevi premiano la ripetizione di formato. Fissa lo scheletro del prompt (composizione, luce, stile audio) e cambia solo il soggetto — i tre modelli di tipo sopra sono progettati proprio per essere riutilizzati.

Se la tua serie ruota attorno ad asset di brand — foto reali del prodotto, mascotte, volti — combina questo workflow con happyhorse-1.1 image-to-video: genera o scatta una volta il keyframe, poi guida il movimento da lì, così il soggetto resta identico in ogni post.

Inizia a renderizzare

Il percorso più rapido: ottieni una chiave, copia la richiesta del barista da questa pagina, e in pochi minuti avrai la tua prima clip verticale con audio. La pagina del modello happyhorse-1.1 text-to-video ha il riferimento live dei parametri e i prezzi, la guida rapida copre l'autenticazione se è la tua prima chiamata a hiapi. Renderizza tre bozze, tieni la migliore, e hai il post di domani per meno del prezzo di un caffè.