Come usare l'API Creatify Boreal: generare video da testo, immagini e audio

creatify-boreal è un modello video su hiapi che restituisce una clip finita con voce e suono già mixati. Un unico id modello copre tre punti di partenza: solo prompt, prompt più immagine di riferimento, oppure prompt più il tuo audio di voiceover. Questa guida mostra la richiesta, il ciclo di polling e cosa ho ottenuto eseguendo davvero una generazione reale.

Devi ottenere una chiave API dalla dashboard di hiapi. Tutte le chiamate passano dall'endpoint unificato per le attività POST /v1/tasks.

Campi di input

Questi campi sono stati verificati rispetto alla pagina del modello live e inviando valori volutamente non validi a /v1/tasks; i valori non validi restituiscono 400 e non vengono addebitati.

Campo	Obbligatorio	Valori accettati
prompt	Sì	Testo, massimo 5000 caratteri
image_url	No	JPG/PNG/WebP, 10 MB; definisce soggetto e composizione
audio_url	No	MP3/WAV/M4A, 15 MB; vengono usati solo i primi duration secondi
negative_prompt	No	Massimo 2000 caratteri
resolution	No	720p, 1080p, 2k
aspect_ratio	No	auto, 16:9, 9:16, 1:1, 4:3, 3:4
duration	No	Secondi interi, da 1 a 20

Queste tre modalità non sono id modello separati. Per la generazione di video da testo ometti image_url e audio_url; per la generazione di video da immagine aggiungi image_url; aggiungi audio_url (di solito insieme a un'immagine) perché il soggetto segua il tuo voiceover.

Richiesta minima funzionante

curl -X POST 'https://api.hiapi.ai/v1/tasks' \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "creatify-boreal",
    "input": {
      "prompt": "Video UGC in stile selfie verticale: una giovane donna in una luminosa camera da letto solleva un rossetto rosa tenue verso la fotocamera e dice: \"Va bene, questo è l'unico rossetto che mi ha fatto superare l'inverno.\" Suoni ambientali naturali della stanza.",
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "duration": 4
    }
  }'

La risposta fornisce un id attività:

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

Python: invio e polling

import os, time, requests

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

def create(payload: dict) -> str:
    r = requests.post(BASE, headers=HEADERS, json=payload, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id: str, every: int = 10, limit: int = 900) -> dict:
    start = time.time()
    while time.time() - start < limit:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except (requests.RequestException, ValueError):
            time.sleep(every)  # errore di rete transitorio: continua a interrogare lo stesso id
            continue
        if d["status"] == "success":
            return d
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(every)
    raise TimeoutError(task_id)

task_id = create({
    "model": "creatify-boreal",
    "input": {
        "prompt": "Video UGC in stile selfie verticale: una giovane donna solleva un rossetto rosa tenue verso la fotocamera e dice: \"Va bene, questo è l'unico rossetto che mi ha fatto superare l'inverno.\" Suoni ambientali naturali della stanza.",
        "resolution": "720p",
        "aspect_ratio": "9:16",
        "duration": 4,
    },
})
result = wait(task_id)
print(result["output"][0]["url"])

Lo stato passa attraverso handling, archiving, poi success. L'URL del video si trova in data.output[0].url.

Modalità immagine e audio

La generazione di video da immagine aggiunge un campo:

{"model": "creatify-boreal",
 "input": {"prompt": "Questa donna sorride e parla verso la fotocamera in cucina: \"Ho sostituito il caffè con questa bevanda di latte d'avena.\" Suoni ambientali naturali della cucina.",
           "image_url": "https://your-cdn.example/presenter.jpg",
           "resolution": "720p", "duration": 8}}

La modalità guidata dall'audio aggiunge audio_url che punta al file di voiceover. La pagina del modello lo descrive come: il voiceover resta nel video, le labbra seguono il voiceover, e vengono usati solo i primi duration secondi dell'audio, quindi imposta duration alla lunghezza della clip che desideri. L'esempio audio della pagina del modello abbina l'audio a un'immagine di riferimento; io personalmente non ho eseguito una generazione immagine più audio, quindi in questo articolo tale combinazione è documentata ma non verificata.

Come si presenta una vera esecuzione

Ho eseguito la richiesta qui sopra (solo testo, 720p, 9:16, 4 secondi).

• Tempo di generazione: l'attività è rimasta nello stato handling per circa 283 secondi, poi nello stato archiving per circa 10 secondi. Anche per una clip di 4 secondi, pianifica in minuti, non in secondi. Esegui il polling ogni 10 secondi o usa un callback, invece di timeout brevi.
• File di output: MP4 720x1280, video H.264 a 24 fps più traccia audio AAC, durata 4,04 secondi. Nonostante la richiesta non avesse campi audio, l'audio è presente: è coerente con il design audio nativo del modello.
• URL temporaneo: l'URL di output si trova su temp.hiapi.ai, con un expireAt che scade dopo circa 7 giorni. Scarica il file e archivialo tu, invece di collegarlo dalla pagina.
• Struttura dei costi: la fatturazione è al secondo e dipende da resolution (vedi la pagina dei prezzi), quindi il modo più economico per iterare sul prompt è 720p con una duration breve, poi ri-renderizzare la versione finale a 1080p o 2k.

Problemi che ho incontrato

• I valori errati falliscono subito e gratis. Inviare aspect_ratio: "7:5", duration: 25 o resolution: "4k" restituisce HTTP 400 INVALID_REQUEST, con un messaggio che elenca i valori consentiti ('auto', '16:9', '9:16', '1:1', '4:3', '3:4', massimo 20, e '720p', '1080p', '2k'). Sfrutta questo per validare i tuoi form prima dell'invio.
• Gli URL dei media errati falliscono più tardi, durante il polling. Ho inviato audio_url: "https://example.com/a.mp3" (non un vero file audio). La chiamata di creazione ha restituito HTTP 200 e un id attività, e circa 15 secondi dopo l'attività è terminata con status: "fail" e error.code: "INVALID_REQUEST". Quindi un 200 al momento della creazione non significa che i tuoi media siano disponibili; controlla sempre lo stato finale e leggi data.error. In questo caso il fallimento si manifesta all'interno di una risposta di polling HTTP 200, non come errore HTTP.
• Il fallimento è status: "fail", non uno stato HTTP. La richiesta di polling stessa restituisce 200, quindi controlla data.status.

Pagine correlate

• Pagina del modello Creatify Boreal: Playground, prezzi in tempo reale e clip di esempio
• Prezzi di hiapi
• Documentazione di hiapi
• Come usare l'API OmniHuman 1.5: un altro modello video in stile presentatore
• API Ray 3.2 da immagine a video
• Guida all'API video Wan 3.0

Domande frequenti

Servono id modello separati per input di testo, immagine e audio? No. Tutti e tre usano creatify-boreal; i campi che includi in input determinano la modalità.

Quanto può essere lunga la clip al massimo? Un numero intero di secondi da 1 a 20. Il valore 25 viene rifiutato con HTTP 400.

L'output contiene l'audio? Sì. La clip di test di 4 secondi aveva una traccia audio AAC anche senza aver fornito un input audio.

Quali risoluzioni sono disponibili? 720p, 1080p e 2k. La fatturazione varia in base alla risoluzione; consulta la pagina dei prezzi.

Quanto dovrei aspettare? Il mio test da 4 secondi a 720p ha impiegato circa cinque minuti end-to-end. Usa il polling con un limite generoso o un callback.