Luma Ray 3.2 Image to Video API

Q: 如何计费?

以 HiAPI 定价页的实时价格为准。

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

图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称	ray-3.2/image-to-video
类型	视频生成（图生视频）
接口	POST /v1/tasks
价格	见 HiAPI 定价

Luma Ray 3.2 图生视频：以首帧图（可选尾帧图）生成 5 秒电影感短片，支持 540p、720p、1080p，画面比例按首帧自动匹配到最接近的支持画幅。

生产建议

生产环境建议

生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
callback.when 当前建议固定为 final；success 和 fail 都可能触发终态通知，你的服务端需要按 taskId 做幂等处理。

适用场景

电影感运镜

以已有图片为首帧，用提示词描述镜头运动与场景变化。

image_urlprompt

首尾帧过渡

同时提供首帧与尾帧，生成从起始画面到目标画面的过渡视频。

image_urlend_image_url

三档分辨率

在 540p、720p、1080p 之间选择输出清晰度。

resolution

请求参数

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

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
# 把 YOUR_API_KEY 换成你的账号 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/image-to-video",
  "input": {
    "prompt": "The shooting star streaks across the Milky Way as the camera slowly cranes down toward the glowing tent, desert sand ripples shimmer in the lantern light, cinematic night timelapse feel",
    "image_url": "https://static.hiapi.ai/previews/nano-banana-2-lite/2026/07/03/1783076316176-b9c9c7b278a01155-nano-lite-g2-desert.webp",
    "resolution": "720p"
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "ray-3.2/image-to-video",
  "input": {
    "prompt": "The shooting star streaks across the Milky Way as the camera slowly cranes down toward the glowing tent, desert sand ripples shimmer in the lantern light, cinematic night timelapse feel",
    "image_url": "https://static.hiapi.ai/previews/nano-banana-2-lite/2026/07/03/1783076316176-b9c9c7b278a01155-nano-lite-g2-desert.webp",
    "resolution": "720p"
  }
}
''')

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # 成功返回 { code, message, data: { taskId } }

// 提交异步任务，成功立即返回 taskId（不等待生成完成）
// 把 YOUR_API_KEY 换成你的账号 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/image-to-video",
  "input": {
    "prompt": "The shooting star streaks across the Milky Way as the camera slowly cranes down toward the glowing tent, desert sand ripples shimmer in the lantern light, cinematic night timelapse feel",
    "image_url": "https://static.hiapi.ai/previews/nano-banana-2-lite/2026/07/03/1783076316176-b9c9c7b278a01155-nano-lite-g2-desert.webp",
    "resolution": "720p"
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

model string 必填

固定填 ray-3.2/image-to-video。

示例 ray-3.2/image-to-video

input object 必填

业务参数对象；Luma Ray 3.2 Image to Video 的模型专属配置都放在这里。

prompt string 必填

描述基于图片要生成的运动、镜头与场景变化；长度 1–6000 个字符。

image_url string 必填

用作视频首帧的公开图片 URL；输出画面比例按这张图片自动匹配到最接近的支持画幅（16:9、9:16、1:1、4:3、3:4、21:9），画面可能有裁切。

end_image_url string 可选

用作视频尾帧的公开图片 URL；传入后视频从首帧过渡到这一帧。

resolution enum 可选

输出视频分辨率，可选 540p、720p、1080p；每条视频固定 5 秒。

默认 540p 可选值: 540p720p1080p

callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback

when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

用例示例

沙漠星夜营地

首帧图驱动、720p 的 5 秒图生视频示例。

请求体

{
  "model": "ray-3.2/image-to-video",
  "input": {
    "prompt": "The shooting star streaks across the Milky Way as the camera slowly cranes down toward the glowing tent, desert sand ripples shimmer in the lantern light, cinematic night timelapse feel",
    "image_url": "https://static.hiapi.ai/previews/nano-banana-2-lite/2026/07/03/1783076316176-b9c9c7b278a01155-nano-lite-g2-desert.webp",
    "resolution": "720p"
  }
}

获取结果

提交成功后立即返回 taskId（不等待生成完成）。
生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
status=success 后，从返回的 output[].url 下载生成的视频。
如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

可以设置视频时长或画面比例吗?

不可以。每条视频固定 5 秒；画面比例由 image_url 首帧图决定，会自动匹配到最接近的支持画幅（16:9、9:16、1:1、4:3、3:4、21:9），比例不完全一致时画面会有裁切，因此没有 duration 和 aspect_ratio 参数。

首尾帧怎么用?

用 image_url 传首帧，再用可选的 end_image_url 传尾帧，视频会从首帧过渡到尾帧；不传 end_image_url 时只以首帧为起点生成。

如何计费?

以 HiAPI 定价页的实时价格为准。查看价格