チュートリアル

Ray 3.2 API の使い方：5 分で最初の動画を生成

オンライン試用 4 ステップ、API 連携 4 ステップ。すぐ実行できる curl と Python、始点・終点フレームの書き方、公開時の注意点付き。

Oct 21, 2026

モデル: ray-3.2

TL;DR

これは何か：Luma AI の Ray 3.2 は HiAPI で 2 つのルートに分かれています。ray-3.2/text-to-video はプロンプトのみ、ray-3.2/image-to-video は始点フレーム（任意で終点フレーム）で駆動します。HiAPI で提供中で、テキストtoビデオモデルページを開くだけで生成できます。新規ユーザー登録で 200 クレジットを進呈。
料金：本数課金で、5 秒 540p は $0.2145、720p は $0.429、1080p は $1.7145。10 秒はテキストtoビデオのみで、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 です。テキストtoビデオはリクエストで長さとアスペクト比を選べます。画像toビデオは 5 秒固定で、アスペクト比は始点フレームに従います。以下ではオンライン試用から curl、Python、画像toビデオ、公開時の注意点までを一気に解説します。

Ray 3.2 とは？2 つのルートの選び方

テキストtoビデオ：prompt のみを送信し、任意で duration（5 または 10 秒）、resolution（540p / 720p / 1080p）、aspect_ratio（16:9、9:16、1:1、4:3、3:4、21:9）を指定可能。プロンプトは最大 6000 文字。
画像toビデオ：prompt と始点フレーム image_url が必須で、任意で終点フレーム end_image_url、resolution を指定可能。各本 5 秒固定で、アスペクト比は始点フレームに従い、最も近い対応比率に自動マッチします。
共通点：いずれも /v1/tasks を使用し、本数課金で、音声トラックなしの MP4 を出力します。

テキストtoビデオは文字だけの構想があり、10 秒や指定アスペクト比が必要なカットに向いています。画像toビデオは製品画像、ポスター、コンセプト画像が既にある場合や、ラストカットを固定したい場合に向いています。両ルート共通の 5 秒 3 段階は同価格で、10 秒はテキストtoビデオのみです。

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 で 1 本 $0.2145。

2 つの導入ルート：オンライン試用か API か？

オンライン試用（約 1 分）

Ray 3.2 テキストtoビデオモデルページを開くか、上のプリフィルリンクをクリック。
登録またはログイン。新規アカウントには 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 は 1 本 $0.2145、$10 で約 46 本生成でき、1 組のカットの動きを試すには十分です。モデルページで最初の 1 本を試す →

最初の動画：curl 版

テキストtoビデオタスクを作成：

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。3 つのフィールドはすべて厳格に検証され、誤った値を渡すと即 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 分確保してください。出力リンクは期限切れになるので、取得後すぐにダウンロードして自社ストレージに保存しましょう。

画像toビデオ：始点フレーム、または始点・終点フレームを追加

model を ray-3.2/image-to-video に変え、始点フレーム image_url を加えると、同じリクエストが画像toビデオになります：

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 を追加します。始点と終点のカメラ位置、光、被写体位置が近いほど遷移が安定します。2 枚の構図が異なる場合、モデルが自動でカメラ移動を加えてつなぎます。どちらのフィールドも価格には影響しません。

画像toビデオには duration と aspect_ratio はありません。各本 5 秒固定で、アスペクト比は始点フレームから 16:9、9:16、1:1、4:3、3:4、21:9 のうち最も近いものにマッチし、比率が一致しない場合は端がクロップされます。出力比率を完全に制御したい場合は、始点フレームをあらかじめこの 6 つの比率のいずれかにクロップしてください。

公開前の 3 つの注意点

サーバー側ではコールバックを使う。 リクエストボディのトップレベルに "callback": {"url": "https://yourapp.com/webhook", "when": "final"} を加えると、タスクが終態に入ると自動通知され、ポーリングを省けます。success と fail の両方がコールバックされるため、サーバー側では taskId で冪等化します。
タイムアウト時に POST を繰り返さない。 POST のたびにタスクが新規作成され、個別に課金されます。まず taskId を保存し、リトライ前に自システムで重複排除。プロセスが落ちた場合は保存した id から照会を再開します。
各リクエストでパラメータを明示的に書く。 resolution は単価を直接左右し、duration は整数 5 または 10 のみ受け付け、画像toビデオには duration と aspect_ratio を含めない。リクエストにハードコードしておくことで、請求と挙動が予測可能になります。

よくあるエラー、1 行ずつ

400 INVALID_REQUEST、resolution の値が不正 → 540p、720p、1080p のみ受け付け、2k、480p はありません。
400、duration の値が不正 → 整数 5 と 10 のみ受け付け。文字列 "5" や数値 7 は失敗します。
400 additional properties 'aspect_ratio' not allowed → 画像toビデオにはこのフィールドがないので削除。テキストtoビデオのみ対応。
401 permission_denied → Key の欠落、誤り、または失効。Authorization: Bearer sk-... を確認。
作成は 200 を返すが、タスクが後で fail → 通常は画像toビデオの image_url が開けないか画像でない。作成時はフィールド形状のみ検証し、URL の到達性は検証しません。
数日後にリンクが開けない → 出力 URL には有効期限があるので、取得後すぐにダウンロード。

失敗したタスクの事前引き落とし金額は自動で全額返金されます。

よくある質問

Ray 3.2 の 1 本の動画の長さは？ テキストtoビデオは 5 秒または 10 秒を選択可能。画像toビデオは 5 秒固定。

プロンプトはどれくらい書ける？ 両ルートとも 1〜6000 文字。

仕上がりに音はある？ ありません。出力は音声トラックなしの MP4 で、BGM や効果音はポストプロダクションで追加します。

画像toビデオでアスペクト比を自分で選べる？ 選べません。アスペクト比は始点フレームに従い、最も近い対応比率に自動マッチします。

テキストtoビデオに参照画像を渡せる？ 渡せません。画像で駆動したい場合は ray-3.2/image-to-video を使ってください。

Ray 3.2 シリーズ記事

今すぐ試す：上の灯台動画の下にあるこのプロンプトで生成 → をクリック。プロンプトは入力済みなので、5 秒、540p、21:9 を選んでワンクリックで同じものが作れます。

タグAPI 接続チュートリアル

すべての記事を見る →