Ray 3.2 API 怎么用？5 分钟跑通第一条视频

TL;DR

它是什么：Luma AI 的 Ray 3.2，在 HiAPI 分成两条线路：ray-3.2/text-to-video 只吃提示词，ray-3.2/image-to-video 用首帧（可选尾帧）驱动。已在 HiAPI 上线，打开文生视频模型页就能生成，新用户注册送 200 积分。
多少钱：按条计费，5 秒 540p $0.2145、720p $0.429、1080p $1.7145；10 秒只有文生视频有，540p $0.643、720p $1.286、1080p $5.143。失败自动退款。
API 怎么调：POST https://api.hiapi.ai/v1/tasks，model 填对应线路，拿到 taskId 后轮询或等 callback.url，从 data.output[0].url 下载静音 MP4。

Ray 3.2 的输出是无声 MP4。文生视频可以在请求里选时长和画幅；图生视频固定 5 秒，画幅跟随首帧。下面从在线试用到 curl、Python、图生视频和上线注意事项，一次走完。

Ray 3.2 是什么？两条线路怎么选

文生视频：只传 prompt，可选 duration（5 或 10 秒）、resolution（540p / 720p / 1080p）、aspect_ratio（16:9、9:16、1:1、4:3、3:4、21:9）。提示词最长 6000 字符。
图生视频：必填 prompt 和首帧 image_url，可选尾帧 end_image_url、resolution。每条固定 5 秒，画幅跟随首帧，自动匹配到最接近的支持比例。
共同点：都走 /v1/tasks，都按条计费，都输出不带音轨的 MP4。

文生视频适合只有文字构想、需要 10 秒或指定画幅的镜头；图生视频适合已经有产品图、海报、概念图，或者要锁定结尾画面。两条线路共有的 5 秒三档同价，10 秒只属于文生视频。

Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.

用这个提示词生成 →，画幅选 21:9，540p 一条 $0.2145。

两条上手路线：在线试用还是 API？

在线试用（约 1 分钟）

打开 Ray 3.2 文生视频模型页，或点上面那条预填链接。
注册或登录，新账号自带 200 积分；一条 5 秒 540p 扣 429 积分，充值后即可生成。
写提示词，选时长、分辨率和画幅，点运行。
成片满意后下载；需要 API 时再去控制台建 Key。

API 接入（约 5 分钟）

在 HiAPI 控制台创建 API Key（sk-...）。
POST /v1/tasks 创建任务，响应里拿到 data.taskId。
用 GET /v1/tasks/{id} 查询，或在请求体顶层带 callback.url 等通知。
data.status 变成 success 后，从 data.output[0].url 下载视频。

5 秒 540p 一条 $0.2145，$10 能跑约 46 条，足够把一组镜头的动作试清楚。去模型页试第一条 →

第一条视频：curl 版

创建文生视频任务：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/text-to-video",
    "input": {
      "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
      "duration": 5,
      "resolution": "540p",
      "aspect_ratio": "21:9"
    }
  }'

返回的任务 ID 在 data.taskId：

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

查询结果：

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

必填的只有 prompt。duration 默认 5，resolution 默认 540p，aspect_ratio 默认 16:9。三个字段都做严格校验，传错值直接 400，不会自动取整。

第一条视频：Python 版

创建、轮询、下载一次写完：

import time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "ray-3.2/text-to-video",
    "input": {
        "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
        "duration": 5,
        "resolution": "540p",
        "aspect_ratio": "21:9",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    video_url = task["output"][0]["url"]
    with open("ray32-clip.mp4", "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
else:
    print(task.get("error"))

视频任务通常要几十秒到几分钟，轮询间隔给 5 秒，超时上限留 10–15 分钟。输出链接会过期，拿到后立刻下载并存到自己的存储。

图生视频：加一张首帧，或者首尾帧

把 model 换成 ray-3.2/image-to-video，加上首帧 image_url，同一个请求就变成图生视频：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/image-to-video",
    "input": {
      "prompt": "The ribbon of milk keeps folding down through the iced espresso, the ice cubes settle and shift slightly, condensation beads slide down the outside of the glass, very slow push-in toward the glass, warm rim light stays steady, vertical product commercial shot",
      "image_url": "https://www.hiapi.ai/images/model-pages/ray-3-2/iced-coffee-first.jpg",
      "resolution": "1080p"
    }
  }'

要固定结尾画面，再加 end_image_url。首帧和尾帧的机位、光线、主体位置越接近，过渡越稳；两张图取景不同时，模型会自己加一段镜头移动去衔接。两个字段都不影响价格。

图生视频没有 duration 和 aspect_ratio：每条固定 5 秒，画幅按首帧匹配到 16:9、9:16、1:1、4:3、3:4、21:9 中最接近的一种，比例不一致时边缘会被裁掉。想让输出比例完全可控，先把首帧裁成这六种比例之一。

上线前注意这 3 件事

服务端用回调。 请求体顶层加 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}，任务进入终态自动通知，省掉轮询。success 和 fail 都会回调，服务端按 taskId 做幂等。
超时别重复 POST。 每次 POST 都会新建任务、单独计费。先存下 taskId，重试前在自己系统里去重；进程崩了就从存下的 id 继续查。
每个请求显式写参数。 resolution 直接决定单价，duration 只收整数 5 或 10，图生视频不要带 duration 和 aspect_ratio。写死在请求里，账单和行为才可预期。

常见报错，一行一个

400 INVALID_REQUEST，resolution 取值不对 → 只接受 540p、720p、1080p，没有 2k、480p。
400，duration 取值不对 → 只接受整数 5 和 10；传字符串 "5" 或数字 7 都会失败。
400 additional properties 'aspect_ratio' not allowed → 图生视频没有这个字段，删掉；文生视频才支持。
401 permission_denied → Key 缺失、写错或已撤销，检查 Authorization: Bearer sk-...。
创建返回 200，任务后来 fail → 通常是图生视频的 image_url 打不开或不是图片。创建时只校验字段形状，不校验 URL 是否可访问。
链接过几天打不开 → 输出 URL 有有效期，拿到后立刻下载。