Luma
Ray 3.2
ray-3.2/text-to-video
Luma's cinematic video generation model, with native support for HDR and EXR export, suited to atmospheric establishing shots, advertising, and early-stage concept films for film and television; prompt adherence is stable under structured shot instructions
Pricing
ray-3.2/text-to-video per video
| Specifications | Unit Price |
|---|---|
| 540P | $0.2145 |
| 720P | $0.429 |
| 1080P | $1.7145 |
Overview
Ray 3.2 is Luma's text-to-video model for cinematic short clips. With just a text prompt, it generates 5-second or 10-second clips at 540p, 720p, or 1080p, and supports six aspect ratios: 16:9, 9:16, 1:1, 4:3, 3:4, and 21:9. It responds reliably to structured, specific shot and subject descriptions, and performs especially well on atmospheric, environment-focused shots. It suits developers and creative teams that need to quickly produce concept films, storyboard previews, and social short videos, and can be integrated into generation workflows by calling it through the unified HiAPI.ai API.
Key Highlights
- Shot-level description control — It follows structured, specific shot blocking and subject descriptions closely, while results degrade under vague, open-ended instructions.
- Cinematic visual style tuning — Its visual style and physical realism lean cinematic, making it well suited to atmospheric empty shots and environment footage.
- Multiple aspect ratios and resolutions — Output supports six ratios spanning landscape, portrait, square, and widescreen, at resolutions up to 1080p and durations of 5 or 10 seconds.
Capabilities
Direct text-to-video generation: Enter a prompt of up to 6,000 characters to produce a short clip with no source footage required, ideal for quickly validating shot ideas from scratch.
Selectable duration and resolution: Clip duration can be 5 or 10 seconds, and resolution covers 540p, 720p, and 1080p, so you can choose specs separately for draft and final-output stages.
Six aspect ratios in one model: It supports 16:9, 9:16, 1:1, 4:3, 3:4, and 21:9, so the same prompt can directly produce landscape, portrait, or widescreen versions to fit different placements.
Cinematic and atmospheric shots: Its visual style and physical realism lean cinematic, and it is relatively stable on environment shots such as atmospheric empty shots and scene backgrounds.
Use Cases
- Film or advertising teams creating concept films and storyboard previews — Describe shot blocking and scene atmosphere in text to produce 5- to 10-second clips as early-stage visual references for creative and client discussions.
- Content teams generating atmospheric empty shots and background assets — Describe lighting, environment, and mood to produce environment shot assets for transitions, background screens, and atmosphere building in video editing.
- Marketers quickly producing social short videos — Choose portrait or landscape aspect ratios by placement and directly generate 5- to 10-second clips suited to each platform for social media and ad placements.
- Developers generating shot assets in batches — Submit generation tasks in batches by prompt through the unified HiAPI.ai API and feed shot assets into your own content production or asset library workflows.
Limitations and Selection Advice
Clips are capped at 10 seconds and 1080p, so it is not suited to long takes or direct high-resolution master output. Third-party evaluations show that temporal consistency and motion quality are not its strongest areas, and shots with continuous motion or multiple interacting subjects require multiple generation rounds and filtering. Results depend on structured, specific prompts, and performance degrades under vague or open-ended instructions. If your needs involve long-form narrative, fine-grained motion control, or image-driven generation, evaluate other models or combine this with an image-to-video pipeline.
Frequently asked questions
View all FAQs →-
What inputs does Ray 3.2 image-to-video need?
Two are required: prompt (1–6000 characters) and the first frame image_url. Optional are end_image_url as the last frame and resolution (540p, 720p or 1080p, default 540p). In the Playground you can upload a local image directly.
-
Can I set the video length?
No. Every image-to-video clip is 5 seconds and the request has no duration field. For a 10-second shot, use Ray 3.2 text-to-video, which supports 5 and 10 seconds.
-
What decides the output aspect ratio?
The first frame; there is no aspect_ratio field. The output snaps to the closest of 16:9, 9:16, 1:1, 4:3, 3:4 and 21:9, trimming the edges when the ratios differ. The desert example here starts from a roughly 3:2 image (1024×687) and comes back at 4:3, 1104×832; the iced espresso example starts from a 9:16 image and stays 9:16 with virtually nothing trimmed. To control the ratio exactly, crop the first frame to one of those six ratios first.
-
How do first and last frames work?
Pass the first frame in image_url and the last in end_image_url; the video moves from one to the other, so the prompt only needs to describe the change in between. The closer the two images are in camera position, light and subject placement, the smoother the transition; when the framing differs the model adds camera movement to bridge it, as in the peony example here.
Create a generation task
https://api.hiapi.ai/v1/tasks Headers
AuthorizationstringRequiredAccount API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key
Content-TypestringOptionalThe request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.
Idempotency-KeystringOptionalIdempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.
On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.
Body
modelstringRequiredCurrent fixed value: ray-3.2/text-to-video
routestringOptionalCurrent fixed value: default
inputobjectRequired
Business parameters for ray-3.2/text-to-video and route default — see the parameter table below.
promptstringRequiredminLength 1maxLength 6000Text prompt describing the video content to be generated; takes a string value, and should use natural language to explain elements such as the main subject, scene, and actions.
durationintegerOptionalDefault: 5Controls the duration of the generated video; takes an integer number of seconds, either 5 seconds or 10 seconds, defaulting to 5 seconds.
510resolutionstringOptionalDefault: "540p"Controls the resolution of the output video; takes a string value, defaulting to 540p.
540p720p1080paspect_ratiostringOptionalDefault: "16:9"Controls the aspect ratio of the output video; takes a string value, defaulting to 16:9.
16:99:161:14:33:421:9callbackobjectOptional
Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.
Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.
urlstringRequiredRequired when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.
whenstringOptionalDefault: "final"Only final is supported today — notified on both success and fail.
finalstoragestringOptionalDefault: "temp"Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.
temppersistentRequest examples
# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ray-3.2/text-to-video",
"input": {
"prompt": "…",
"duration": 5,
"resolution": "540p",
"aspect_ratio": "16:9"
}
}' const res = await fetch("https://api.hiapi.ai/v1/tasks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "ray-3.2/text-to-video",
input: {
"prompt": "…",
"duration": 5,
"resolution": "540p",
"aspect_ratio": "16:9"
}
}),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } } import os, requests
res = requests.post(
"https://api.hiapi.ai/v1/tasks",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "ray-3.2/text-to-video",
"input": {
"prompt": "…",
"duration": 5,
"resolution": "540p",
"aspect_ratio": "16:9"
}
},
)
print(res.json()) # { code, message, data: { taskId } } 200 OK
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
}
} 400 Bad Request
{
"code": 400,
"message": "invalid request",
"data": null,
"error_code": "INVALID_REQUEST"
} Get task detail
https://api.hiapi.ai/v1/tasks/:id Response fields
taskIdstringRequiredTask ID, always prefixed with tk-hiapi-.
modelstringRequiredResolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.
routestringOptionalPresent only when the task was submitted with an explicit route parameter; echoes the submitted value.
statusstringRequiredTask status.
queued Queued, not started yet.
handling Being processed.
archiving Processing finished, artifacts being prepared.
success Terminal: completed, artifacts available (output returned).
fail Terminal: failed (error returned).
After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.
creatednumberRequiredTask creation time (Unix seconds).
completednumberRequiredUnix seconds when the task reached a terminal state; fixed to 0 while not terminal.
outputarrayOptional
Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).
Array [ object ]
Array items
urlstringRequiredArtifact URL, directly downloadable.
typestringRequiredCurrent possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.
expireAtnumberRequiredUnix seconds until which the artifact remains accessible; download or transfer before it expires.
errorobjectOptional
Present only when status == fail.
codestringRequiredBusiness error code.
messagestringRequiredError description.
Response examples
Success
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
"model": "happyhorse-1-0",
"status": "success",
"created": 1777282033,
"completed": 1777282099,
"output": [
{
"url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
"type": "video",
"expireAt": 1777886899
}
]
}
} Processing (non-terminal)
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "archiving",
"created": 1777282033,
"completed": 0
}
} Failed
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "fail",
"created": 1777282033,
"completed": 1777282099,
"error": {
"code": "TASK_FAILED",
"message": "task failed"
}
}
} Articles
View all articles →Related Models
View all models →Same Type
-
Gemini Omni Google -- -
Creatify Boreal Creatify $0.015 /second -
Veo 3.1 Fast Google $0.170 /second -
Veo 3.1 Google $0.290 /second -
Wan 2.7 Video Alibaba $0.100 /second -
LTX 2.5 Fast Lightricks $0.086 /second -
HappyHorse 1.1 Alibaba $0.160 /second -
Kling 4.0 Kuaishou $0.330 /second -
Grok Imagine 1.5 xAI $0.011 /second -
Grok Imagine 1.5 Lite xAI $0.029 /second -
Hailuo 2.3 MiniMax $0.270 /video -
Ray 3.2 Luma $0.214 /video