Luma

Ray 3.2

ray-3.2/image-to-video

Luma 电影感视频生成模型，原生支持 HDR 与 EXR 导出，适合氛围空镜与广告、影视前期概念片，结构化镜头指令下提示遵循稳定

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

价格

ray-3.2/image-to-video 每条

规格	单价
540P	$0.2145
720P	$0.429
1080P	$1.7145

定位简介

Ray 3.2 图生视频模型以一张公开图片作为首帧，配合文字描述生成电影感短片，输出画幅自动跟随首帧图片比例。支持可选尾帧图片，让画面从首帧过渡到指定终点；分辨率可选 540p、720p、1080p，成品为 5 秒片段。适合需要从单张关键帧延展镜头、制作概念预演或氛围空镜的开发者与创作团队。

核心亮点

首尾帧双向控制——可只给首帧，也可补一张尾帧图片，让视频按指定终点收束，镜头走向更可控。
画幅自动跟随首帧——输出比例由首帧图片决定，无需额外设置即可匹配已有素材的构图。
三档分辨率可选——540p、720p、1080p 按需选择，便于在预览与成片之间分配成本。

能力说明

首帧驱动的图生视频：传入公开图片 URL 作为第一帧，再用提示词描述运动与场景，即可得到以该图为起点的 5 秒视频。

尾帧过渡约束：可选传入结束帧图片，模型生成从首帧到尾帧的过渡过程，适合控制镜头落点与画面收束。

结构化提示词响应：对具体、结构化的运动与镜头描述响应更稳定，提示词上限 6000 字符，可容纳较完整的镜头说明。

分辨率与画幅控制：输出分辨率可选 540p、720p、1080p，画幅比例继承首帧图片，减少后期二次裁切。

适用场景

概念预演：单张关键帧 + 镜头描述——从概念图或分镜关键帧延展为 5 秒短镜头，用于影视、广告提案阶段的动态预演。
氛围空镜：场景图 + 环境运动描述——将静态场景图转为环境类镜头素材，用作背景屏、转场或氛围铺垫。
首尾帧衔接：起止两张图——给定起始与结束画面，生成两者之间的过渡片段，用于镜头衔接与节奏控制。
营销短片：产品图 + 运动提示词——以产品图片为首帧生成短动态素材，用于社交与营销内容的快速产出。

限制与选型建议

单次生成固定为 5 秒片段，不支持更长时长；分辨率上限 1080p，不适合长镜头或高分辨率母版直出。效果依赖具体、结构化的运动与场景描述，模糊指令下表现会下降，时序一致性与运动质量也不是其强项。若需要文本直接生成视频，可选用同系列的文生视频型号；若追求更长的成片时长，需另行评估。计费按每条视频计。

常见问题

查看全部常见问题 →

Ray 3.2 图生视频需要哪些输入？

必填两项：prompt（1–6000 个字符）和首帧 image_url。可选 end_image_url 作为尾帧，以及 resolution（540p、720p、1080p，默认 540p）。在 Playground 里可以直接上传本地图片。
可以设置视频时长吗？

不可以。图生视频每条固定 5 秒，请求里没有 duration 参数。需要 10 秒的镜头时，可以改用 Ray 3.2 文生视频，它支持 5 秒和 10 秒。
输出的画面比例由什么决定？

由首帧决定，没有 aspect_ratio 参数。输出会匹配到 16:9、9:16、1:1、4:3、3:4、21:9 中最接近的一种，比例不完全一致时边缘会被裁掉。本页的沙漠案例原图约 3:2（1024×687），输出为 4:3 的 1104×832；冰咖啡案例原图是 9:16，输出为 9:16 的竖屏视频，基本没有裁切。想让输出比例完全可控，就把首帧先裁成这六种比例之一。
首尾帧怎么用？

image_url 传首帧，end_image_url 传尾帧，视频会从首帧过渡到尾帧，提示词只需描述中间发生的变化。两张图的机位、光线和主体位置越接近，过渡越平稳；取景不同时模型会加入镜头移动去衔接，本页牡丹案例就是这种情况。

提交生成任务

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

请求头

Authorizationstring必填

账号 API Key，所有请求必填。示例：Bearer YOUR_HIAPI_API_KEY。获取 API Key

Content-Typestring可选

请求体固定按 JSON 解析；如携带，仅接受 application/json（可带 charset），其他取值返回 415。示例：application/json。

Idempotency-Keystring可选

幂等键，最长 255 字节。同账户同键的重试只创建一次任务，重放返回首次 taskId。

幂等键

网络超时或客户端自动重试时，同键只创建一次任务、不会重复扣费（幂等范围 = API Key 所属账户）。建议用业务侧唯一标识做键（如 "order-42"）；同键重放返回首次 taskId，键在首次提交 24 小时后过期。详细的场景矩阵见统一异步接口介绍页。

请求体

modelstring必填

当前固定值：ray-3.2/image-to-video

routestring可选

当前固定值：default

inputobject必填

ray-3.2/image-to-video 和线路 default 的业务参数对象，见下方参数表。

promptstring必填minLength 1maxLength 6000

文本提示词，描述希望基于输入图像生成的动态与场景内容。

image_urlstring必填

作为视频首帧的公开图像 URL，输出视频的画幅比例与该图像保持一致。

resolutionstring可选默认值: "540p"

输出视频分辨率，默认 540p；每段视频时长为 5 秒。

可选项：540p720p1080p

end_image_urlstring可选

可选的公开图像 URL，用作视频尾帧；视频将从首帧过渡到该帧。

callbackobject可选

终态通知配置；为空则不回调，由调用方自行查询。详见下方回调说明。

回调（Webhook）

创建任务时提供 callback.url，任务终态时 HiAPI 主动 POST 通知你的服务，可免去轮询。回调请求体与任务详情数据结构同构；签名校验、投递重试与幂等说明见统一异步接口介绍页的回调说明。

urlstring必填

callback 存在时必填；任务终态后向该 URL 发起 POST，须为合法 http(s) URL。

whenstring可选默认值: "final"

当前仅支持 final，即 success / fail 均回调。

可选项：final

storagestring可选默认值: "temp"

产物存储档位：temp（默认，保留约 7 天）或 persistent（长期保存，按大小计费）。余额不足或超出存储上限会静默降级为 temp；实际生效档位见任务详情响应。

可选项：temppersistent

请求示例

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
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 https://api.hiapi.ai/v1/tasks/:id

响应字段

taskIdstring必填

任务 ID，前缀固定 tk-hiapi-。

modelstring必填

解析后的模型全名。用 route 参数提交的任务返回 base@线路（如 gpt-image-2/text-to-image@ext）；否则与创建时传入的模型名一致。

routestring可选

仅当任务用显式 route 参数提交时出现，回显提交时的原值。

statusstring必填

任务状态。

状态枚举

queued 已入队，尚未开始。 handling 处理中。 archiving 处理完成，产物准备中。 success 终态：完成，产物可用（返回 output）。 fail 终态：失败（返回 error）。提交后按 status 判断：success 或 fail 为终态，其余为非终态，建议按 1~3 秒间隔轮询直至终态。成功终态后从 output[].url 下载产物，并在 expireAt 前完成下载或转存；需要长期保留时在创建任务时使用 storage: "persistent"。

creatednumber必填

任务创建时间（Unix 秒）。

completednumber必填

进入终态的 Unix 秒；非终态固定为 0。

outputarray可选

仅 status == success 时出现。产物列表，始终为数组，同一任务可能同时返回多个 type（如 video + first_frame）。

Array [ object ]

数组元素

urlstring必填

资源 URL，可直接下载。

typestring必填

当前可能值：video、image、audio、first_frame、last_frame、thumbnail，后续可能会扩展。

expireAtnumber必填

资源可访问截止时间（Unix 秒）；过期前请完成下载或转存。

errorobject可选

仅 status == fail 时出现。

codestring必填

业务错误码。

messagestring必填

错误描述。

响应示例

成功

{
  "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
      }
    ]
  }
}

处理中（非终态）

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

失败

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