rw-api-reference

Runway 公開 API リファレンス

前提条件： まず +rw-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
seedance2	POST /v1/text_to_video、POST /v1/image_to_video、または POST /v1/video_to_video	テキスト、画像、および／または動画	36

動画の長さ：2～15 秒（モデルによって異なります）。アスペクト比はピクセル単位です：1280:720、720:1280、1104:832、960:960、832:1104、1584:672 など。

Seedance 2 の詳細：

• モード：テキストから動画、画像から動画（最初／最後のフレームまたは画像参照）、動画から動画
• 長さ：TTV と ITV では必須です（秒単位）
• アスペクト比（ピクセル単位）：1280:720、720:1280、960:960、1112:834、834:1112、1470:630、992:432、864:496、752:560、640:640、560:752、496:864
• ITV では、相互排他的な 2 つのモードに対応しています：最初／最後のフレーム（position を指定した promptImage 配列）または画像参照（references 配列）
• VTV の入力要件：最大 15 秒、最大 32 MB、最小 720p の解像度。MP4 を推奨します

画像生成

モデル	エンドポイント	コスト（クレジット）
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	テキスト読み上げ	50 文字あたり 1 クレジット
eleven_text_to_sound_v2	POST /v1/sound_effect	効果音	1～2 クレジット
eleven_voice_isolation	POST /v1/voice_isolation	音声から声を分離	6 秒あたり 1 クレジット
eleven_voice_dubbing	POST /v1/voice_dubbing	音声を他の言語に吹き替え	2 秒あたり 1 クレジット
eleven_multilingual_sts_v2	POST /v1/speech_to_speech	音声変換	3 秒あたり 1 クレジット

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

モデル	説明	セッションの最大時間
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: [...] }) を使って、ドキュメントをアバターにリンクします。

---

リクエストボディのリファレンス（raw JSON）

SDK 経由ではなく（たとえば use-runway-api の request コマンドを通じて）API を直接呼び出す際に使用します。必須フィールドと一般的なフィールドのみを記載しています。完全なスキーマについては +rw-fetch-api-reference を参照してください。

POST /v1/text_to_image

{
  "model": "gen4_image",
  "promptText": "A serene Japanese garden with cherry blossoms",
  "ratio": "1920:1080"
}

• model：gen4_image | gen4_image_turbo | gemini_2.5_flash（必須）
• promptText：string、最大約 1000 文字（必須）
• ratio：1920:1080、1080:1920、1024:1024、1360:768、1080:1080、1168:880、1440:1080、1080:1440、1808:768、2112:912 のいずれか（必須。モデルに応じて 720p または 1080p のバリエーション）
• referenceImages：任意の [{ "uri": "https://...", "tag": "MyTag" }] — promptText 内で @MyTag を使って参照
• seed：再現性のための任意の整数

POST /v1/text_to_video

{
  "model": "gen4.5",
  "promptText": "A golden retriever running through wildflowers at sunset",
  "ratio": "1280:720",
  "duration": 5
}

• model：gen4.5 | veo3 | veo3.1 | veo3.1_fast | seedance2（必須）
• duration：秒数を示す整数、2～10（必須。モデルごとに有効な値が異なります。例：veo3 で指定できるのは 8 のみ）
• ratio：例：1280:720、720:1280、1104:832、832:1104、960:960（必須）

POST /v1/image_to_video

{
  "model": "gen4.5",
  "promptImage": "https://example.com/cover.jpg",
  "promptText": "A slow dolly-in shot",
  "ratio": "1280:720",
  "duration": 5
}

• model：gen4.5 | gen4_turbo | veo3 | veo3.1 | veo3.1_fast | seedance2（必須）
• promptImage：HTTPS URL、data URI、または runway:// URI（必須）。キーフレームの場合は [{ "uri": "...", "position": "first" | "last" }] も指定できます。
• promptText：ほとんどのモデルで任意。画像から動きが明らかでない場合、gen4_turbo では必須

POST /v1/video_to_video

{
  "model": "gen4_aleph",
  "videoUri": "https://example.com/source.mp4",
  "promptText": "Change the season to winter with snowfall",
  "ratio": "1280:720"
}

POST /v1/text_to_speech

{
  "model": "eleven_multilingual_v2",
  "text": "Hello, welcome to Runway.",
  "voice": { "type": "runway-preset", "presetId": "clara" }
}

• voice：{ type: "runway-preset", presetId: "clara" | "victoria" | "vincent" | ... } またはプロバイダー固有の音声オブジェクト
• languageCode：任意の ISO コード（デフォルトでは自動検出）

POST /v1/sound_effect

{
  "model": "eleven_text_to_sound_v2",
  "promptText": "Thunderclap followed by heavy rain",
  "duration": 5
}

POST /v1/voice_isolation

{
  "model": "eleven_voice_isolation",
  "audioUri": "https://example.com/noisy.mp3"
}

POST /v1/voice_dubbing

{
  "model": "eleven_voice_dubbing",
  "audioUri": "https://example.com/english.mp3",
  "targetLanguage": "es"
}

POST /v1/speech_to_speech

{
  "model": "eleven_multilingual_sts_v2",
  "audioUri": "https://example.com/source.mp3",
  "voice": { "type": "runway-preset", "presetId": "victoria" }
}

POST /v1/avatars

{
  "name": "Support Agent",
  "referenceImage": "https://example.com/portrait.jpg",
  "voice": { "type": "runway-live-preset", "presetId": "clara" },
  "personality": "You are a friendly support agent.",
  "documentIds": []
}

POST /v1/documents

{
  "avatarId": "<avatar-id>",
  "name": "FAQ",
  "content": "Q: What is your return policy?\nA: 30 days, no questions asked."
}

POST /v1/realtime_sessions

{
  "avatarId": "<avatar-id>"
}

---

管理用エンドポイント

メソッド	エンドポイント	説明
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 サイズ制限が適用されます。