luma-ray-video

Luma Ray 動画制作

リクエストを作成する前に、ジョブを適切なサーフェスに振り分けてください。現在、Luma では名前が似ていても、モデル、スキーマ、認証情報、価格、データ利用規約が互換性のない製品が公開されています。新しい API 統合には Luma Agents API と ray-3.2 を使用し、旧 Dream Machine API はレガシー互換サーフェスとして扱ってください。

変動する情報は、2026-07-10 に Luma の一次情報で確認済みです。有料の実行や機密性の高い実行の前に、モデルページ、スキーマ、価格、アカウントの制限、適用される規約を再確認してください。

3 つのサーフェスを区別する

現行の開発者向けサーフェス：Luma Agents API

• ベース URL：https://agents.lumalabs.ai/v1
• 認証情報：LUMA_AGENTS_API_KEY。Bearer トークンとして送信します。現在のキーは luma-api- で始まります。
• モデル：ray-3.2。
• 生成タイプ：POST /v1/generations の video、video_edit、video_reframe。GET /v1/generations/{id} でポーリングします。
• 現行のレスポンスヘッダー：X-API-Version: 2026-04-01。これは情報提供用です。リクエストのバージョンとして送信しないでください。
• 現行の公式 Python パッケージ：luma-agents（from luma_agents import Luma）。TypeScript、Go、CLI、生の HTTP もドキュメントに記載されています。

新しいコードにはすべてこのサーフェスを使用してください。情報源：Agents クイックスタート、モデル、API リファレンス。

コンシューマー向けサーフェス：Luma App

ブラウザー／iOS 製品にはサブスクリプションプランと独立したクレジットシステムがあります。Ray3.14 は App 専用として記載されており、API モデルではありません。App のクレジットは API の請求には引き継がれません。Luma の 2026 年 5 月の公式情報ページでは、「Dream Machine」は廃止された製品用語とされ、コンシューマー向け製品は Luma App と呼ばれています。

App のコントロール、クレジット数、リラックスモード、透かし、Ray3.14 の機能を Agents API のフィールドに置き換えないでください。情報源：公式の製品用語、Ray3.14 FAQ、App のプラン。

レガシーの開発者向けサーフェス：Dream Machine API

旧 https://api.lumalabs.ai/dream-machine/v1 API、LUMAAI_API_KEY、lumaai SDK、ray-2／ray-flash-2 モデルは、引き続きドキュメントに記載されています。そのルートとデータ形式には、レガシーの keyframes.frame0/frame1、コールバック、カメラの概念、Modify Video、Reframe、および独立した POST /generations/{id}/audio 操作が含まれます。

確認したドキュメントでは、Luma はこのサーフェスの提供終了日を公表していません。そのため、製品／API の世代が古いという意味でのレガシーであり、提供終了ではないと明記してください。既存の統合は、ダッシュボードとドキュメントを確認したうえでのみ維持してください。Agents API にレガシーのフィールドを送信しないでください。レガシーの音声リファレンスには、現行の価格、長さ、出力、ライフサイクルに関する詳細が十分に記載されていないため、安全な既定の選択肢にはできません。情報源：レガシー動画ガイド、レガシー Modify Video、レガシー音声操作。

Ray 3.2 の機能コントラクトを使用する

意図	現在のリクエスト	主な制約
テキストから動画を生成	type: "video"	プロンプトと動画設定
画像から動画を生成	type: "video" + アンカー	start_frame/end_frame、または複数キーフレーム
前方／後方に延長	type: "video" + start_frame または end_frame に直前の generation_id を1つだけ指定	直前の生成が完了済みであること。SDR のみ
動画から動画への編集	type: "video_edit" + source + video.edit	元動画の動きを維持または再解釈します。すべての入力チャネルで元動画は18秒以下
リフレーム／アウトペイント	type: "video_reframe" + source + 目標の aspect_ratio	SDR のみ。すべての入力チャネルで元動画は30秒以下

現在の Ray 3.2 のプロンプトはすべて1～6,000文字です。動画生成では 9:16、3:4、1:1、4:3、16:9、21:9 を指定できます。出力形式は MP4 です。生成時には 360p のドラフト、540p、720p、1080p を選択できます。デフォルトは720pです。標準の生成では5秒または10秒をサポートします。公開 API にはシードパラメーターもネガティブプロンプトパラメーターもありません。

アンカーと複数キーフレーム

video.start_frame と video.end_frame では、それぞれ公開 HTTPS の url、media_type と組み合わせた base64 の data、準備済みの file_id、または延長時の直前の generation_id のいずれか1つだけを指定できます。従来の2アンカー形式は10秒では機能しません。

現在の複数キーフレーム方式では、次の両方を指定します。

• video.keyframes：1～64個の ImageRef エントリー。
• video.keyframe_indexes：同じ長さで、24 fps の出力グリッド上の重複しない位置。5秒の場合は0～120、10秒の場合は0～240です。

複数キーフレームは start_frame、end_frame、loop と併用できません。従来のアンカーの組み合わせとは異なり、10秒と HDR をサポートします。Luma のマーケティング API ページには「最大16個のキーフレーム」とありますが、現在の Agents ガイドと API スキーマでは64個とされています。通信上のコントラクトには現在のスキーマを採用しますが、16個を超える指定に依存する前に再検証してください。

出典：Ray 3.2 の動画生成。

ループ、HDR、EXR、延長

• video.loop: true は新規作成時のみ指定できます。10秒、HDR、end_frame、複数キーフレームとは併用できません。
• video.hdr: true を指定するには、type: "video" の場合、720p または1080p、かつ5秒である必要があります。
• video.exr_export: true には HDR が必要で、HDR MP4 とともに EXR が出力されます。
• 単一キーフレームによる延長では、完了済みの生成 ID を start_frame（前方への延長）または end_frame（後方への延長）のいずれか1つだけに指定します。SDR のみで、5秒ブロック1つ分として課金されます。ループを指定できるのは前方への延長のみです。
• 現在の延長方式では、直前に生成した動画と別のキーフレームを補間することはサポートされていません。

動画編集

元動画は、同じクライアントで完了済みの generation_id、file_id、または media_type: "video/*" を指定した URL／base64 のいずれか1つだけを指定します。すべての元動画チャネルで18秒が上限です。URL／data ソースには200 MBの上限もあります。一般 FAQ では編集の上限を現在30秒としていますが、型付きの video_edit スキーマでは18秒です。より厳しい型付きスキーマの上限に従い、本番運用前に再確認してください。

まず video.edit.auto_controls: true を指定してください。意図的に維持の度合いを調整する場合は、9つの strength 値、adhere_1..3、flex_1..3、reimagine_1..3 のいずれかを指定します。高度な制御には、信号ごとの pose、depth、normals、trajectory、face を使用します。これらの制御は auto_controls: true と併用できません。編集では、元動画のフレームグリッド上でインデックス指定したガイドフレームを最大64個使用できます。end_frame、loop、image_ref は無効です。出力のアスペクト比は元動画から決まり、指定した aspect_ratio は暗黙に無視されます。

出典：Ray 3.2 の動画編集。

リフレーミング

video_reframe にはソースとターゲットのアスペクト比が必要です。各ソースチャネルの長さは最大30秒です。URL／データソースのサイズも最大200 MBです。SDR のみ対応しており、編集コントロール、ループ、アンカー、HDR、EXR は受け付けません。任意の video.source_position では、正規化された4つのフィールドをすべて指定します。x_norm／y_norm は -2〜2、w_norm／h_norm は 0より大きく、最大2です。1080p での縦長9:16または3:4の出力にはまだ対応していません。720p以下を使用してください。

ソース：Ray 3.2 のリフレーミング。

ショットを演出する

プロンプトは簡潔なショット指示として記述します。

1. 被写体と変えてはならないアイデンティティ。
2. クリップ中に見える動作。
3. 環境と物理的な相互作用。
4. カメラ位置、レンズの印象、主要なカメラ移動を1つ。
5. 照明、色調、質感、仕上がり。
6. 目標を明確にする場合に限り、連続性や変更禁止に関する指示。

制作上の指針： 1つのクリップには、ドラマ上の1つのビートを持たせます。正確なビートにはキーフレームを使い、その間の動きにはプロンプトテキストを使います。1つの5秒ショットに、場所の紹介、キャラクターの変身、3つのカメラ移動の実行、編集の解決をすべて求めないでください。

制作上の指針： 形容詞を増やすのではなく、安定した名詞と属性を繰り返してアイデンティティを保ちます。製品の場合は、シルエット、素材、色、キャップ／留め具、ラベルの配置、照明の方向、画面上の向きを固定します。人物の場合は、許可された肖像参照のみを使用し、衣装、髪型、年齢の見え方、登場／退場時の動きを固定します。

例：HDR の画像から動画への変換（5秒）

目的：承認済みの開始画像から、合成に適した製品の登場シーンを作成します。

request_body = {
    "model": "ray-3.2",
    "type": "video",
    "prompt": (
        "Slow 40mm dolly in on the cobalt glass perfume bottle as a narrow white highlight "
        "travels across the glass. Dark slate studio, soft rim light from camera left, restrained "
        "mist, preserve the rectangular silhouette and silver cap."
    ),
    "aspect_ratio": "16:9",
    "video": {
        "resolution": "720p",
        "duration": "5s",
        "hdr": True,
        "start_frame": {"file_id": "11111111-2222-4333-8444-555555555555"},
    },
}

期待される結果：参照画像から始まる5秒の HDR MP4 です。exr_export も true でない限り、音声や EXR は生成されません。ラベル、シルエット、キャップ、色にずれがあれば、承認済み製品として提示せず、差し戻してください。

例：3つのビートによる複数キーフレームのクリップ

request_body = {
    "model": "ray-3.2",
    "type": "video",
    "prompt": "A red paper kite rises steadily above a foggy green valley as sunrise warms the clouds; smooth lateral tracking, natural wind and taut string.",
    "aspect_ratio": "16:9",
    "video": {
        "resolution": "720p",
        "duration": "5s",
        "keyframes": [
            {"file_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"},
            {"file_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"},
            {"file_id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc"},
        ],
        "keyframe_indexes": [0, 60, 120],
    },
}

各フレームで、開始、中間、終了の構図を指定します。切り替わりで速度が不連続になっていないか、モーフィングが発生していないか、カメラが飛んでいないかを確認してください。

例：動きを維持する編集

request_body = {
    "model": "ray-3.2",
    "type": "video_edit",
    "prompt": "Preserve the choreography and camera motion; transform the warehouse into a moonlit glass conservatory, realistic reflections, cool 35mm film texture.",
    "source": {"generation_id": "d290f1ee-6c54-4b01-90e6-d701748f0851"},
    "video": {
        "resolution": "720p",
        "edit": {"auto_controls": True},
    },
}

動きやアイデンティティがずれる場合は、矛盾するコントロールを重ねるのではなく、adhere_1 または明示的なガイドフレームを試してください。

正確な操作の料金を確認し、承認する

現在の Agents 料金ガイドを実行時の参照元とします。Luma の一般向け API マーケティングページには内容が食い違う料金表があるため、日付入りの Agents ガイドから料金を引用し、送信前に再確認してください。従量課金は遅延 SLA のない共有容量です。動画の Provisioned Throughput 料金については、営業への問い合わせが必要です。

2026-07-10 時点で選定した従量課金の合計額：

操作	540p	720p	1080p
SDR 生成、5秒	$0.15	$0.30	$1.20
SDR 生成、10秒	$0.45	$0.90	$3.60
HDR 生成、5秒	—	$0.60	$2.40
HDR+EXR 生成、5秒	—	$0.90	$3.60
SDR 編集、5秒	$0.72	$1.08	$2.16
SDR 編集、10秒	$1.44	$2.16	$4.32
リフレーム、ソースの1秒あたり	$0.06	$0.12	$0.36

360p のドラフト料金と、それより高解像度の編集における HDR／EXR 料金も記載されています。そこから料金を推定しないでください。単一キーフレームでの延長には、その解像度の5秒 SDR 生成料金がかかります。料金ページには、一般提供前に料金が変更される可能性があると記載されています。ソース：Agents API の料金。

有料 POST の前に、正規リクエストの SHA-256、モデル／タイプ、すべての参照のハッシュまたは不変 ID、現在の見積もり料金とタイムスタンプ、最大 USD 額、アカウント／クライアント、権利／同意、保持クラス、承認者、有効期限を含む承認記録を作成してください。変更があった場合、上限が期限切れまたは不十分／有限値でない場合、料金が不明な場合、未対応の組み合わせの場合、またはメディアが未承認の場合は、処理を拒否してください。

例：ドライラン優先の単一試行による送信

現在の API ドキュメントでは、トレース用の X-Request-Id が記載されていますが、冪等性キーとしては記載されていません。この例では、アトミックな処理による確保の後に POST を正確に 1 回だけ実行します。ネットワークの結果が不明瞭な場合はその状態を記録し、むやみに再試行してはなりません。

import hashlib
import json
import math
import os
import urllib.error
import urllib.request
from decimal import Decimal, InvalidOperation
from pathlib import Path

API = "https://agents.lumalabs.ai/v1/generations"
PRICE = Decimal("0.30")  # 720p SDR 5s, verified 2026-07-10; recheck before execute.
body = {
    "model": "ray-3.2",
    "type": "video",
    "prompt": "Static wide shot of silver grass moving in dawn wind, soft fog, natural documentary light.",
    "aspect_ratio": "16:9",
    "video": {"resolution": "720p", "duration": "5s"},
}
canonical = json.dumps(body, sort_keys=True, separators=(",", ":")).encode()
digest = hashlib.sha256(canonical).hexdigest()
state_path = Path(os.environ.get("LUMA_STATE", f"luma-{digest}.json"))
print(json.dumps({"sha256": digest, "estimated_usd": str(PRICE), "request": body}, indent=2))

if os.environ.get("EXECUTE") != "1":
    raise SystemExit("DRY RUN: approve the digest, then set EXECUTE=1")
if os.environ.get("APPROVED_SHA256") != digest:
    raise SystemExit("approval digest mismatch")
try:
    maximum = Decimal(os.environ["APPROVED_MAX_USD"])
except (KeyError, InvalidOperation):
    raise SystemExit("missing or invalid approved maximum")
if not math.isfinite(float(maximum)) or maximum < PRICE:
    raise SystemExit("approved maximum is non-finite or insufficient")
token = os.environ.get("LUMA_AGENTS_API_KEY", "")
if not token.startswith("luma-api-"):
    raise SystemExit("missing current Agents API key")

claim = {"state": "SUBMITTING", "request_sha256": digest, "x_request_id": f"req-{digest[:32]}"}
fd = os.open(state_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
with os.fdopen(fd, "w", encoding="utf-8") as handle:
    json.dump(claim, handle, indent=2)
    handle.flush()
    os.fsync(handle.fileno())

def save(value):
    temp = state_path.with_name(state_path.name + ".tmp")
    temp_fd = os.open(temp, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
    with os.fdopen(temp_fd, "w", encoding="utf-8") as handle:
        json.dump(value, handle, indent=2)
        handle.flush()
        os.fsync(handle.fileno())
    os.replace(temp, state_path)

request = urllib.request.Request(
    API,
    data=canonical,
    method="POST",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "X-Request-Id": claim["x_request_id"],
    },
)
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        if response.status != 201:
            raise RuntimeError(f"unexpected HTTP {response.status}")
        result = json.loads(response.read(1_000_000))
        claim.update(state="SUBMITTED", generation_id=result["id"])
except urllib.error.HTTPError as exc:
    # A 4xx response rejects the request. A 5xx can arrive after the service
    # accepted it, so preserve uncertainty and reconcile before any retry.
    state = "REJECTED" if 400 <= exc.code < 500 else "UNKNOWN"
    claim.update(state=state, http_status=exc.code)
    save(claim)
    raise SystemExit(
        f"HTTP {exc.code}; claim is {state}; inspect and reconcile before any new attempt"
    )
except Exception as exc:
    claim.update(state="UNKNOWN", error_type=type(exc).__name__)
    save(claim)
    raise SystemExit("submission outcome unknown; do not repeat POST—escalate with X-Request-Id")
save(claim)
print(json.dumps(claim, indent=2))

ポーリングを始める前に、返された生成 ID を永続化してください。トレース ID はサポート担当者が試行を特定するのに役立ちますが、重複排除を保証するものではありません。現在の Agents API で公開されているのは作成と取得のエンドポイントであり、生成一覧による復旧エンドポイントはありません。そのため、ID を伴わない曖昧な応答については、サポートとの照合が完了するまで処理を停止してください。

アーティファクトの運用、取得、管理

期限を設け、ジッターを上限付きで加えて、2〜5 秒ごとにポーリングしてください。状態は queued、processing、completed、failed です。ダッシュボードと X-RateLimit-* レスポンスヘッダーに示される、アカウント固有の RPM 制限と同時実行ジョブ数の上限を守ってください。429 が返された場合は、Rate limit exceeded と Too many concurrent jobs を区別し、Retry-After に従ってください。再試行ループによって、有料の作成処理を重複させてはなりません。

出力 URL は 1 時間有効な署名付き URL です。再ポーリングすると新しい URL が発行されます。生成 ID は永続的な検索キーですが、確認済みの公開ドキュメントには ID の有効期限に関する保証はありません。認証済み GET で返された URL から速やかにダウンロードし、ローカルのバイト数上限を適用してください。また、署名付き URL を永続的なエンドユーザー向けリンクとして公開してはなりません。

Files API へのアップロードは file_id を使って再利用でき、アカウントに紐付けられます。また、expires_at を設定できます。署名付きアップロードでは、宣言されたファイルを最大 5 GiB までアップロードできます。削除は論理削除であり、以後の参照を防ぎます。現在の Agents ドキュメントにはファイル削除が記載されていますが、生成の削除エンドポイントや、生成ストレージの保証された TTL は記載されていません。削除やエクスポートが必要な場合は、URL の有効期限切れによってアセットも削除されると想定せず、記載されているサポート窓口と契約に従ってください。

公開前に、次のことを行ってください。

• リクエスト、ダイジェスト、承認情報、トレース ID、生成 ID、ソース／ファイル ID とハッシュ、モデル／タイプ、価格スナップショット、未加工の最終応答を保持します。
• 各 MP4／EXR を上限付きでダウンロードし、HTML／エラー本文を拒否して、ファイルシグネチャを検証したうえで、プローブと完全なデコードを行います。
• 音声に関する主張をする前に、指定された再生時間、寸法／アスペクト比、想定される SDR／HDR メタデータ、フレームレート、音声の有無を確認します。
• アイデンティティ、解剖学的整合性、オブジェクトの連続性、カメラの連続性、ちらつき、テキスト、ブランド／製品の正確性、編集、リフレームの継ぎ目を確認します。
• オリジナルのハッシュを計算し、管理された永続ストレージに保存して、上書きせずにアトミックに公開し、トランスコードやカラーグレーディングをすべて派生物として記録します。

出典：Files API、レート制限、エラー処理。

権利、プライバシー、安全性、および開示

提出して変換するメディア、肖像、パフォーマンス、ブランド、場所は、使用許可を得ているものだけを使用してください。個人を特定できる人物やデジタルレプリカについては、文書による同意を取得してください。欺瞞的なディープフェイク、なりすまし、政治的操作、性的コンテンツ、児童搾取、詐欺、嫌がらせ、または来歴を誤認させる目的でサービスを使用しないでください。Luma の API 利用規約では、下流の API ユーザーにも少なくとも同等の制限、合理的なモデレーション／不正利用対策、および出力が AI 生成であることの通知を適用するよう求めています。

2026年4月の API 利用規約には、Luma が API 入力または出力をモデルのトレーニングや開発に使用しないこと、また、規約の対象となる API アクセスについて、一般利用規約と矛盾する場合は当該 API 利用規約が優先されることが記載されています。ただし、現在の Agents の料金比較では、従量課金にはトレーニングに使用しない保証がなく、Provisioned Throughput にはその保証があるとされています。この一次情報間の矛盾は未解決として扱ってください。Luma から書面による確認を得ずに、機密性の高いワークロードで従量課金にトレーニング不使用の保証があると約束しないでください。保証が重要な場合は、確認済みのエンタープライズ向け／プロビジョニング済みの規約を利用してください。いずれの記述も、コンシューマー向け App や従来の無料ワークフローに自動的に適用しないでください。Luma は引き続き、サービスの提供、ポリシーの適用、請求、サポート、ストレージ運用のためにデータを処理します。また、公開 URL の入力データはホスティング経路にメディアを公開します。非公開のアセットには Files API または管理された短期間有効の URL を使用し、プロンプト／ユーザー ID／ログに含める PII を最小限に抑えてください。リージョン、データレジデンシー、保持、機密保持、削除の保証が必要な場合は、エンタープライズ向け規約を取得してください。

現在の Agents ドキュメントにはグローバルなベース URL が1つ掲載されており、選択可能な処理リージョンや包括的なデータレジデンシーのマップは公開されていません。米国／EU への固定を主張しないでください。規制対象の利用やデータレジデンシーの制約がある利用を開始する前に、Luma から書面による回答を得てください。

出典：API 利用規約、利用規約、コンテンツモデレーションポリシー、プライバシーポリシー。

最終リリース判定

• サーフェス、モデル、スキーマ、価格、API バージョン、アカウント制限を再確認済みであること。
• メディアの権利、肖像の同意、下流の利用規約、および意図した使用の確認が完了し、記録されていること。
• 正確なダイジェストと上限のあるコスト承認が、送信したバイト列と一致していること。
• 作成の試行は1回のみで、ID とトレースが永続化され、不明な結果を再実行していないこと。
• 入力と Files オブジェクトに所有者、ハッシュ、TTL／削除計画が設定され、意図しない公開がないこと。
• 元の MP4／EXR と最終応答が保存され、技術的に検証されていること。
• クリエイティブ、アイデンティティ、一貫性、編集、リフレーム、安全性、テキスト、ブランドの QA に合格していること。
• 音声がファイルから検証されているか、別途作成されており、根拠のない「ネイティブ音声」の主張をしていないこと。
• AI による開示、来歴記録、派生物の系譜、保持、および削除の責任者が納品物に含まれていること。