Luma

Ray 3.2

ray-3.2/image-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

ray-3.2/image-to-video ray-3.2/text-to-video

Pricing

ray-3.2/image-to-video per video

Specifications	Unit Price
540P	$0.2145
720P	$0.429
1080P	$1.7145

Overview

The Ray 3.2 image-to-video model uses a public image as the first frame and, together with a text description, generates a cinematic short clip; the output aspect ratio automatically follows that of the first-frame image. An optional last-frame image is supported, letting the visuals transition from the first frame to a specified endpoint; resolution options are 540p, 720p, and 1080p, and the finished piece is a 5-second clip. It is suited to developers and creative teams who need to extend a shot from a single keyframe, produce concept previews, or create atmospheric establishing shots.

Key Highlights

Two-way first/last frame control — you can provide only the first frame, or add a last-frame image so the video converges on a specified endpoint, making the shot's direction more controllable.
Aspect ratio automatically follows the first frame — the output ratio is determined by the first-frame image, matching the composition of existing assets without extra settings.
Three resolution options — choose 540p, 720p, or 1080p as needed, making it easy to allocate cost between previews and final output.

Capabilities

First-frame-driven image-to-video: pass a public image URL as the first frame, then describe the motion and scene with a prompt to get a 5-second video starting from that image.

Last-frame transition constraint: optionally pass an ending-frame image, and the model generates the transition from the first frame to the last frame, which is well suited to controlling where the shot lands and how the visuals resolve.

Structured prompt responsiveness: responds more reliably to concrete, structured descriptions of motion and camera work; prompts can be up to 6000 characters, accommodating fairly complete shot instructions.

Resolution and aspect ratio control: output resolution can be 540p, 720p, or 1080p, and the aspect ratio inherits that of the first-frame image, reducing the need for secondary cropping in post-production.

Use Cases

Concept preview: single keyframe + shot description — extend a concept image or storyboard keyframe into a 5-second short shot for dynamic previews during film and advertising pitch stages.
Atmospheric establishing shots: scene image + environment motion description — turn a static scene image into environment-type footage for use as background screens, transitions, or mood setting.
First/last frame connection: two images, start and end — given a starting and an ending image, generate the transition segment between them for shot continuity and pacing control.
Marketing clips: product image + motion prompt — use a product image as the first frame to generate short dynamic assets for rapid production of social and marketing content.

Limitations and Selection Advice

Each generation is fixed at a 5-second clip, with no support for longer durations; resolution tops out at 1080p, so it is not suitable for long takes or direct high-resolution master output. Results depend on concrete, structured descriptions of motion and scene, and performance degrades with vague instructions; temporal consistency and motion quality are also not its strengths. If you need video generated directly from text, consider a text-to-video model from the same series; if you need longer finished durations, evaluate other options separately. Billing is per video.

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

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

Headers

AuthorizationstringRequired

Account API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key

Content-TypestringOptional

The 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-KeystringOptional

Idempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.

Idempotency key

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

modelstringRequired

Current fixed value: ray-3.2/image-to-video

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for ray-3.2/image-to-video and route default — see the parameter table below.

promptstringRequiredminLength 1maxLength 6000

Text prompt describing the motion and scene content you want generated based on the input image.

image_urlstringRequired

Public image URL to use as the first frame of the video; the output video's aspect ratio matches this image.

resolutionstringOptionalDefault: "540p"

Output video resolution, defaults to 540p; each video segment is 5 seconds long.

Options:540p720p1080p

end_image_urlstringOptional

Optional public image URL to use as the last frame of the video; the video will transition from the first frame to this frame.

callbackobjectOptional

Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.

Callbacks (Webhook)

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.

urlstringRequired

Required 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.

Options:final

storagestringOptionalDefault: "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.

Options:temppersistent

Request 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/image-to-video",
  "input": {
    "prompt": "…",
    "image_url": "…",
    "resolution": "540p"
  }
}'

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/image-to-video",
    input: {
      "prompt": "…",
      "image_url": "…",
      "resolution": "540p"
    }
  }),
});
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/image-to-video",
        "input": {
          "prompt": "…",
          "image_url": "…",
          "resolution": "540p"
        }
    },
)
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

GET https://api.hiapi.ai/v1/tasks/:id

Response fields

taskIdstringRequired

Task ID, always prefixed with tk-hiapi-.

modelstringRequired

Resolved 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.

routestringOptional

Present only when the task was submitted with an explicit route parameter; echoes the submitted value.

statusstringRequired

Task status.

Status values

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.

creatednumberRequired

Task creation time (Unix seconds).

completednumberRequired

Unix 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

urlstringRequired

Artifact URL, directly downloadable.

typestringRequired

Current possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.

expireAtnumberRequired

Unix seconds until which the artifact remains accessible; download or transfer before it expires.

errorobjectOptional

Present only when status == fail.

codestringRequired

Business error code.

messagestringRequired

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