api-reference

Runway Public API Reference

前提条件： まず +check-compatibility を実行し、プロジェクトがサーバー側の機能に対応していることを確認してください。

ベース URL：https://api.dev.runwayml.com

すべてのリクエストに、以下のヘッダーが必要です。

Authorization: Bearer <RUNWAYML_API_SECRET>
X-Runway-Version: 2024-11-06

---

モデルとエンドポイント

動画生成

モデル	エンドポイント	入力	コスト（クレジット/秒）
gen4.5	POST /v1/image_to_video または POST /v1/text_to_video	テキストおよび／または画像	12
gen4_turbo	POST /v1/image_to_video	画像が必要	5
gen4_aleph	POST /v1/video_to_video	動画＋テキスト／画像	15
act_two	POST /v1/character_performance	画像／動画	5
veo3	POST /v1/image_to_video または POST /v1/text_to_video	テキスト／画像	40
veo3.1	POST /v1/image_to_video または POST /v1/text_to_video	テキスト／画像	20-40
veo3.1_fast	POST /v1/image_to_video または POST /v1/text_to_video	テキスト／画像	10-15

動画の長さ：2-10 秒。アスペクト比：1280:720、720:1280、1104:832 など。

画像生成

モデル	エンドポイント	コスト（クレジット）
gen4_image	POST /v1/text_to_image	5（720p）、8（1080p）
gen4_image_turbo	POST /v1/text_to_image	2
gemini_2.5_flash	POST /v1/text_to_image	5

音声生成

モデル	エンドポイント	用途	コスト
eleven_multilingual_v2	POST /v1/text_to_speech	テキスト読み上げ	1 クレジット/50 文字
eleven_text_to_sound_v2	POST /v1/sound_effect	効果音	1-2 クレジット
eleven_voice_isolation	POST /v1/voice_isolation	音声から声を分離	1 クレジット/6 秒
eleven_voice_dubbing	POST /v1/voice_dubbing	音声を他の言語に吹き替え	1 クレジット/2 秒
eleven_multilingual_sts_v2	POST /v1/speech_to_speech	音声変換	1 クレジット/3 秒

キャラクター（リアルタイムアバター）

モデル	説明	セッションの最大時間
gwm1_avatars	GWM-1 を搭載したリアルタイムの会話型アバター	5 分

エンドポイント：

メソッド	エンドポイント	説明
POST	/v1/avatars	新しいアバターを作成
GET	/v1/avatars/{id}	アバターを取得
PATCH	/v1/avatars/{id}	アバターを更新（名前、音声、パーソナリティ、documentIds）
DELETE	/v1/avatars/{id}	アバターを削除
POST	/v1/realtime_sessions	新しいリアルタイムセッションを作成
GET	/v1/realtime_sessions/{id}	セッションのステータスを取得（READY になるまでポーリング）
POST	/v1/realtime_sessions/{id}/consume	WebRTC 用のセッション認証情報を消費（1 回限り）

アバター作成パラメーター：

パラメーター	型	説明
name	string	アバターの表示名
referenceImage	string	キャラクター画像の URL または runway:// URI
voice	object	{ type: 'runway-live-preset', presetId: 'clara' }
personality	string	システムプロンプト／パーソナリティの指示
documentIds	string[]	任意。関連付けるナレッジベース文書の ID

音声プリセット： clara（柔らかい）、victoria（力強い）、vincent（威厳のある）。すべてのプレビューは dev.runwayml.com で確認できます。

セッションのステータス： NOT_READY → READY → RUNNING → COMPLETED（または FAILED／CANCELLED）

ドキュメント（ナレッジベース）

メソッド	エンドポイント	説明
POST	/v1/documents	ドキュメントを作成（プレーンテキストまたは Markdown）
GET	/v1/documents/{id}	ドキュメントを取得
DELETE	/v1/documents/{id}	ドキュメントを削除

各アバターは最大 50,000 トークンのナレッジに対応します。client.avatars.update(id, { documentIds: [...] }) を使って、ドキュメントをアバターにリンクします。

管理エンドポイント

メソッド	エンドポイント	説明
GET	/v1/tasks/{id}	タスクのステータスと出力を取得します
DELETE	/v1/tasks/{id}	タスクをキャンセル／削除します
POST	/v1/uploads	一時的なアップロードを作成します
GET	/v1/organization	組織情報とクレジット残高
POST	/v1/organization/usage	クレジット使用履歴（最大90日分）

---

タスクのライフサイクル

すべての生成エンドポイントはタスクオブジェクトを返します。処理の流れは次のとおりです。

1. 送信 — POST /v1/<endpoint> → { "id": "task_xxx" } を返します
2. ポーリング — GET /v1/tasks/{id} → status を含むタスクを返します
3. 出力の取得 — status === "SUCCEEDED" の場合、output 配列に署名付き URL が含まれます

タスクのステータス

ステータス	意味
PENDING	キューに入り、開始を待っています
RUNNING	生成中です
SUCCEEDED	完了しました — 出力 URL を利用できます
FAILED	生成に失敗しました — failure フィールドを確認してください
THROTTLED	同時実行数の上限に達しました — 自動的にキューに入れられます

SDK によるポーリング（推奨）

SDK には、ポーリングを自動的に処理する waitForTaskOutput() メソッドが用意されています。

// Node.js — polls until complete (default 10 min timeout)
const task = await client.imageToVideo.create({
  model: 'gen4.5',
  promptImage: 'https://example.com/image.jpg',
  promptText: 'A sunset timelapse',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

console.log(task.output); // Array of signed URLs

# Python
task = client.image_to_video.create(
    model='gen4.5',
    prompt_image='https://example.com/image.jpg',
    prompt_text='A sunset timelapse',
    ratio='1280:720',
    duration=5
).wait_for_task_output()

print(task.output)

手動ポーリング（REST）

async function pollTask(taskId) {
  while (true) {
    const response = await fetch(`https://api.dev.runwayml.com/v1/tasks/${taskId}`, {
      headers: {
        'Authorization': `Bearer ${process.env.RUNWAYML_API_SECRET}`,
        'X-Runway-Version': '2024-11-06'
      }
    });
    const task = await response.json();

    if (task.status === 'SUCCEEDED') return task;
    if (task.status === 'FAILED') throw new Error(task.failure);

    await new Promise(r => setTimeout(r, 5000)); // poll every 5 seconds
  }
}

---

出力の処理

• 成功したタスクは、生成コンテンツへの署名付き URLを含む output 配列を返します
• 出力 URL は24～48時間以内に期限切れになります
• 出力をダウンロードして、ご自身のストレージに保存してください — 署名付き URL をエンドユーザーに提供しないでください
• 動画の出力形式は MP4、画像の出力形式は PNG／JPEG です

---

入力要件

サイズ制限

種類	URL 経由	データ URI 経由	アップロード経由
画像	16 MB	5 MB	200 MB
動画	32 MB	16 MB	200 MB
音声	32 MB	16 MB	200 MB

サポートされている形式

• 画像： JPEG、PNG、WebP（GIF は非対応）
• 動画コーデック： H.264、H.265／HEVC、AV1、VP8／VP9、Apple ProRes、Theora
• 音声： MP3、AAC、FLAC、PCM、ALAC

URL の要件

アセットを URL 経由で指定する場合：

• HTTPS のみ（HTTP は不可）
• ドメイン名のみ（IP アドレスは不可）
• リダイレクトなし
• HTTP HEAD リクエストをサポートしていること
• 有効な Content-Type および Content-Length ヘッダーを返すこと
• URL の最大長：2,048文字

---

レート制限とティア

ティア	同時実行数	1日の生成数	月間上限	解除条件
1（デフォルト）	1-2	50-200	$100	—
2	3	500-1,000	$500	1日 + $50
3	5	1,000-2,000	$2,000	7日 + $100
4	10	5,000-10,000	$20,000	14日 + $1,000
5	20	25,000-30,000	$100,000	7日 + $5,000

• 1分あたりのリクエスト数の制限はなく、1日の生成数の上限のみがあります
• 同時実行数の上限を超えると、ステータスは THROTTLED になります（リクエストは拒否されず、自動的にキューに入れられます）
• 1日の上限を超えると、429 Too Many Requests が返されます
• 1日の上限はローリング24時間枠で適用されます

---

エラー処理

HTTP エラー

コード	意味	対応
400	入力検証エラー	入力を修正し、再試行しないでください
401	API キーが無効です	キーを確認し、再試行しないでください
429	レート制限に達しました	指数バックオフとジッターを使用して再試行してください
502/503/504	サーバーが過負荷です	指数バックオフとジッターを使用して再試行してください

タスクの失敗コード

コード	意味	再試行
SAFETY.INPUT.*	入力コンテンツのモデレーション	いいえ — 返金されません
SAFETY.OUTPUT.*	出力コンテンツのモデレーション	はい — 別のプロンプトを試してください
INTERNAL.BAD_OUTPUT	品質の問題	はい
ASSET.INVALID	入力形式が不正です	入力を修正してください
INTERNAL	サーバーエラー	はい

SDK は、一時的なエラーに対する再試行を自動的に処理します。

---

データ URI のサポート

URL の代わりに、Base64 エンコードされた画像を渡すことができます。

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

小さな画像を扱う場合や、ファイルをホストしたくない場合に便利です。上記のデータ URI のサイズ制限が適用されます。