Come usare l'API di Runway Gen-4.5? Il primo video pronto in 5 minuti

TL;DR

• Runway Gen-4.5 è il modello video di Runway; su HiAPI ci sono due ingressi, text-to-video e image-to-video. Apri la pagina del modello per provarlo online; i nuovi utenti ricevono 200 crediti alla registrazione.
• Entrambi gli ingressi costano $0.1715 al secondo: 5 secondi $0.8575, 8 secondi $1.372, 10 secondi $1.715.
• Come si chiama: invia con POST /v1/tasks, controlla il risultato con taskId; il video finale è in output[0].url.

Cosa può fare Runway Gen-4.5

• Tre durate: 5, 8 e 10 secondi: 8 secondi bastano appena per completare una carrellata in avanti, un'orbita o una lenta salita.
• 720p fisso: orizzontale 1280×720, verticale 720×1280, nessuna risoluzione da scegliere.
• Image-to-video con 5 formati: 16:9, 9:16, 4:3, 3:4, 1:1; dalla stessa immagine puoi ottenere versioni per piattaforme diverse.
• Il video finale non ha traccia audio: le immagini le gestisce il modello, l'audio si aggiunge in fase di montaggio.

She turns her head toward the camera and smiles, hair moves in a light breeze, slow push-in

Genera con questo prompt → (carica il primo frame del ritratto, scegli 5 secondi, 3:4)

runway-gen-4.5/image-to-video, 3:4, 832×1104, 5 secondi, $0.8575. Primo frame: .

Lei gira il viso di profilo verso la camera e sorride, i capelli si muovono leggermente, la camera avanza fino a un primo piano del volto. Il prompt descrive solo l'azione e il movimento di camera; l'aspetto della persona e la luce della finestra vengono tutti dal primo frame.

Come scegliere tra i due ingressi

ID modello	Input	Durata	Formato	Adatto a
runway-gen-4.5/text-to-video	prompt	5 / 8 / 10 secondi (9:16 solo 5 / 10)	16:9, 9:16	Nessun materiale, si parte dal testo
runway-gen-4.5/image-to-video	1 primo frame + prompt	5 / 8 / 10 secondi	16:9, 9:16, 4:3, 3:4, 1:1	Il soggetto deve corrispondere all'immagine originale, o serve formato quadrato, 4:3, 3:4

I due ingressi hanno lo stesso prezzo: $0.1715 al secondo.

Due percorsi per iniziare

Provare nel browser (3 passaggi)

1. Apri la pagina del modello text-to-video o image-to-video e accedi.
2. Scrivi il prompt; per image-to-video carica prima un primo frame.
3. Scegli 5 secondi e il formato, poi premi esegui.

Chiamare via API (3 passaggi)

1. Crea una chiave nella pagina API Key della console e mettila nella variabile d'ambiente HIAPI_KEY.
2. Invia con POST https://api.hiapi.ai/v1/tasks, la risposta contiene data.taskId.
3. Con GET /v1/tasks/{taskId} controlla che status sia success, poi scarica output[0].url.

curl: il primo video

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "runway-gen-4.5/text-to-video",
    "input": {
      "prompt": "A lone stone lighthouse on a rugged sea cliff at dusk, heavy waves crashing against the rocks, the lamp beam sweeping across dark storm clouds, slow cinematic push-in, drifting sea mist, dramatic lighting",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

5 secondi, 16:9, $0.8575. Il video finale è così:

A lone stone lighthouse on a rugged sea cliff at dusk, heavy waves crashing against the rocks, the lamp beam sweeping across dark storm clouds, slow cinematic push-in, drifting sea mist, dramatic lighting

Genera con questo prompt → (scegli 5 secondi, 16:9)

runway-gen-4.5/text-to-video, 16:9, 1280×720, 5 secondi, $0.8575.

Python: invio, polling, download

# pip install requests；先 export HIAPI_KEY=你的 Key
import os, time, uuid, requests

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

def generate(model, timeout_s=900, **inp):
    # 重试同一个任务时带同一个 Idempotency-Key，避免重复扣费
    r = requests.post(API, json={"model": model, "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

# 图生视频：同一张图出 1:1 版本，8 秒（$1.372）
url = generate(
    "runway-gen-4.5/image-to-video",
    prompt="The scene slowly comes alive: clouds drift, light shifts across the mountain lake, gentle forward camera move",
    image_urls=["https://你的图床/lake.jpg"],
    duration=8, aspect_ratio="1:1",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Tabella dei parametri

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	1–1000 caratteri	Descrivi soggetto, azione e inquadratura; per image-to-video scrivi solo azione e inquadratura
duration	No	5 (predefinito) / 8 / 10	Text-to-video 9:16 solo 5 / 10
aspect_ratio	No	Testo: 16:9 (predefinito) 9:16; immagine: 16:9 (predefinito) 9:16 4:3 3:4 1:1	Per image-to-video il primo frame viene ritagliato al centro secondo il formato
image_urls	Obbligatorio per image-to-video	Solo 1, jpeg/png/webp, ≤10MB	Primo frame; text-to-video non accetta questo campo

Non esistono resolution, seed, negative_prompt, né frame finale.

Gli errori che incontrerai

Se al momento dell'invio i parametri non sono corretti, l'API restituisce direttamente 400, senza creare il task e senza addebitare nulla:

• duration: value must be one of 5, 10: per text-to-video hai scelto 9:16 e inviato 8 secondi.
• duration: value must be one of 5, 8, 10: le durate sono solo queste tre.
• image_urls: maxItems: got 2, want 1: image-to-video accetta solo un primo frame, non supporta il frame finale.
• image_urls: missing required field "image_urls": per image-to-video non hai inviato il primo frame.
• prompt: maxLength: got 3,000, want 1,000: il prompt ha una lunghezza massima di 1000 caratteri.
• additional properties 'negative_prompt', 'cfg_scale' not allowed: questi due campi non esistono su Runway Gen-4.5.

Da tenere presente prima della messa in produzione

• Usa i callback invece del polling: al livello superiore della richiesta (stesso livello di input) aggiungi "callback": {"url": "https://tuo-dominio/hiapi/callback"}, deduplica per taskId.
• Salva subito i risultati: output[0].url scade dopo circa 7 giorni, salvalo nel tuo storage appena lo ricevi.
• Specifica esplicitamente duration e aspect_ratio: per text-to-video verticale evita gli 8 secondi; scriverlo fisso nel codice è la soluzione più stabile.
• Riprova con la chiave di idempotenza: aggiungi Idempotency-Key nell'header della richiesta; con la stessa chiave viene creato un solo task.

Domande frequenti

Si può ottenere 1080p o 4K?

No, l'output è fisso a 720p. Per il 1080p puoi usare Kling 2.5 Turbo; confronta in Confronto tra Runway Gen-4.5 e Kling 2.5 Turbo.

Il video finale ha l'audio?

No, l'output contiene solo le immagini. Musica, effetti sonori e voce fuori campo si aggiungono in fase di montaggio.

Image-to-video può aggiungere un frame finale?

No, image_urls accetta una sola immagine. Se vuoi controllare la scena finale con un frame finale, usa image-to-video di Kling 2.5 Turbo.

Cosa succede se il rapporto del primo frame è diverso dal formato?

Il primo frame viene ritagliato al centro secondo il formato scelto; il soggetto al centro è la soluzione più stabile.

Per i dettagli sui prezzi vedi Prezzi dell'API Runway Gen-4.5; per altri casi d'uso vedi Guida completa ai prompt di Runway Gen-4.5. Se vuoi prima vedere il risultato, copia il prompt del faro qui sopra e genera il tuo primo video nella pagina del modello.