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 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:
# ローカルファイルをデータ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: {status} ({int(progress*100)}%)")
if status == "SUCCEEDED":
return task["output"] # 動画URLのリスト
elif status in ("FAILED", "CANCELLED"):
raise RuntimeError(f"Task {status}: {task.get('failure', '')}")
elif time.time() - start > timeout:
raise TimeoutError(f"Task not done after {timeout}s")
time.sleep(poll_interval)
output_urls = wait_for_task(task_id)
print(f"Video(s) ready: {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"Saved: {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"Generating: {prompt[:80]}...")
task_id = text_to_video(prompt, **kwargs)
urls = wait_for_task(task_id)
return download_video(urls[0], output_path)
# 製品広告クリップを生成
生成_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 で確認してください。