使用代码调用Runway API批量生成视频，应用场景远不止简单的“图生视频”——例如为电商商品图批量添加旋转动画、将100篇博客自动转换为营销短视频、或接入内部CMS系统实现“一键成片”。核心任务分为三类：Text to Video、Image to Video、Video to Video。操作前需准备好API密钥、安装runwayml库、确保Pro订阅且积分充足（提示词限制120字符，避免使用中文标点）；图像和视频输入需先上传获取file_id/video_id再拼接URL；Motion Brush需导出JSON坐标，导演模式与音频保留也需显式配置参数。

准备API密钥和基础环境

登录Runway官网，点击右上角头像，进入Settings，选择API Keys，然后点击“Create New Key”，复制生成的密钥。这里有一个极易踩坑的注意事项：【该密钥一旦关闭页面就无法再次查看，必须立即保存】，经验之谈，请务必牢记。

环境方面，需安装Python 3.9或更高版本，然后执行 pip install runwayml 安装库即可。

此外，请确认已开通Pro订阅且账户余额充足。Gen-3 Alpha模型每秒消耗15积分，生成一段4秒视频需60积分，而免费额度仅125积分/月，不足以完成两轮测试，请根据实际需求合理规划用量。

发送文本生成视频请求（Text to Video）

推荐使用官方SDK，适合新手。初始化客户端后直接传入参数，提示词需控制在120字符内，且避免使用中文标点。例如："A vintage typewriter on a wooden desk, keys pressing down one by one, soft shadows, film grain"。

调用 run.generate_video(prompt=...) 后会返回一个任务ID，然后需要轮询 get_job_status(task_id) 直至status变为completed，最后用 get_result(task_id) 下载MP4。此过程虽简单，但需注意轮询间隔不宜过短，以免触发限流。

发送图像生成视频请求（Image to Video）

第一步：将本地图片上传至Runway托管存储空间。调用 run.upload_file("product.jpg") 获取file_id，此ID为后续请求必需参数，注意不是URL。

第二步：构造包含图像引用的生成请求体。body的结构大致如下：

{
    "model": "gen-3-alpha",
    "prompt": "the shoe rotates slowly, studio lighting, clean white background",
    "image_url": "https://cdn.runwayml.com/files/{file_id}",
    "duration": 4
}

这里有一个关键点：【image_url必须使用run.upload_file返回的file_id拼接，不可直接传入本地路径或公网URL】，否则API会直接报错。

第三步：向 https://api.runwayml.com/v1/video-generation 发送POST请求，Header中携带 Authorization: Bearer YOUR_API_KEY。若使用SDK，这些底层细节已自动处理，但手动调用时需仔细检查。

处理视频转视频（Video to Video）的特殊参数

此环节较前两个更为复杂，需注意以下几点：

① 必须先上传原始视频，获取video_id；

② Motion Brush轨迹需预先导出为JSON格式坐标数组，包含每帧的x/y偏移量与蒙版掩码，否则API会忽略笔刷效果——不传则无效；

③ 开启导演模式需显式设置 camera_motion: { "type": "dolly-in", "intensity": 0.7 }，若不设置，默认无摄像机动画，输出为静态镜头；

④ 如需保留音频轨道，必须在请求体中添加 keep_audio: true，否则生成结果始终为静音。许多新手初次运行发现无声音，往往是因为遗漏了此参数。