Luma Ray 3.2 Text to Video API

POST Base URL: https://api.hiapi.ai /v1/tasks

Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name	ray-3.2/text-to-video
Type	Video generation (text-to-video)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

Luma Ray 3.2 text-to-video turns a prompt into a 5- or 10-second cinematic clip at 540p, 720p, or 1080p in six aspect ratios.

Production guidance

For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

Cinematic short clips

Describe the scene, subject motion, and camera movement in the prompt to generate a video directly.

prompt

Multi-platform framing

Six aspect ratios covering landscape, portrait, square, and ultra-wide for different publishing channels.

aspect_ratio

Length and resolution

Choose 5 or 10 seconds, and 540p, 720p, or 1080p output.

durationresolution

Request parameters

POST https://api.hiapi.ai/v1/tasks

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ray-3.2/text-to-video",
  "input": {
    "prompt": "A lone lighthouse keeper climbs the spiral stairs at dusk, storm waves crash against the rocks below, the beam sweeps across the sea, slow cinematic crane shot",
    "aspect_ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "ray-3.2/text-to-video",
  "input": {
    "prompt": "A lone lighthouse keeper climbs the spiral stairs at dusk, storm waves crash against the rocks below, the beam sweeps across the sea, slow cinematic crane shot",
    "aspect_ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "ray-3.2/text-to-video",
  "input": {
    "prompt": "A lone lighthouse keeper climbs the spiral stairs at dusk, storm waves crash against the rocks below, the beam sweeps across the sea, slow cinematic crane shot",
    "aspect_ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Fixed value ray-3.2/text-to-video.

example ray-3.2/text-to-video

input object required

Business parameters. Put Luma Ray 3.2 Text to Video-specific configuration here.

prompt string required

Describes the scene, subject motion, and camera movement of the video to generate. 1–6000 characters.

duration integer optional

Video length in seconds: 5 or 10.

default 5 enum: 510

resolution enum optional

Output video resolution: 540p, 720p, or 1080p.

default 540p enum: 540p720p1080p

aspect_ratio enum optional

Output video aspect ratio: 16:9, 9:16, 1:1, 4:3, 3:4, or 21:9.

default 16:9 enum: 16:99:161:14:33:421:9

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

Storm lighthouse keeper

Text-to-video example: a 5-second 16:9 clip at 720p.

Request body

{
  "model": "ray-3.2/text-to-video",
  "input": {
    "prompt": "A lone lighthouse keeper climbs the spiral stairs at dusk, storm waves crash against the rocks below, the beam sweeps across the sea, slow cinematic crane shot",
    "aspect_ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }
}

Getting the result

The response returns a taskId immediately without waiting for generation to finish.
In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
When status=success, download the generated video from output[].url.
When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

Which durations and aspect ratios are available?

duration accepts 5 or 10 seconds; aspect_ratio accepts 16:9, 9:16, 1:1, 4:3, 3:4, or 21:9.

Can I pass a reference image?

No. Text-to-video accepts only a text prompt. To use an image as the first or last frame, use ray-3.2/image-to-video.

How is it billed?

See the live prices on the HiAPI pricing page. View pricing