Runway ML API
概述
Runway 的 Gen-3 Alpha Turbo 模型可從文字提示或圖片生成高品質影片。REST API 採用非同步任務模式:建立任務、輪詢完成狀態、下載結果。可用於製作電影級短片、將圖片轉為動畫,或建置自動化影片內容管線。
設定
pip install requests python-dotenv
export RUNWAY_API_KEY="your_api_key_here"
Base URL: https://api.dev.runwayml.com/v1
API 文件:https://docs.runwayml.com
核心概念
- Task(任務):一個非同步的影片生成工作。建立後立即回傳
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 submitted: {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:
# 將本地檔案編碼為 data 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 submitted: {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 或 data URI | 圖片轉影片的起始圖片 |
指引
- Runway 任務根據持續時間與負載,通常需要 30–120 秒完成。
- 輸出 URL 有時間限制 — 請在生成後立即下載影片。
- 提示詞應描述性強且富有電影感:包含鏡頭運動、光線、情緒。
- 在迭代提示詞時使用
seed來重現相同結果。 - 批次生成時,請平行排入任務,但務必遵守速率限制(檢查 HTTP 429 狀態碼,並根據
Retry-After標頭值重試)。 - API 金鑰應儲存在環境變數中 — 切勿寫死在程式碼中。
- 由於模型名稱與端點變化快速,請查閱 https://docs.runwayml.com 以取得最新資訊。