Runway ML API
概述
Runway 的 Gen-3 Alpha Turbo 模型可根据文本提示或图像生成高质量视频。REST API 遵循异步任务模式:创建任务、轮询完成状态,然后下载结果。可用于制作电影短片、动画图像或构建自动化视频内容流水线。
设置
pip install requests python-dotenv
export RUNWAY_API_KEY="your_api_key_here"
基础 URL:https://api.dev.runwayml.com/v1
API 文档:https://docs.runwayml.com
核心概念
- 任务:一个异步视频生成作业。立即返回
task_id。 - Gen-3 Alpha Turbo:最快的 Gen-3 模型——最适合生产流水线。
- 图像转视频(
gen3a_turbo):将静态图像动画化为动态视频。 - 文本转视频:仅根据文本提示生成视频。
- 时长:5 或 10 秒。
- 宽高比:
1280:720(横屏)、720:1280(竖屏)、1104:832、832:1104、960:960(正方形)。
操作说明
步骤 1:设置客户端
import os
import time
import requests
API_KEY = os.environ["RUNWAY_API_KEY"]
BASE_URL = "https://api.dev.runwayml.com/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"X-Runway-Version": "2024-11-06"
}
步骤 2:文本转视频生成
def text_to_video(
prompt_text: str,
duration: int = 5,
ratio: str = "1280:720",
seed: int = None
) -> str:
"""提交一个文本转视频任务并返回 task_id。"""
payload = {
"model": "gen3a_turbo",
"promptText": prompt_text,
"duration": duration,
"ratio": ratio
}
if seed is not None:
payload["seed"] = seed
r = requests.post(f"{BASE_URL}/image_to_video", json=payload, headers=HEADERS)
r.raise_for_status()
return r.json()["id"]
task_id = text_to_video(
prompt_text="A drone shot flying over a misty mountain valley at golden hour, cinematic, slow motion",
duration=5,
ratio="1280:720"
)
print(f"任务已提交:{task_id}")
步骤 3:图像转视频生成
import base64
from pathlib import Path
def image_to_video(
image_path: str,
prompt_text: str = "",
duration: int = 5,
ratio: str = "1280:720",
seed: int = None
) -> str:
"""将图像动画化为视频。image_path 可以是本地文件或 URL。"""
if image_path.startswith("http"):
prompt_image = image_path
else:
# 将本地文件编码为数据 URI
img_bytes = Path(image_path).read_bytes()
ext = Path(image_path).suffix.lstrip(".").lower()
mime = {"jpg": "image/jpeg", "jpeg": "image/jpeg", "png": "image/png", "webp": "image/webp"}.get(ext, "image/png")
b64 = base64.b64encode(img_bytes).decode()
prompt_image = f"data:{mime};base64,{b64}"
payload = {
"model": "gen3a_turbo",
"promptImage": prompt_image,
"promptText": prompt_text,
"duration": duration,
"ratio": ratio
}
if seed is not None:
payload["seed"] = seed
r = requests.post(f"{BASE_URL}/image_to_video", json=payload, headers=HEADERS)
r.raise_for_status()
return r.json()["id"]
task_id = image_to_video(
image_path="product_shot.png",
prompt_text="The product slowly rotates, sparkling particles float around it, luxury feel",
duration=5,
ratio="1280:720"
)
print(f"任务已提交:{task_id}")
步骤 4:轮询任务状态
def get_task(task_id: str) -> dict:
r = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS)
r.raise_for_status()
return r.json()
def wait_for_task(task_id: str, poll_interval: int = 5, timeout: int = 600) -> list[str]:
"""轮询直到任务完成;返回输出视频 URL 列表。"""
start = time.time()
while True:
task = get_task(task_id)
status = task["status"]
progress = task.get("progress", 0)
print(f"[{int(time.time()-start)}s] 状态:{status} ({int(progress*100)}%)")
if status == "SUCCEEDED":
return task["output"] # 视频 URL 列表
elif status in ("FAILED", "CANCELLED"):
raise RuntimeError(f"任务 {status}:{task.get('failure', '')}")
elif time.time() - start > timeout:
raise TimeoutError(f"任务在 {timeout}s 内未完成")
time.sleep(poll_interval)
output_urls = wait_for_task(task_id)
print(f"视频已就绪:{output_urls}")
步骤 5:下载结果
def download_video(url: str, output_path: str = "output.mp4") -> str:
r = requests.get(url, stream=True)
r.raise_for_status()
with open(output_path, "wb") as f:
for chunk in r.iter_content(chunk_size=8192):
f.write(chunk)
size_mb = os.path.getsize(output_path) / 1024 / 1024
print(f"已保存:{output_path} ({size_mb:.1f} MB)")
return output_path
download_video(output_urls[0], "mountain_valley.mp4")
完整流水线示例
def generate_and_download(prompt: str, output_path: str = "output.mp4", **kwargs) -> str:
"""一站式操作:根据文本生成视频并下载。"""
print(f"正在生成:{prompt[:80]}...")
task_id = text_to_video(prompt, **kwargs)
urls = wait_for_task(task_id)
return download_video(urls[0], output_path)
# 生成产品广告片段
generate_and_download(
prompt="Close-up of a sleek smartphone on a white desk, screen lights up, smooth camera pull-back",
output_path="product_ad.mp4",
duration=5,
ratio="1280:720"
)
参数参考
| 参数 | 值 | 说明 |
|---|---|---|
model | gen3a_turbo | 使用 Gen-3 Alpha Turbo(最快) |
duration | 5、10 | 视频长度(秒) |
ratio | 1280:720、720:1280、1104:832、832:1104、960:960 | 分辨率宽高比 |
seed | 整数 | 用于确定性输出的可重复性种子 |
promptText | 字符串 | 描述所需视频的文本提示 |
promptImage | URL 或数据 URI | 图像转视频的起始图像 |
使用指南
- Runway 任务耗时 30–120 秒,具体取决于时长和负载。
- 输出 URL 有过期时间——生成后请尽快下载视频。
- 保持提示描述性和电影感:包含镜头运动、光照、情绪。
- 迭代提示时使用
seed复现相同结果。 - 对于批量生成,可并行提交任务但需遵守速率限制(检查 HTTP 429 状态码,并根据
Retry-After标头值重试)。 - 将 API 密钥存储在环境变量中——切勿硬编码。
- 请查看 https://docs.runwayml.com 以获取最新的模型名称和端点,因为它们会频繁更新。