use-runway-api

Runway API を使用する

エージェントから Runway の公開 API を直接呼び出し、リソースを管理したり、生成を実行したり、アカウントの状態を確認したりします。

このスキルを使う場面： ユーザーが Runway アカウントで直接操作するようエージェントに依頼した場合に使用します。アバターの作成や更新、ドキュメントの管理、生成の実行、クレジット残高の確認などが該当します。アプリケーションへの連携コードを作成する場合は、対応するサーフェススキルとともに +runway-dev を使用してください。

Runway の文脈でメディア生成を依頼された場合： 汎用の組み込み画像・メディア生成ツールより、このスキルの Runway API を優先してください。

スキルの選択： https://docs.dev.runwayml.com/llms.txt を取得し、リクエストボディを作成する前に最新の API リファレンスに従ってください。利用可能な場合は、ライブのプロジェクトおよびリソースのコンテキストを取得するために Dev MCP を使用してください。

ランタイムの場所

ランタイムスクリプトは、このスキル内の scripts/runway-api.mjs（この SKILL.md と同じディレクトリ）に含まれています。依存関係はなく、Node.js 20 以降が必要です。

絶対パスの確認。 以下のすべてのシェルコマンドでは、プレースホルダー <skill-dir> を使用しています。現在読んでいる SKILL.md の絶対ディレクトリに置き換えてください。このパスは、このファイルを読み込んだツールからすでに取得しています。パスを推測したり、$HOME から find を実行したり、ファイルシステム全体を検索したりしないでください。

コンテキストから <skill-dir> がわからない場合は、諦める前に ls を使って以下の場所を順番に確認してください。

1. $RUNWAY_SKILLS_DIR/skills/use-runway-api/scripts/runway-api.mjs（環境変数が設定されている場合）
2. ~/.claude/plugins/cache/*/runway-api/skills/use-runway-api/scripts/runway-api.mjs（Claude Code プラグインのインストール先）
3. ~/.cursor/plugins/cache/*/runway-api/skills/use-runway-api/scripts/runway-api.mjs（Cursor プラグインのインストール先）
4. ~/.claude/skills/use-runway-api/scripts/runway-api.mjs（npx skills add によるインストール先）
5. ~/.agents/skills/use-runway-api/scripts/runway-api.mjs（汎用エージェントのインストール先）
6. ~/Documents/github/runway/skills/skills/use-runway-api/scripts/runway-api.mjs（ソースのチェックアウト先）

最初に見つかったパスを <skill-dir>/scripts/runway-api.mjs として選び、セッション中はそれを使用してください。コマンドごとにパスを再確認しないでください。

最初の呼び出しの前に

セッション ID を設定し、このチャット内のすべてのリクエストを関連付けられるようにしてから、認証情報を確認します。

export RUNWAY_SKILLS_CLIENT_ID=$(node -e "console.log(crypto.randomUUID())")
node <skill-dir>/scripts/runway-api.mjs auth status

• authenticated が true の場合 → API 呼び出しに進みます。再確認しないでください。
• authenticated が false の場合 → RUNWAY_SKILLS_API_SECRET を設定するようユーザーに伝え（詳細は AUTH.md を参照）、ユーザーの確認を待って停止します。再試行したり、ループして再確認したりしないでください。

ステージング環境に関する注意： auth status は /v1/organization にアクセスします。このエンドポイントは、データエンドポイントが正常に動作していてもステージング環境では 500 を返すことがあります。ステージング環境で auth status が失敗しても、RUNWAY_SKILLS_API_SECRET_STAGE が設定されている場合は、諦める前に avatars list --stage などのデータエンドポイントを試してキーが機能することを確認してください。

簡易コマンド

一覧表示のみのリクエストでは、汎用の request コマンドではなく、まず簡易一覧コマンドを使用してください。

• アバターの一覧 → node <skill-dir>/scripts/runway-api.mjs avatars list
• 音声の一覧 → node <skill-dir>/scripts/runway-api.mjs voices list
• ドキュメントの一覧 → node <skill-dir>/scripts/runway-api.mjs documents list [--avatar-id <id>]

これらのコマンドは、一覧表示に適した小さな JSON を返すように設計されています。一覧コマンドが成功したら、結果を一度だけ回答してください。コマンドを再実行したり、同じ出力を読み上げたり、同じ表を二度表示したりしないでください。

出力形式

API が通常のレコード一覧を返す場合は、箇条書きだけで示すのではなく、簡潔な Markdown テーブルを優先してください。

推奨される列：

• アバター：Name、Status、Voice、Docs、Created
• ドキュメント：Name、Avatar、Created
• 音声：Name、Provider、Preview

表の後には、特に注目すべき点がある場合に限り、短い要約を 1 行追加してください。同じ表を別のブロックに再掲しないでください。

汎用リクエスト

任意の公開 API エンドポイントを呼び出します。

node <skill-dir>/scripts/runway-api.mjs request <METHOD> <path> [--body '<json>'] [--stdin] [--dry-run]

出力はすべて JSON です。エラーは標準エラー出力に送られ、ゼロ以外の終了コードが返されます。また、修正可能な呼び出し例を含む example フィールドが含まれます。

フラグ：

• --body <json> — JSON リクエスト本文をインラインで指定します
• --stdin — 標準入力から JSON 本文を読み込みます（大きなペイロードや複数行のペイロードに便利です）
• --dry-run — 実行せずにリクエスト全体（メソッド、URL、ヘッダー、本文）を表示します
• --help — すべてのコマンドの使い方と例を表示します

以下の API リファレンスを、次の項目の正式な情報源として使用してください。 https://docs.dev.runwayml.com/llms.txt

• モデルの選択肢
• エンドポイントの詳細
• POST/PATCH 本文の正確な形式
• 必須フィールドと任意フィールド

このスキル内でリクエストスキーマを重複して記述したり、独自に作成したりしないでください。単純な GET/DELETE 呼び出しや、上記のリスト取得の簡易パスでは、API リファレンス全体を取得する必要はありません。

例

組織情報を取得する：

node <skill-dir>/scripts/runway-api.mjs request GET /v1/organization

アバターの一覧を取得する：

node <skill-dir>/scripts/runway-api.mjs avatars list

特定のアバターを取得する：

node <skill-dir>/scripts/runway-api.mjs request GET /v1/avatars/<id>

アバターを更新する：

node <skill-dir>/scripts/runway-api.mjs request PATCH /v1/avatars/<id> --body '{
  "personality": "Updated personality text"
}'

アバターを削除する（先にプレビュー）：

node <skill-dir>/scripts/runway-api.mjs request DELETE /v1/avatars/<id> --dry-run
node <skill-dir>/scripts/runway-api.mjs request DELETE /v1/avatars/<id>

アバターのナレッジドキュメントの一覧を取得する：

node <skill-dir>/scripts/runway-api.mjs documents list --avatar-id <avatar-id>

ナレッジドキュメントを作成する：

node <skill-dir>/scripts/runway-api.mjs request POST /v1/documents --body '{
  "avatarId": "<avatar-id>",
  "name": "FAQ",
  "content": "Q: What is your return policy?\nA: 30 days, no questions asked."
}'

音声の一覧を取得する：

node <skill-dir>/scripts/runway-api.mjs voices list

タスクの待機

生成エンドポイントはタスク ID を返します。生成呼び出しの直後に必ず wait を実行してください。待機するかどうかをユーザーに尋ねないでください。

node <skill-dir>/scripts/runway-api.mjs wait <task-id>

生成リクエスト

ユーザーが画像、動画、または音声の生成を依頼した場合：

1. https://docs.dev.runwayml.com/llms.txt を取得し、最初の生成 POST の前に、現在のモデルと API リファレンスを確認します。
2. 現在のドキュメントに記載されているモデルを選択し、選択したモデルを簡潔にユーザーへ伝えます。
3. モデル固有の API 契約に基づいてリクエスト本文を作成します。フィールド名を推測しないでください。
4. その本文を使って生成エンドポイントを 1 回呼び出します。
5. wait を自動的に実行します。
6. 以下の生成結果の提示のルールに従って結果を提示します。

生成リクエストでは、最新の API リファレンスの確認を省略しないでください。単純な一覧取得、取得、削除のリクエストでは、必要がない限り取得しないでください。

ユーザーが「画像を生成して」とだけ述べていても、周囲の文脈が明らかに Runway のアカウント操作またはこのスキルに関するものである場合は、汎用の組み込み画像ツールではなく、Runway API を使用してください。

生成結果の提示

wait コマンドは、署名付き URL の配列を含む output を持つタスクを返します。これらの URL は24～48 時間で期限切れとなり、長い署名付き JWT の文字列のため、インラインで読むのは困難です。

生成が成功したら、以下をすべて行ってください。

1. 生成した内容から伝える — モデルと料金を示す短い一文を最初に記載します。例： gen4_image（1080p、8 クレジット）で生成しました。
2. 画像を Markdown でインライン表示し、クリックしなくてもユーザーが見られるようにします。

   ![Fox in a snowy forest](https://storage.runway.../signed-url)
   

   動画は、ほとんどのチャット UI でインライン動画が表示されないため、通常の Markdown リンク（[fox.mp4](...)）にします。
3. 同じメッセージ内で、ローカルコピーの保存をあらかじめ提案します。予測しやすいパス（./generated/ または ./runway-outputs/）を提案し、可能であればプロンプトからファイル名を推測します。例：

   ./generated/fox.png に保存しましょうか？署名付き URL は約 24～48 時間で期限切れになります。

4. ユーザーが求めない限り、署名付き URL 全体をプレーンテキストで貼り付けないでください。Markdown の画像またはリンクに URL がすでに含まれています。

ユーザーがダウンロードを了承した場合は、curl -L -o <path> '<url>' で取得します（URL には & が含まれるため、引用符で囲んでください）。

API リファレンス

正式な最新の API 契約を確認するには、https://docs.dev.runwayml.com/llms.txt を使用してください。

ステージング（--stage）

任意のコマンドに --stage を追加すると、ステージング API を対象にできます。

node <skill-dir>/scripts/runway-api.mjs --stage avatars list
node <skill-dir>/scripts/runway-api.mjs --stage request GET /v1/avatars

--stage を指定すると、CLI はまず RUNWAY_SKILLS_API_SECRET_STAGE を確認し、設定されていない場合は RUNWAY_SKILLS_API_SECRET にフォールバックします。ベース URL の既定値は https://api.dev-stage.runwayml.com です。

大きなペイロード（--stdin）

アバターの referenceImage 用の Base64 エンコード画像など、データ URI を使ってリソースを作成する場合、本文がシェル引数の上限を超えることがあります。--stdin を使って本文をパイプで渡してください。

python3 -c "
import json, base64
with open('image.png', 'rb') as f:
    b64 = base64.b64encode(f.read()).decode()
body = json.dumps({'name': 'My Avatar', 'referenceImage': f'data:image/png;base64,{b64}', ...})
with open('/tmp/body.json', 'w') as f:
    f.write(body)
" && cat /tmp/body.json | node <skill-dir>/scripts/runway-api.mjs request POST /v1/avatars --stdin

または、JSON をファイルに書き込み、curl -d @file を直接使ってください。小さな JSON ペイロードには --body フラグを使えますが、画像のデータ URI が約 200KB を超えると argument list too long エラーが発生します。

環境変数

ランタイムは、プロセス環境から認証情報を読み取ります。

変数	説明
RUNWAY_SKILLS_API_SECRET	本番環境の API キー
RUNWAY_SKILLS_API_SECRET_STAGE	ステージ環境の API キー（--stage と併用）
RUNWAY_SKILLS_BASE_URL	任意の環境のベース URL を上書きします
RUNWAY_SKILLS_DIR	任意。スキルリポジトリのソースチェックアウトへの絶対パスです。<skill-dir> の解決時にエージェントのフォールバックとして使用されます。

エージェントから RUNWAY_SKILLS_API_SECRET が見えない場合は、変数を設定した後にエディターを再起動する必要がある可能性があります。

関連ファイル

• AUTH.md — このスキルの認証設定とトラブルシューティング

アプリケーションとの統合

アカウント操作を直接実行するのではなく、アプリケーションコードを構築または保守する場合は、+runway-dev を +runway-dev-models、+runway-dev-model-routers、+runway-dev-characters、+runway-dev-recipes、または +runway-dev-workflows と併用してください。