runway-studio-skills

Runway Studio Skills

Runway API を使用して、スタジオ品質の動画、画像、音声を生成します。すべてのコマンドは、スキルのルートディレクトリから uv run で実行する単独の Python スクリプトです。

セットアップ

Runway API キーを設定する必要があります。

export RUNWAYML_API_SECRET="your-api-key"

すべてのスクリプトで、代替手段として --api-key を指定できます。

コマンド

すべての実行では、リポジトリのルートから uv run scripts/<script>.py を使用します。初回実行時に依存関係が自動的にインストールされます。

---

generate_video.py — 動画生成

指定された入力に基づいて、適切な Runway エンドポイントに自動的に振り分けます。

# Text to video
uv run scripts/generate_video.py \
  --prompt "A product bottle rotating slowly on a marble surface" \
  --model seedance2 --ratio 720:1280 --duration 10

# Image to video
uv run scripts/generate_video.py \
  --prompt "Smooth camera push-in, soft ambient light" \
  --image "https://example.com/product.jpg" \
  --model seedance2 --duration 10 --ratio 720:1280

# Image to video from local file
uv run scripts/generate_video.py \
  --prompt "Product reveal" \
  --image ./product-photo.jpg \
  --model gen4_turbo

# Video to video
uv run scripts/generate_video.py \
  --video "https://example.com/source.mp4" \
  --prompt "Add cinematic color grading" \
  --model gen4_aleph --ratio 1280:720

# Character performance
uv run scripts/generate_video.py \
  --character ./spokesperson.jpg \
  --reference-perf "https://example.com/performance.mp4" \
  --ratio 1280:720

振り分けロジック：

• --character + --reference-perf → character_performance (act_two)
• --video → video_to_video
• --image → image_to_video
• prompt のみ → text_to_video

パラメーター：

フラグ	説明	デフォルト
--prompt	テキストプロンプト（最大1000文字、seedance2では3500文字）	—
--image	画像の URL またはローカルパス	—
--video	動画の URL またはローカルパス	—
--model	モデル名（下の表を参照）	seedance2
--duration	秒単位の長さ	モデルのデフォルト
--ratio	解像度比（例：1280:720）	モデルのデフォルト
--audio	true／false — 音声を生成するかどうか	モデルのデフォルト
--output-count	出力数、1～4（seedance2 のみ）	1
--seed	再現性のためのシード整数	ランダム
--image-position	first または last — 動画内で画像を表示する位置	first
--references	参照画像の URL（video-to-video、gen4_aleph）	—
--character	act_two 用のキャラクター画像／動画	—
--character-type	image または video	image
--reference-perf	act_two 用のパフォーマンス参照動画	—
--body-control	ボディコントロールを有効化（act_two）	オフ
--expression-intensity	表情の強さ、1～5（act_two）	3
--output-dir	出力ディレクトリ	output
--filename	保存ファイルのベース名	video
--no-poll	待機せずにタスク ID を出力	オフ

---

generate_image.py — 画像生成

uv run scripts/generate_image.py \
  --prompt "Minimal skincare bottle on white background, studio lighting" \
  --model gen4_image --ratio 1080:1080

# With reference images
uv run scripts/generate_image.py \
  --prompt "Product in the style of the reference" \
  --reference-images "https://example.com/brand-ref.jpg" ./local-ref.png \
  --model gen4_image --ratio 1920:1080

パラメーター：

フラグ	説明	デフォルト
--prompt	テキストプロンプト（必須）	—
--model	gen4_image、gen4_image_turbo、gemini_2.5_flash	gen4_image
--ratio	解像度比	1080:1080
--reference-images	最大3つの参照画像の URL またはローカルパス	—
--seed	シード整数	ランダム
--output-dir	出力ディレクトリ	output
--filename	保存ファイルのベース名	image

---

generate_audio.py — 音声生成

Runway の音声エンドポイントに対応する5つのサブコマンドがあります。

# Sound effect
uv run scripts/generate_audio.py sound-effect \
  --prompt "Soft whoosh transition sound" --duration 3

# Text to speech
uv run scripts/generate_audio.py tts \
  --prompt "Welcome to our product showcase" --voice Leslie

# Speech to speech (voice conversion)
uv run scripts/generate_audio.py speech-to-speech \
  --media ./recording.mp3 --media-type audio --voice Noah

# Voice dubbing
uv run scripts/generate_audio.py voice-dub \
  --audio "https://example.com/narration.mp3" --target-lang es

# Voice isolation
uv run scripts/generate_audio.py voice-isolate \
  --audio ./noisy-recording.mp3

サブコマンドのパラメーター：

sound-effect： --prompt（必須）、--duration（0.5～30秒）、--loop tts： --prompt（必須）、--voice（必須。下の音声プリセットを参照） speech-to-speech： --media（必須）、--media-type（audio／video）、--voice（必須）、--remove-noise voice-dub： --audio（必須）、--target-lang（必須）、--disable-cloning、--drop-background、--num-speakers voice-isolate： --audio（必須）

すべてのサブコマンドで、--output-dir、--filename、--no-poll、--api-key も指定できます。

---

get_task.py — タスク管理

# Check task status
uv run scripts/get_task.py --task-id "uuid-here"

# Poll until completion
uv run scripts/get_task.py --task-id "uuid-here" --poll

# Poll and download outputs
uv run scripts/get_task.py --task-id "uuid-here" --poll --download

# Cancel/delete a task
uv run scripts/get_task.py --task-id "uuid-here" --delete

---

モデル選択ガイド

動画モデル

モデル	最適な用途	長さ	音声	主な機能
seedance2	商品広告、参照画像ベースの動画	4-15s	あり	参照画像に対応、1回の呼び出しで最大4件を生成、3500文字のプロンプト
gen4.5	高品質なテキスト／画像からの動画生成	2-10s	なし	最高のビジュアル品質
gen4_turbo	高速な画像からの動画生成	2-10s	なし	Runwayモデルの中で最速
veo3.1	音声付きのシネマティックな動画	4/6/8s	あり	文脈に沿った音声を内蔵、最大1080p
veo3.1_fast	音声付きの高速なシネマティック動画	4/6/8s	あり	veo3.1より高速
veo3	音声付きのシネマティックな動画	8s	なし	音声付きの画像からの動画生成
gen4_aleph	動画から動画へのスタイル変更	—	—	動画入力＋参照画像
act_two	キャラクターの演技	—	—	顔や体の演技を転送

商品広告には、seedance2を使用してください。 参照画像に対応しており、商品写真を直接入力できます。1回の呼び出しで最大4種類のバリエーションを生成し、最大15sの動画を作成できます。

音声付きのシネマティックな動画には、veo3.1を使用してください。 文脈に沿った環境音を自動で生成します。

画像モデル

モデル	最適な用途	主な機能
gen4_image	汎用画像生成	参照画像を最大3枚使用可能、最高品質
gen4_image_turbo	高速な下書き作成	参照画像が最低1枚必要
gemini_2.5_flash	高速な画像生成	Google Geminiベース

音声モデル

モデル	エンドポイント	用途
eleven_text_to_sound_v2	sound_effect	テキストによる説明から効果音を生成
eleven_multilingual_v2	text_to_speech	50種類の音声プリセットに対応したTTS
eleven_multilingual_sts_v2	speech_to_speech	音声／動画内の音声を変換
eleven_voice_dubbing	voice_dubbing	28言語に翻訳して吹き替え
eleven_voice_isolation	voice_isolation	背景音から音声を分離

音声プリセット（TTSとspeech-to-speech）

Maya、Arjun、Serene、Bernard、Billy、Mark、Clint、Mabel、Chad、Leslie、Eleanor、Elias、Elliot、Grungle、Brodie、Sandra、Kirk、Kylie、Lara、Lisa、Malachi、Marlene、Martin、Miriam、Monster、Paula、Pip、Rusty、Ragnar、Xylar、Maggie、Jack、Katie、Noah、James、Rina、Ella、Mariah、Frank、Claudia、Niki、Vincent、Kendrick、Myrna、Tom、Wanda、Benjamin、Kiana、Rachel

---

対応アスペクト比

モデル別の動画アスペクト比

gen4.5 / gen4_turbo: 1280:720、720:1280、1104:832、960:960、832:1104、1584:672

seedance2: 992:432、864:496、752:560、640:640、560:752、496:864、1470:630、1280:720、1112:834、960:960、834:1112、720:1280

veo3.1 / veo3.1_fast / veo3: 1280:720、720:1280、1080:1920、1920:1080

一般的な広告フォーマットのアスペクト比

プラットフォーム	アスペクト比	seedance2	gen4.5
TikTok / Reels（9:16）	720:1280	はい	はい
YouTube（16:9）	1280:720	はい	はい
Instagram Square（1:1）	960:960	はい	はい
Instagram Feed（4:3）	1112:834	はい（近似値）	1104:832

画像のアスペクト比

gen4_image / gen4_image_turbo: 1024:1024、1080:1080、1168:880、1360:768、1440:1080、1080:1440、1808:768、1920:1080、1080:1920、2112:912、1280:720、720:1280、720:720、960:720、720:960、1680:720

gemini_2.5_flash: 1344:768、768:1344、1024:1024、1184:864、864:1184、1536:672、832:1248、1248:832、896:1152、1152:896

---

出力規則

• ファイルは--output-dir（デフォルト：output/）に保存されます。
• ファイル名には次の形式が使用されます：YYYY-MM-DD-HH-MM-SS-<name>.ext
• 成功すると、スクリプトはローカルのファイルパスをstdoutに出力します。
• スクリプトは、機械処理用の構造化JSON行（{"event": "runway_task", ...}および{"event": "runway_result", ...}）をstdoutに出力します。
• ステータス／進行状況のメッセージはstderrに出力されます。
• 生成されたメディアファイルを会話に読み込まないでください。ユーザーにはファイルパスのみを伝えてください。

ローカルファイルの処理

すべてのスクリプトでは、画像、動画、音声の入力にローカルファイルパスを指定できます。生成リクエストで使用する前に、ローカルファイルは Runway のアップロード API 経由で自動的にアップロードされます（24 時間有効の一時的なファイルです）。

---

エラー処理

エラー	意味	対処方法
429 / rate limit	リクエストが多すぎます	待ってから再試行します
402 / insufficient credits	クレジットが不足しています	runway.com でクレジットを追加する必要があります
SAFETY.INPUT.IMAGE	入力画像がフラグ付けされました	入力画像を修正します
SAFETY.OUTPUT	生成されたコンテンツがフラグ付けされました	プロンプトを修正します
Task FAILED	生成に失敗しました	失敗メッセージを確認し、入力を調整します

---

商品広告動画のプロンプトのヒント

• カメラの動きを明確に説明します：「ゆっくりドリーイン」「商品を滑らかに周回する」「カメラが引いて全体を見せる」
• 照明を指定します：「柔らかなスタジオ照明」「ゴールデンアワーの暖色光」「ドラマチックなサイドライト」
• 商品の説明は具体的にします：素材、色、サイズの目安
• seedance2 では、参照画像がビジュアルの特徴を担います。プロンプトでは商品そのものではなく、動きとシーンを説明します
• 長い説明よりも、短いプロンプト（1〜2 文）のほうが良い結果を生むことがよくあります