luma-ray-video

Luma Ray 视频制作

在编写请求前，先判断应使用哪种接口。Luma 目前提供了名称相似但模型、架构、凭证、价格和数据条款互不兼容的产品。对于新的 API 集成，请使用 Luma Agents API 和 ray-3.2；将较旧的 Dream Machine API 视为用于兼容旧版的接口。

易变信息已于 2026-07-10 根据 Luma 官方一手资料核实。在进行任何付费或敏感操作前，请重新核对模型页面、架构、价格、账户限制及适用协议。

区分三种接口

当前开发者接口：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 常见问题、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	先前的生成必须已完成；仅支持 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 不提供 seed 参数，也不提供负向提示词参数。

锚点与多关键帧

video.start_frame 和 video.end_frame 各自恰好接受以下一项：公开 HTTPS url、包含 media_type 的 base64 data、已就绪的 file_id，或者用于扩展的先前 generation_id。旧版双锚点形式不适用于 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（向后扩展）。仅支持 SDR，并按一个五秒区块计费；仅向前扩展时允许使用循环。
• 当前扩展路径不支持插入先前生成的视频和另一个关键帧。

视频编辑

恰好提供一个源：同一客户端下已完成的 generation_id、file_id，或者带有 media_type: "video/*" 的 URL/base64 视频。每个源通道的时长限制为 18 秒；URL/data 源还限制为 200 MB。当前通用 FAQ 对编辑给出的时长限制为 30 秒，而类型化的 video_edit 架构规定为 18 秒。请采用更严格的类型化架构限制，并在投入生产前重新核实。

请从 video.edit.auto_controls: true 开始。若需有意权衡保留程度，可使用九种 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 提供全部四个归一化字段：x_norm/y_norm 的取值范围为 -2 到 2，w_norm/h_norm 为正数且最大为 2。目前尚不支持以 1080p 输出竖屏 9:16 或 3:4；请使用 720p 或更低分辨率。

来源：Ray 3.2 重新构图。

指导镜头

将提示词写成简洁的镜头指示：

1. 主体及不变的身份特征。
2. 视频片段中的可见动作。
3. 环境和物理交互。
4. 摄像机位置、镜头感觉和一个主要运镜。
5. 光线、色调、纹理和成片效果。
6. 仅在有助于明确正向目标时，才说明连续性要求或禁止的变化。

**制作经验法则：**一个视频片段应呈现一个戏剧性节拍。用关键帧指定精确节拍，用提示词文本描述关键帧之间的动作。不要要求一个 5 秒的镜头同时交代场景、变换角色、执行三种运镜并完成剪辑。

**制作经验法则：**通过重复使用稳定的名词和属性来保持身份一致，而不是增加更多形容词。对于产品，应固定轮廓、材质、颜色、瓶盖/封口、标签位置、光线方向和画面方向。对于人物，只能使用已获授权的肖像参考，并固定服装、发型、年龄呈现以及入场/退场动作。

示例：5 秒 HDR 图像转视频

意图：从已批准的起始图像生成可用于合成的产品亮相片段。

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。如果标签、轮廓、瓶盖或颜色出现偏差，应拒绝该结果，不要将其作为已批准的产品展示。

示例：三拍多关键帧片段

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
重新构图，每秒源素材	$0.06	$0.12	$0.36

文档还列出了草稿 360p 及更高分辨率下编辑 HDR/EXR 的价格；不要据此推算其他价格。单关键帧延长的费用，等同于相应分辨率下 5 秒 SDR 生成的价格。定价页面说明，正式发布前价格可能变动。来源：Agents API 定价。

付费 POST 前，请创建审批记录，其中包含规范请求的 SHA-256、模型/类型、所有参考素材的哈希或不可变 ID、当前报价和时间戳、最高美元金额、账户/客户端、权利/同意、保留类别、审批人和到期时间。如果请求发生变更、审批已过期、最高金额不足或非有限值、价格未知、组合不受支持，或媒体未经批准，则应默认拒绝。

示例：先试运行、单次提交

当前 API 文档将 X-Request-Id 用于追踪，但未将其说明为幂等键。此示例在原子认领后恰好发送一次 POST。对于结果不明确的网络请求，会记录下来，且不得盲目重试。

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))

轮询前先持久化返回的 generation ID。追踪 ID 有助于支持人员查找某次尝试，但不能证明请求已去重。当前 Agents API 提供创建和获取接口，但没有用于恢复的 generation 列表端点，因此，如果响应不明确且没有 ID，必须停止操作并联系支持人员核实。

操作、获取和管理工件

每隔 2–5 秒轮询一次，并设置截止时间和有界抖动。状态为 queued、processing、completed 和 failed。遵守仪表板和 X-RateLimit-* 响应标头中显示的账户专属 RPM 和并发任务限制。遇到 429 时，区分 Rate limit exceeded 和 Too many concurrent jobs，并遵守 Retry-After；切勿让重试循环造成重复的付费创建请求。

输出 URL 的预签名有效期为一小时。再次轮询会生成新的 URL；generation ID 是持久的查询凭据，但已审阅的公开文档未公布 ID 的有效期保证。应尽快通过经过身份验证的 GET 请求，从返回的 URL 下载文件，设置本地字节数上限，且绝不将预签名 URL 作为持久的终端用户链接公开。

Files API 上传的文件可通过 file_id 重复使用，并限定在账户范围内，还可以设置 expires_at；预签名上传支持声明大小不超过 5 GiB 的文件。删除属于软删除，可阻止后续引用。当前 Agents 文档提供文件删除功能，但没有 generation 删除端点，也没有保证 generation 存储期限。如需删除或导出，请使用文档中说明的支持渠道和合同条款，不要假设 URL 过期就会删除资产。

发布前：

• 保留请求、摘要、审批信息、追踪 ID、generation 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 和日志中的个人身份信息；若需要区域、数据驻留、保留、保密或删除方面的保证，请获取企业条款。

当前 Agents 文档仅公布了一个全局基础 URL，未公布可供选择的处理区域或完整的数据驻留地图。请勿声称可以固定在美国或欧盟区域。用于受监管或有数据驻留要求的场景前，请向 Luma 索取书面答复。

来源：API 条款、服务条款、内容审核政策、隐私政策。

最终发布检查

• 已重新核实界面、模型、架构、价格、API 版本和账户限制。
• 已记录完整的媒体权利、肖像授权、下游条款和预期用途审查。
• 已获批的精确摘要值和有限成本与提交的字节完全一致。
• 仅进行了一次创建尝试；ID 和跟踪记录已持久保存；未重放结果未知的请求。
• 输入和 Files 对象均有负责人、哈希值、TTL／删除计划，且未发生非预期的公开暴露。
• 原始 MP4/EXR 和终端响应均已保留并通过技术验证。
• 创意、身份、连续性、剪辑、重新构图、安全、文本和品牌质量检查均已通过。
• 已通过文件验证音频，或单独制作音频；未作出不受支持的“原生音频”声明。
• 交付内容附有 AI 披露、溯源记录、衍生作品脉络、保留期限和删除负责人。