Como usar a API do Ray 3.2? Gere seu primeiro vídeo em 5 minutos

TL;DR

• O que é: Ray 3.2 da Luma AI, dividido em duas rotas na HiAPI: ray-3.2/text-to-video aceita apenas o prompt, ray-3.2/image-to-video é guiado pelo primeiro frame (opcionalmente com último frame). Já está disponível na HiAPI, abra a página do modelo de texto para vídeo e gere na hora; novos usuários ganham 200 créditos ao se registrar.
• Quanto custa: cobrança por vídeo, 5 segundos 540p $0.2145, 720p $0.429, 1080p $1.7145; 10 segundos só existe em texto para vídeo, 540p $0.643, 720p $1.286, 1080p $5.143. Falhas são reembolsadas automaticamente.
• Como chamar a API: POST https://api.hiapi.ai/v1/tasks, preencha model com a rota correspondente, após obter o taskId faça polling ou aguarde o callback.url, e baixe o MP4 sem áudio em data.output[0].url.

A saída do Ray 3.2 é um MP4 sem som. Texto para vídeo permite escolher duração e proporção na requisição; imagem para vídeo é fixo em 5 segundos e a proporção segue o primeiro frame. Abaixo, do teste online ao curl, Python, imagem para vídeo e cuidados antes de ir para produção, tudo de uma vez.

O que é o Ray 3.2? Como escolher entre as duas rotas

• Texto para vídeo: envie apenas prompt, com duration opcional (5 ou 10 segundos), resolution (540p / 720p / 1080p), aspect_ratio (16:9, 9:16, 1:1, 4:3, 3:4, 21:9). O prompt tem no máximo 6000 caracteres.
• Imagem para vídeo: obrigatórios prompt e o primeiro frame image_url, opcionais o último frame end_image_url e resolution. Cada vídeo é fixo em 5 segundos, a proporção segue o primeiro frame, ajustada automaticamente à proporção suportada mais próxima.
• Em comum: ambos usam /v1/tasks, ambos são cobrados por vídeo e ambos geram MP4 sem faixa de áudio.

Texto para vídeo é ideal para tomadas que existem só como ideia textual, precisam de 10 segundos ou de uma proporção específica; imagem para vídeo é ideal quando você já tem foto de produto, pôster, arte conceitual ou quer fixar o frame final. Os 5 segundos nas três faixas de preço são iguais nas duas rotas, e os 10 segundos são exclusivos do texto para vídeo.

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.

Gerar com este prompt →, escolha proporção 21:9, 540p por $0.2145 o vídeo.

Duas formas de começar: teste online ou API?

Teste online (cerca de 1 minuto)

1. Abra a página do modelo Ray 3.2 texto para vídeo, ou clique no link pré-preenchido acima.
2. Registre-se ou faça login; contas novas ganham 200 créditos; um vídeo de 5 segundos 540p consome 429 créditos, então gere após recarregar.
3. Escreva o prompt, escolha duração, resolução e proporção, e clique em executar.
4. Baixe quando o vídeo estiver bom; quando precisar da API, crie uma Key no console.

Integração via API (cerca de 5 minutos)

1. Crie uma API Key (sk-...) no console da HiAPI.
2. POST /v1/tasks cria a tarefa; a resposta traz data.taskId.
3. Consulte com GET /v1/tasks/{id}, ou inclua callback.url no nível superior do corpo da requisição e aguarde a notificação.
4. Quando data.status virar success, baixe o vídeo em data.output[0].url.

5 segundos 540p custa $0.2145 por vídeo, $10 rende cerca de 46 vídeos, o suficiente para testar bem o movimento de um conjunto de tomadas. Vá à página do modelo e teste o primeiro →

Primeiro vídeo: versão curl

Criar uma tarefa de texto para vídeo:

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

O ID da tarefa retornado fica em data.taskId:

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

Consultar o resultado:

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

Só prompt é obrigatório. duration é 5 por padrão, resolution é 540p por padrão, aspect_ratio é 16:9 por padrão. Os três campos passam por validação estrita; valores errados retornam 400 direto, sem arredondamento automático.

Primeiro vídeo: versão Python

Criar, fazer polling e baixar em um único bloco:

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

Tarefas de vídeo costumam levar de dezenas de segundos a alguns minutos; use intervalo de polling de 5 segundos e limite de timeout de 10–15 minutos. O link de saída expira; baixe imediatamente após recebê-lo e armazene no seu próprio storage.

Imagem para vídeo: adicione um primeiro frame, ou primeiro e último frames

Troque model para ray-3.2/image-to-video, adicione o primeiro frame image_url, e a mesma requisição vira imagem para vídeo:

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

Para fixar o frame final, adicione end_image_url. Quanto mais próximos forem posição de câmera, iluminação e posição do sujeito entre primeiro e último frames, mais estável será a transição; quando as duas imagens têm enquadramentos diferentes, o modelo adiciona um movimento de câmera para conectar. Nenhum dos dois campos afeta o preço.

Imagem para vídeo não tem duration nem aspect_ratio: cada vídeo é fixo em 5 segundos, e a proporção é ajustada conforme o primeiro frame para a mais próxima entre 16:9, 9:16, 1:1, 4:3, 3:4 e 21:9; se a proporção não coincidir, as bordas são cortadas. Para controlar totalmente a proporção de saída, corte o primeiro frame em uma dessas seis proporções antes.

3 cuidados antes de ir para produção

1. Use callback no servidor. Adicione no nível superior do corpo da requisição "callback": {"url": "https://yourapp.com/webhook", "when": "final"}; a tarefa notifica automaticamente ao entrar em estado terminal, eliminando o polling. Tanto success quanto fail disparam callback; faça idempotência no servidor por taskId.
2. Em timeout, não repita o POST. Cada POST cria uma nova tarefa e cobra separadamente. Salve o taskId primeiro e deduplique no seu sistema antes de tentar de novo; se o processo cair, continue a consulta a partir do id salvo.
3. Escreva os parâmetros explicitamente em cada requisição. resolution determina diretamente o preço unitário, duration aceita apenas inteiros 5 ou 10, e imagem para vídeo não deve incluir duration nem aspect_ratio. Fixe-os na requisição para que cobrança e comportamento sejam previsíveis.

Erros comuns, um por linha

• 400 INVALID_REQUEST, valor de resolution incorreto → aceita apenas 540p, 720p, 1080p; não existe 2k nem 480p.
• 400, valor de duration incorreto → aceita apenas os inteiros 5 e 10; enviar a string "5" ou o número 7 falha.
• 400 additional properties 'aspect_ratio' not allowed → imagem para vídeo não tem esse campo, remova; só texto para vídeo o suporta.
• 401 permission_denied → Key ausente, errada ou revogada; verifique Authorization: Bearer sk-....
• Criação retorna 200, tarefa depois vai para fail → normalmente o image_url do imagem para vídeo não abre ou não é uma imagem. Na criação só se valida o formato dos campos, não se a URL é acessível.
• Link não abre depois de alguns dias → a URL de saída tem validade; baixe imediatamente após recebê-la.

Tarefas com falha têm o valor pré-cobrado reembolsado integralmente de forma automática.

Perguntas frequentes

Qual a duração de um vídeo do Ray 3.2? Texto para vídeo pode ter 5 ou 10 segundos; imagem para vídeo é fixo em 5 segundos.

Qual o tamanho máximo do prompt? Ambas as rotas: 1–6000 caracteres.

O vídeo tem som? Não; a saída é um MP4 sem faixa de áudio, trilha e efeitos sonoros são adicionados na pós-produção.

Dá para escolher a proporção no imagem para vídeo? Não. A proporção segue o primeiro frame, ajustada automaticamente à proporção suportada mais próxima.

Dá para enviar imagem de referência no texto para vídeo? Não. Para ser guiado por imagem, use ray-3.2/image-to-video.

Série de artigos sobre Ray 3.2

• Página do modelo Ray 3.2 texto para vídeo: gere online e veja casos reais
• Página do modelo Ray 3.2 imagem para vídeo: casos com primeiro frame, último frame e vertical
• Quanto custa a API do Ray 3.2: 6 faixas de preço unitário e orçamento mensal
• Ray 3.2 vs Runway Gen-4.5: como escolher entre texto para vídeo e imagem para vídeo
• Guia completo de prompts do Ray 3.2: 5 casos de texto para vídeo + 3 de imagem para vídeo
• Documentação de integração do Ray 3.2 em chinês: todos os parâmetros e códigos de erro

Teste agora: clique em Gerar com este prompt → abaixo do vídeo do farol acima; o prompt já vem preenchido, escolha 5 segundos, 540p, 21:9 e clique para obter o mesmo resultado.