Come si usa l'API di Ray 3.2? La tua prima clip video in 5 minuti

TL;DR

• Cos'è: Ray 3.2 di Luma AI, disponibile su HiAPI in due modalità: ray-3.2/text-to-video accetta solo il prompt, ray-3.2/image-to-video viene guidato da un primo frame (e facoltativamente da un ultimo frame). È già online su HiAPI: apri la pagina del modello text-to-video e genera subito; i nuovi utenti ricevono 200 crediti alla registrazione.
• Quanto costa: a clip, 5 secondi 540p $0.2145, 720p $0.429, 1080p $1.7145; la durata di 10 secondi esiste solo per text-to-video: 540p $0.643, 720p $1.286, 1080p $5.143. In caso di errore il rimborso è automatico.
• Come chiamare l'API: POST https://api.hiapi.ai/v1/tasks, imposta model sulla modalità corrispondente, recupera taskId e poi esegui il polling o attendi callback.url; scarica il file MP4 senza audio da data.output[0].url.

L'output di Ray 3.2 è un MP4 senza audio. Con il text-to-video puoi scegliere durata e formato nella richiesta; l'image-to-video è fisso a 5 secondi e il formato segue il primo frame. Di seguito trovi il percorso completo: prova online, curl, Python, image-to-video e note per la messa in produzione.

Cos'è Ray 3.2? Come scegliere tra le due modalità

• Text-to-video: invii solo prompt; puoi opzionalmente impostare duration (5 o 10 secondi), resolution (540p / 720p / 1080p) e aspect_ratio (16:9, 9:16, 1:1, 4:3, 3:4, 21:9). Il prompt può arrivare a 6000 caratteri.
• Image-to-video: richiede prompt e il primo frame image_url; sono facoltativi end_image_url e resolution. Ogni clip dura 5 secondi, il formato segue il primo frame e viene allineato automaticamente al rapporto supportato più vicino.
• In comune: entrambe usano /v1/tasks, si pagano a clip e producono un MP4 senza traccia audio.

Il text-to-video è ideale quando hai solo un'idea testuale e ti servono 10 secondi o un formato specifico; l'image-to-video è adatto se hai già un'immagine di prodotto, un poster, un concept o vuoi fissare l'immagine finale. Le due modalità condividono le tre fasce di prezzo per i 5 secondi; i 10 secondi sono esclusivi del text-to-video.

Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.

Genera con questo prompt →, scegli il formato 21:9, una clip 540p costa $0.2145.

Due percorsi per iniziare: prova online o API?

Prova online (circa 1 minuto)

1. Apri la pagina del modello Ray 3.2 text-to-video, oppure clicca il link precompilato qui sopra.
2. Registrati o accedi: un nuovo account ha 200 crediti in dotazione; una clip 5 secondi 540p costa 429 crediti, quindi ricarica per iniziare a generare.
3. Scrivi il prompt, scegli durata, risoluzione e formato, poi clicca su esegui.
4. Se il risultato ti soddisfa, scaricalo; quando ti serve l'API, crea una Key nella console.

Integrazione API (circa 5 minuti)

1. Crea una API Key (sk-...) nella console HiAPI.
2. Chiama POST /v1/tasks per creare un task; nella risposta trovi data.taskId.
3. Interroga con GET /v1/tasks/{id}, oppure passa callback.url al livello superiore del body della richiesta per ricevere una notifica.
4. Quando data.status diventa success, scarica il video da data.output[0].url.

Una clip 5 secondi 540p costa $0.2145: con $10 puoi generarne circa 46, abbastanza per testare a fondo il movimento di una serie di inquadrature. Vai alla pagina del modello e prova la prima →

La prima clip video: versione curl

Crea un task text-to-video:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/text-to-video",
    "input": {
      "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
      "duration": 5,
      "resolution": "540p",
      "aspect_ratio": "21:9"
    }
  }'

L'ID del task restituito si trova in data.taskId:

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

Interroga il risultato:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

L'unico campo obbligatorio è prompt. duration ha default 5, resolution ha default 540p, aspect_ratio ha default 16:9. Tutti e tre i campi vengono validati in modo rigoroso: un valore errato restituisce subito 400, senza arrotondamenti automatici.

La prima clip video: versione Python

Creazione, polling e download in un unico script:

import time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "ray-3.2/text-to-video",
    "input": {
        "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
        "duration": 5,
        "resolution": "540p",
        "aspect_ratio": "21:9",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    video_url = task["output"][0]["url"]
    with open("ray32-clip.mp4", "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
else:
    print(task.get("error"))

I task video richiedono in genere da decine di secondi a qualche minuto: imposta un intervallo di polling di 5 secondi e un timeout massimo di 10–15 minuti. Il link di output scade, quindi scarica subito e salva nel tuo storage.

Image-to-video: aggiungi un primo frame, oppure primo e ultimo

Cambia model in ray-3.2/image-to-video, aggiungi il primo frame image_url e la stessa richiesta diventa image-to-video:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/image-to-video",
    "input": {
      "prompt": "The ribbon of milk keeps folding down through the iced espresso, the ice cubes settle and shift slightly, condensation beads slide down the outside of the glass, very slow push-in toward the glass, warm rim light stays steady, vertical product commercial shot",
      "image_url": "https://www.hiapi.ai/images/model-pages/ray-3-2/iced-coffee-first.jpg",
      "resolution": "1080p"
    }
  }'

Per fissare l'immagine finale, aggiungi end_image_url. Più il punto di ripresa, l'illuminazione e la posizione del soggetto del primo e dell'ultimo frame sono simili, più la transizione è stabile; se le due immagini hanno inquadrature diverse, il modello aggiunge da solo un movimento di camera per raccordarle. Nessuno dei due campi influisce sul prezzo.

L'image-to-video non ha duration né aspect_ratio: ogni clip dura 5 secondi e il formato segue il primo frame, allineandosi al più vicino tra 16:9, 9:16, 1:1, 4:3, 3:4 e 21:9; se il rapporto non coincide, i bordi vengono ritagliati. Se vuoi il pieno controllo del formato di output, ritaglia prima il primo frame su uno di questi sei rapporti.

3 cose da sapere prima della messa in produzione

1. Sul server usa il callback. Aggiungi al livello superiore del body della richiesta "callback": {"url": "https://yourapp.com/webhook", "when": "final"}: il task notifica automaticamente al raggiungimento dello stato finale, evitando il polling. Il callback arriva sia per success sia per fail; sul server gestisci l'idempotenza tramite taskId.
2. In caso di timeout, non ripetere il POST. Ogni POST crea un nuovo task e viene addebitato separatamente. Salva prima il taskId e deduplica nel tuo sistema prima di riprovare; se il processo va in crash, riprendi l'interrogazione dall'id salvato.
3. Scrivi esplicitamente i parametri in ogni richiesta. resolution determina direttamente il prezzo unitario, duration accetta solo gli interi 5 o 10, mentre per l'image-to-video non passare duration e aspect_ratio. Fissa i valori nella richiesta per avere costi e comportamenti prevedibili.

Errori comuni, uno per riga

• 400 INVALID_REQUEST, valore di resolution non valido → sono accettati solo 540p, 720p e 1080p; 2k e 480p non esistono.
• 400, valore di duration non valido → sono accettati solo gli interi 5 e 10; una stringa "5" o il numero 7 falliscono.
• 400 additional properties 'aspect_ratio' not allowed → l'image-to-video non ha questo campo, rimuovilo; è supportato solo dal text-to-video.
• 401 permission_denied → Key mancante, errata o revocata; controlla Authorization: Bearer sk-....
• La creazione restituisce 200, ma il task va poi in fail → di solito l'image_url dell'image-to-video non si apre o non è un'immagine. In fase di creazione viene validata solo la forma dei campi, non l'accessibilità dell'URL.
• Il link non si apre dopo qualche giorno → l'URL di output ha una scadenza; scaricalo immediatamente.

L'importo prenotato per i task falliti viene rimborsato automaticamente per intero.

Domande frequenti

Quanto dura un video Ray 3.2? Il text-to-video permette 5 o 10 secondi; l'image-to-video è fisso a 5 secondi.

Quanto può essere lungo il prompt? Da 1 a 6000 caratteri per entrambe le modalità.

Il video ha l'audio? No, l'output è un MP4 senza traccia audio; musica ed effetti si aggiungono in post-produzione.

Posso scegliere il formato nell'image-to-video? No. Il formato segue il primo frame e si allinea automaticamente al rapporto supportato più vicino.

Posso passare un'immagine di riferimento al text-to-video? No. Se vuoi guidare la generazione con un'immagine, usa ray-3.2/image-to-video.

Articoli della serie Ray 3.2

• Pagina del modello Ray 3.2 text-to-video: genera online e guarda casi reali
• Pagina del modello Ray 3.2 image-to-video: casi con primo frame, ultimo frame e verticale
• Quanto costa l'API Ray 3.2: 6 fasce di prezzo e budget mensile
• Ray 3.2 vs Runway Gen-4.5: come scegliere tra text-to-video e image-to-video
• Guida completa ai prompt Ray 3.2: 5 esempi text-to-video + 3 image-to-video
• Documentazione Ray 3.2 in cinese: tutti i parametri e i codici di errore

Prova subito: clicca Genera con questo prompt → sotto il video del faro qui sopra: il prompt è già compilato, scegli 5 secondi, 540p, 21:9 e con un clic ottieni la stessa clip.