Runway API 文生视频：通过 hiapi 调用 Gen-4.5 的开发者指南

为什么使用托管式文生视频端点

文生视频并不是图像生成或编辑流程的替代品——它是一种不同的基础能力。图像模型给你一张静帧，你可以裁剪、修图或合成。文生视频调用给你的是运动：镜头运动、主体动作，以及随时间变化的光线。如果你的产品需要一段视频片段——一个简短的营销画面、一个应用内背景循环、一个场景的预览——单次“请求到片段”的调用往往是从想法到素材最快的路径。

代价是控制力。你是在用文字描述运动，而不是用关键帧去设定它，因此模型需要自行解读。这让提示词质量比图像任务中更为重要，也让迭代循环比一次性尝试更为重要。

通过 hiapi 提供的托管端点免去了围绕这一基础能力的基础设施工作：你获得一个一致的接口、一套凭证模型，以及在你所调用的视频模型之间统一的响应结构。你把时间花在提示词和产品集成上，而不是存储管线、任务轮询和各家 SDK 上。

适用场景：

• 根据用户输入或模板按需生成的短片
• 在投入完整生产管线之前的快速概念探索
• 背景和 B-roll 素材，即使某次生成略有瑕疵仍然可用

不适用场景：任何需要帧级精确连续性、确定性输出或长篇叙事连贯性的需求。请为每个可用结果预留若干候选片段的预算。

runway-gen-4.5/text-to-video 端点的结构

从概念上讲，发往 runway-gen-4.5/text-to-video 的请求由三部分组成：提示词、请求级设置，以及你的身份/授权。只有第一部分是创意性的，另外两部分决定模型如何运行以及如何计费。

你发送什么

• 提示词字符串。主要的创意输入——用自然语言描述主体、动作、镜头、光线和氛围。
• 请求级设置。宽高比、时长，以及端点暴露的任何生成标志。这些决定输出的容器形态，而非其内容。
• 认证头。你的 hiapi 密钥，每次调用都要带上。请将其视为机密；绝不要放在客户端代码中发布。

你收到什么

视频生成不是瞬时完成的，因此根据端点的调用方式，你可能会收到一个需要轮询的任务句柄，或一个解析为媒体 URL 的响应。无论哪种情况，你收到的都是对生成片段的引用，而不是内联的原始字节。如果你需要在返回 URL 的有效期之后继续使用素材，请将其下载并持久化到你自己的存储中。

一个有用的心智模型：该端点是一个将 (prompt, settings) 映射为片段加元数据的函数。你的集成应将其视为异步、可重试且非确定性的——相同的输入不总会产生相同的片段，这是预期行为，而非缺陷。

让请求构建保持简单乏味。写一个小的内部封装，负责组装请求体、附加认证、发送调用，并将响应规范化为 { status, videoUrl, error }。本指南后续所有章节都假定这个封装已经存在。

编写能在运动中成立的电影级提示词

含糊的形容词在运动中会崩坏。“A beautiful cinematic shot of a city”没有给模型任何可动画的东西，于是它生成某种泛泛而漂移的画面。解决办法是明确摄像师所需的四项要素：主体、镜头、光线和运动。

点名主体与动作

说明画面中有什么，以及它在整个片段中做什么。给出一个起点和一个隐含的终点，让模型有运动轨迹可循。

A lone cyclist rides from left to right along a wet coastal road, 
pedaling steadily as spray kicks up from the rear wheel.

明确指定镜头

使用模型能映射为运动的镜头语言：缓慢推近、固定广角、手持跟随、低角度追踪、缓慢右摇、航拍下降。每个片段只用一个镜头运动，比三个互相冲突的运动更稳妥。

Static wide shot, camera at ground level, no zoom.

指定光线与时间

光线决定了大部分感知到的制作水准。给出光源和质感：阴天漫射日光、来自镜头左侧的强烈午后阳光、夜晚湿滑反光中的实景霓虹。

描述物理上可信的运动

短片段中的快速运动会拖糊。相比众多快速事件，更倾向于中等速度的单一可读动作。如果你想要张力，请从镜头运动和光线中获取，而不是让十几件事同时发生。

保持一个段落

一到三句话的紧凑段落胜过项目符号式的规格清单。把它写成镜头描述，而不是愿望清单。避免堆叠风格形容词；选定一种观感并坚持到底。

一个可靠的模板：

[Subject + action]. [Camera framing and movement]. [Lighting and time of day]. [Environment and atmosphere].

在改动任何设置之前，先把你的提示词重写进这个模板。

一个可运行的请求，分步说明

本演练假定使用 Node.js 和一个封装函数，但结构不依赖具体语言。

第 1 步：编写镜头

A chef slices vegetables on a wooden board in a small kitchen, 
hands moving steadily. Static medium close-up, camera at counter height, 
no zoom. Warm tungsten light from an overhead lamp, soft shadows, 
light steam in the background.

第 2 步：选择请求设置

选择与片段最终使用位置相匹配的宽高比，以及能讲清故事的最短时长。短片段失败得快，探索成本也更低。

第 3 步：发送调用

const res = await fetch(`${HIAPI_BASE}/runway-gen-4.5/text-to-video`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.HIAPI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: shotPrompt,
    aspect_ratio: '16:9',
    duration: 5,
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);

第 4 步：获取片段

如果响应携带任务句柄，则用较小的退避间隔轮询，直到其达到终态。如果直接携带媒体 URL，则跳到第 5 步。

第 5 步：持久化素材

下载片段并以你自己的键存储。把返回的 URL 当作临时地址。

第 6 步：记录决策点

将提示词、设置和生成的素材一并记录。正是这份日志让下一节——调优——变得可操作，而不是靠猜。

在不修改提示词的情况下调优输出

当片段令人失望时，本能反应是重写提示词。先忍住一轮。提示词和设置是独立的变量，同时改动两者会破坏你判断究竟哪个才是关键的能力。

隔离变量

保持提示词固定，只改动恰好一个请求级设置——宽高比、时长或某个生成标志。重新运行。如果片段改善，说明问题出在结构层面而非创意层面。如果没有改善，就回退该设置，转而修改提示词。

用设置解决结构性问题

• 构图与投放位置不符？改宽高比。
• 动作在完成前被截断？增加时长。
• 一切都漂移不定、没有锚点？缩短片段，让它没有那么多时间漂移。

用提示词修改解决内容问题

• 主体错误或缺失？更早点名，并使其具体。
• 镜头游移？删掉除你想要的那一个运动之外的所有镜头用词。
• 平淡无生气？添加光源和方向。

做一个小型 A/B 测试

固定一个种子提示词，生成三个变体，每个只改动一个从句。并排比较它们，而不是凭记忆。非确定性意味着单个糟糕片段并非证据；在断定某个从句有害之前，先在两三次运行中寻找规律。

把你已经维护的日志里写下结论。经过十几次迭代，这会变成针对你产品专属的提示词与设置手册，其价值远超任何通用提示词清单。

调试常见失败

第一周的大多数失败可归为四类。每类的排查路径不同。

请求被拒绝或拦截

带有策略信息的非 2xx 响应意味着提示词或设置未被接受。阅读错误响应体，而不是盲目重试。重写有问题的描述，移除具名的真实人物或品牌，然后重新发送。原样记录被拒绝的提示词——反复出现的拒绝通常可追溯到提示词模板中的某个习惯。

超时

视频生成很慢。如果你的 HTTP 客户端在端点响应之前超时，任务可能仍在运行并且会计费。为生成类调用提高客户端超时，并将轮询移入后台工作进程，而不是保持请求挂起。

空片段或不可用片段

响应成功但片段中没有可辨认的主体，通常意味着提示词过于抽象。对照主体-镜头-光线-运动模板重读它。如果四项中缺了一项，那就是你的修复点。

认证与配置错误

401 和 403 意味着密钥问题，而不是提示词问题。确认密钥存在于运行时环境中，而不仅仅是你的本地 shell，并确认请求头格式。这类失败越早发现成本越低，在生产中发现成本越高。

一条通用规则：在改动任何东西之前先对错误分类。提示词类错误、设置类错误和基础设施类错误需要不同的修复方式，混在一起会浪费生成预算。

成本、延迟与生产防护措施

在上线之前，先决定出错时端点的行为，因为视频生成是大多数产品中最昂贵、最慢的调用。

按片段而非按调用做预算

视频计费通常与输出长度挂钩，因此较长的片段比较短的片段更贵。请以成品片段的单位做预算——包括重试和被拒的候选——而不是统计 API 调用次数。为每个用户和每个会话设定生成上限。当前费率见价格面板；不要将它们硬编码进业务逻辑。

为延迟而设计

绝不要让面向用户的请求阻塞在生成上。启动任务，立即返回句柄，并通过轮询、webhook 或通知交付片段。在 UI 中显示进度，让缓慢的渲染读起来是进行中的工作，而不是卡死。按提示词和设置缓存已生成的片段，避免重复请求重新生成。

在生成之前做校验

调用前的廉价检查能省下调用后的昂贵处理：

• 在你的封装中强制提示词的最小和最大长度
• 拒绝缺少主体或动作的提示词
• 对照渲染目标验证宽高比
• 确认用户在其配额之内

入口和出口都做审核

发送前对提示词做文本检查。展示前对返回的片段做轻量检查。两者都比一次支持事故便宜。

保留兜底方案

如果生成失败或耗时过长，提供一个静态封面帧或占位片段，而不是报错。功能应当降级，而不是中断。

从一个端点、一个封装和一份日志开始；随着你了解产品实际在哪里失败，逐步添加防护措施，并让价格面板始终是成本的唯一事实来源。