Comment utiliser l'API Ray 3.2 ? Lancez votre première vidéo en 5 minutes

TL;DR

• C'est quoi : Ray 3.2 de Luma AI, disponible sur HiAPI en deux canaux : ray-3.2/text-to-video ne prend qu'un prompt, ray-3.2/image-to-video est piloté par une image de début (image de fin en option). Déjà disponible sur HiAPI, ouvrez la page du modèle texte-vers-vidéo pour générer ; les nouveaux utilisateurs reçoivent 200 crédits à l'inscription.
• Combien ça coûte : facturation à la vidéo, 5 secondes en 540p à $0.2145, 720p à $0.429, 1080p à $1.7145 ; 10 secondes uniquement en texte-vers-vidéo, 540p à $0.643, 720p à $1.286, 1080p à $5.143. Remboursement automatique en cas d'échec.
• Comment appeler l'API : POST https://api.hiapi.ai/v1/tasks, renseignez le model du canal correspondant, récupérez le taskId puis faites du polling ou attendez le callback.url, et téléchargez le MP4 muet depuis data.output[0].url.

La sortie de Ray 3.2 est un MP4 sans son. En texte-vers-vidéo, vous choisissez la durée et le format dans la requête ; en image-vers-vidéo, la durée est fixée à 5 secondes et le format suit l'image de début. Ci-dessous, de l'essai en ligne à curl, Python, l'image-vers-vidéo et les points à surveiller avant la mise en production, en une seule passe.

Qu'est-ce que Ray 3.2 ? Comment choisir entre les deux canaux

• Texte-vers-vidéo : envoyez uniquement prompt, avec en option duration (5 ou 10 secondes), resolution (540p / 720p / 1080p), aspect_ratio (16:9, 9:16, 1:1, 4:3, 3:4, 21:9). Le prompt peut faire jusqu'à 6000 caractères.
• Image-vers-vidéo : prompt et l'image de début image_url obligatoires, image de fin end_image_url et resolution en option. Chaque vidéo fait 5 secondes, le format suit l'image de début et correspond automatiquement au ratio supporté le plus proche.
• Points communs : les deux passent par /v1/tasks, sont facturés à la vidéo et produisent un MP4 sans piste audio.

Le texte-vers-vidéo convient aux plans dont vous n'avez qu'une idée écrite, à 10 secondes ou avec un format imposé ; l'image-vers-vidéo convient quand vous avez déjà une image produit, une affiche, une image conceptuelle, ou que vous voulez verrouiller l'image finale. Les trois paliers de 5 secondes communs aux deux canaux sont au même prix ; le 10 secondes est réservé au texte-vers-vidéo.

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.

Générer avec ce prompt →, choisissez le format 21:9, une vidéo 540p coûte $0.2145.

Deux parcours : essai en ligne ou API ?

Essai en ligne (environ 1 minute)

1. Ouvrez la page du modèle Ray 3.2 texte-vers-vidéo, ou cliquez sur le lien prérempli ci-dessus.
2. Inscrivez-vous ou connectez-vous, un nouveau compte reçoit 200 crédits ; une vidéo 5 secondes 540p coûte 429 crédits, il suffit de recharger pour générer.
3. Écrivez le prompt, choisissez la durée, la résolution et le format, puis cliquez sur exécuter.
4. Téléchargez la vidéo si elle vous convient ; si vous avez besoin de l'API, créez ensuite une clé dans la console.

Intégration API (environ 5 minutes)

1. Créez une clé API dans la console HiAPI (sk-...).
2. POST /v1/tasks pour créer la tâche, récupérez data.taskId dans la réponse.
3. Interrogez avec GET /v1/tasks/{id}, ou mettez callback.url au niveau racine du corps de la requête pour attendre la notification.
4. Une fois data.status passé à success, téléchargez la vidéo depuis data.output[0].url.

Une vidéo 5 secondes 540p coûte $0.2145, avec $10 vous pouvez en produire environ 46, de quoi bien tester le mouvement d'une série de plans. Essayez votre première vidéo sur la page du modèle →

Première vidéo : version curl

Créer une tâche texte-vers-vidéo :

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 de tâche renvoyé se trouve dans data.taskId :

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

Récupérer le résultat :

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

Seul prompt est obligatoire. duration vaut 5 par défaut, resolution 540p, aspect_ratio 16:9. Les trois champs font l'objet d'une validation stricte, une valeur erronée renvoie directement 400, sans arrondi automatique.

Première vidéo : version Python

Création, polling et téléchargement en une seule passe :

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"))

Une tâche vidéo prend généralement de quelques dizaines de secondes à quelques minutes, prévoyez un intervalle de polling de 5 secondes et un timeout maximal de 10 à 15 minutes. Le lien de sortie expire, téléchargez immédiatement puis stockez sur votre propre stockage.

Image-vers-vidéo : ajoutez une image de début, ou début et fin

Remplacez model par ray-3.2/image-to-video et ajoutez l'image de début image_url, la même requête devient de l'image-vers-vidéo :

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"
    }
  }'

Pour verrouiller l'image finale, ajoutez end_image_url. Plus le cadrage, la lumière et la position du sujet de l'image de début et de l'image de fin sont proches, plus la transition est stable ; si les deux images ont des cadrages différents, le modèle ajoute lui-même un mouvement de caméra pour faire la liaison. Ces deux champs n'affectent pas le prix.

L'image-vers-vidéo n'a ni duration ni aspect_ratio : chaque vidéo fait 5 secondes, le format correspond à l'image de début parmi 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 le plus proche, et en cas de ratio différent les bords sont rognés. Pour contrôler entièrement le ratio de sortie, recadrez d'abord l'image de début dans l'un de ces six ratios.

3 points à surveiller avant la mise en production

1. Utilisez le callback côté serveur. Ajoutez "callback": {"url": "https://yourapp.com/webhook", "when": "final"} au niveau racine du corps de la requête, la notification est automatique quand la tâche atteint son état final, ce qui évite le polling. success et fail déclenchent tous deux le callback, rendez le traitement idempotent côté serveur par taskId.
2. En cas de timeout, ne refaites pas de POST. Chaque POST crée une nouvelle tâche et est facturé séparément. Enregistrez d'abord le taskId, dédupliquez dans votre propre système avant de réessayer ; si le processus plante, reprenez la consultation à partir de l'id enregistré.
3. Écrivez explicitement les paramètres de chaque requête. resolution détermine directement le prix unitaire, duration n'accepte que les entiers 5 ou 10, l'image-vers-vidéo ne doit pas inclure duration ni aspect_ratio. Fixez-les dans la requête pour que la facturation et le comportement soient prévisibles.

Erreurs courantes, une par ligne

• 400 INVALID_REQUEST, valeur de resolution invalide → seuls 540p, 720p, 1080p sont acceptés, pas de 2k ni 480p.
• 400, valeur de duration invalide → seuls les entiers 5 et 10 sont acceptés ; une chaîne "5" ou le nombre 7 échouent.
• 400 additional properties 'aspect_ratio' not allowed → l'image-vers-vidéo n'a pas ce champ, supprimez-le ; seul le texte-vers-vidéo le supporte.
• 401 permission_denied → clé manquante, mal écrite ou révoquée, vérifiez Authorization: Bearer sk-....
• Création renvoie 200, puis la tâche passe à fail → généralement l'image_url de l'image-vers-vidéo est inaccessible ou n'est pas une image. La création ne valide que la forme des champs, pas l'accessibilité de l'URL.
• Le lien ne s'ouvre plus au bout de quelques jours → l'URL de sortie a une durée de validité, téléchargez immédiatement après l'avoir obtenue.

Le montant prélevé pour une tâche échouée est automatiquement remboursé intégralement.

Questions fréquentes

Quelle est la durée d'une vidéo Ray 3.2 ? Le texte-vers-vidéo propose 5 ou 10 secondes ; l'image-vers-vidéo est fixé à 5 secondes.

Quelle est la longueur maximale du prompt ? 1 à 6000 caractères pour les deux canaux.

La vidéo a-t-elle du son ? Non, la sortie est un MP4 sans piste audio, la musique et les effets sonores s'ajoutent en post-production.

Peut-on choisir le format en image-vers-vidéo ? Non. Le format suit l'image de début, avec correspondance automatique au ratio supporté le plus proche.

Peut-on envoyer une image de référence en texte-vers-vidéo ? Non. Pour piloter par image, utilisez ray-3.2/image-to-video.

Articles de la série Ray 3.2

• Page du modèle Ray 3.2 texte-vers-vidéo : génération en ligne, cas réels
• Page du modèle Ray 3.2 image-vers-vidéo : cas avec image de début, image de fin et verticale
• Combien coûte l'API Ray 3.2 : 6 paliers de prix unitaires et budget mensuel
• Ray 3.2 vs Runway Gen-4.5 : comment choisir entre texte-vers-vidéo et image-vers-vidéo
• Guide complet des prompts Ray 3.2 : 5 cas texte-vers-vidéo + 3 cas image-vers-vidéo
• Documentation d'intégration Ray 3.2 : tous les paramètres et codes d'erreur

Essayez maintenant : cliquez sur le Générer avec ce prompt → sous la vidéo du phare ci-dessus, le prompt est déjà rempli, choisissez 5 secondes, 540p, 21:9, un clic et vous obtenez la même vidéo.