rw-integrate-video

動画生成を統合する

前提条件： 最初に +rw-check-compatibility を実行してください。統合する前に +rw-fetch-api-reference を実行して、最新の API リファレンスを読み込んでください。API 認証情報には +rw-setup-api-key が必要です。入力としてローカルファイルを使用する場合は、+rw-integrate-uploads が必要です。

ユーザーがサーバーサイドのコードに Runway の動画生成を追加できるよう支援します。

利用可能なモデル

モデル	最適な用途	入力	コスト	速度
seedance2	参照画像や動画、長時間の生成	テキスト、画像、動画のいずれか、または複数	36 クレジット/秒	標準
gen4.5	高品質、汎用	テキスト、画像のいずれか、または両方	12 クレジット/秒	標準
gen4_turbo	高速、画像ベース	画像必須	5 クレジット/秒	高速
gen4_aleph	動画編集・変換	動画 + テキスト/画像	15 クレジット/秒	標準
veo3	Google のプレミアムモデル	テキスト/画像	40 クレジット/秒	標準
veo3.1	高品質な Google モデル	テキスト/画像	20～40 クレジット/秒	標準
veo3.1_fast	高速な Google モデル	テキスト/画像	10～15 クレジット/秒	高速

モデル選択のガイド：

• デフォルトのおすすめ：gen4.5 — 品質とコストのバランスが最適です
• 商品広告・E コマース： seedance2 — 最大 15 秒で、参照画像と動画に対応しています
• コストを抑えたい場合：gen4_turbo（画像が必要）または veo3.1_fast
• 最高品質：veo3（最も高価です）
• 動画から動画への編集：gen4_aleph または seedance2

セキュリティ

promptImage、promptVideo、videoUri、および references[].uri は Runway API がサーバーサイドで取得します。外部へのフェッチと同様に扱ってください。

• +rw-integrate-uploads の runway:// URI を優先してください。アカウントにスコープが限定されており、任意のウェブコンテンツを取得しません。
• クライアントから URL を受け取る場合は、必ず検証してください。https:// を必須とし、信頼できるホストを許可リストに登録し、プライベートアドレスを拒否してください。以下の Express.js の例を参照してください。
• req.body.imageUrl（または同様の値）をそのまま promptImage / promptVideo に渡さないでください。以下の SDK スニペットでは簡潔さのために生の URL を使用していますが、本番環境向けのテンプレートではありません。
• 生成した出力を後続の自動化処理に渡す際は、信頼できないものとして扱ってください。取り込んだメディアは結果に影響します。

エンドポイント

テキストから動画へ：POST /v1/text_to_video

テキストプロンプトのみから動画を生成します。

対応モデル： seedance2、gen4.5、veo3、veo3.1、veo3.1_fast

// Node.js SDK
import RunwayML from '@runwayml/sdk';

const client = new RunwayML();

const task = await client.textToVideo.create({
  model: 'gen4.5',
  promptText: 'A golden retriever running through a field of wildflowers at sunset',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

// task.output is an array of signed URLs
const videoUrl = task.output[0];

# Python SDK
from runwayml import RunwayML

client = RunwayML()

task = client.text_to_video.create(
    model='gen4.5',
    prompt_text='A golden retriever running through a field of wildflowers at sunset',
    ratio='1280:720',
    duration=5
).wait_for_task_output()

video_url = task.output[0]

画像から動画へ：POST /v1/image_to_video

静止画像を動画にアニメーション化します。

対応モデル： seedance2、gen4.5、gen4_turbo、veo3、veo3.1、veo3.1_fast

おすすめ： +rw-integrate-uploads でアップロードし、返された runway:// URI を渡してください。

// Node.js SDK — preferred flow
import fs from 'fs';

const upload = await client.uploads.createEphemeral(
  fs.createReadStream('/path/to/image.jpg')
);

const task = await client.imageToVideo.create({
  model: 'gen4.5',
  promptImage: upload.runwayUri,
  promptText: 'The scene comes to life with gentle wind',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

外部 URL も使用できます。管理下にあるオリジンのみを渡してください（「セキュリティ」を参照）。

const task = await client.imageToVideo.create({
  model: 'gen4.5',
  promptImage: 'https://cdn.yourapp.com/landscape.jpg',
  promptText: 'Camera slowly pans right revealing a mountain range',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

# Python SDK
task = client.image_to_video.create(
    model='gen4.5',
    prompt_image='https://cdn.yourapp.com/landscape.jpg',
    prompt_text='Camera slowly pans right revealing a mountain range',
    ratio='1280:720',
    duration=5
).wait_for_task_output()

動画から動画へ：POST /v1/video_to_video

テキストプロンプトや参照画像を使用して、既存の動画を変換します。

対応モデル： gen4_aleph、seedance2

// Node.js SDK — gen4_aleph
const task = await client.videoToVideo.create({
  model: 'gen4_aleph',
  videoUri: 'https://cdn.yourapp.com/source.mp4',
  promptText: 'Transform into an animated cartoon style',
}).waitForTaskOutput();

// Node.js SDK — seedance2 video-to-video (with optional image reference)
const task = await client.videoToVideo.create({
  model: 'seedance2',
  promptVideo: 'https://cdn.yourapp.com/input.mp4',
  promptText: 'Transform into a warm golden sunset scene',
  references: [{ type: 'image', uri: 'https://cdn.yourapp.com/style_ref.jpg' }]
}).waitForTaskOutput();

seedance2 の VTV 入力要件： 最大 15 秒、最大 32 MB、最小 720p 解像度、MP4 を推奨します。

Seedance 2

Seedance 2 は、テキストから動画への生成、画像から動画への生成（2 つのモード）、および動画から動画への変換に対応しています。ピクセルベースの比率を使用します：1280:720、720:1280、960:960、1112:834、834:1112、1470:630、992:432、864:496、752:560、640:640、560:752、496:864。

テキストから動画へ

const task = await client.textToVideo.create({
  model: 'seedance2',
  promptText: 'A calm ocean wave gently crashing on a sandy beach at sunset',
  duration: 5,
  ratio: '1280:720'
}).waitForTaskOutput();

画像から動画へ — モード 1：最初／最後のフレーム

特定の画像を最初および／または最後のフレームとして使用します。このモードでは references フィールドを使用できません。

const task = await client.imageToVideo.create({
  model: 'seedance2',
  promptText: 'Smooth transition from day to night in a cozy mountain cabin',
  promptImage: [
    { uri: 'https://cdn.yourapp.com/image.jpg', position: 'first' },
    { uri: 'https://cdn.yourapp.com/image2.jpg', position: 'last' }
  ],
  duration: 4,
  ratio: '1280:720'
}).waitForTaskOutput();

promptImage は、uri（必須）と position（"first" または "last"、デフォルトは first）を持つオブジェクトの配列です。

画像から動画 — モード 2：画像参照

画像を文字どおりのフレームとしてではなく、スタイルや内容の参照として使用します。promptImage は引き続き必須です（URI 文字列、または単一要素の配列）。

const task = await client.imageToVideo.create({
  model: 'seedance2',
  promptText: 'Smooth transition from day to night in a cozy mountain cabin',
  promptImage: 'https://cdn.yourapp.com/image.jpg',
  references: [{ type: 'image', uri: 'https://cdn.yourapp.com/reference.jpg' }],
  duration: 4,
  ratio: '1280:720'
}).waitForTaskOutput();

これら 2 つの ITV モードは相互排他的です。同じリクエストで promptImage に position を指定し、references も使用することはできません。

動画から動画

テキストプロンプトを指定して既存の動画を変換します。必要に応じて画像参照も追加できます。

task = client.video_to_video.create(
    model='seedance2',
    prompt_video='https://cdn.yourapp.com/input.mp4',
    prompt_text='Transform into a warm golden sunset scene',
    references=[{'type': 'image', 'uri': 'https://cdn.yourapp.com/style_ref.jpg'}]
).wait_for_task_output()

VTV の入力要件： 最大 15 秒、最大 32 MB、最低解像度 720p、MP4 を推奨します。

Seedance 2 のパラメーター

パラメーター	型	必須	説明
model	string	はい	"seedance2" を指定する必要があります
promptText	string	はい	生成したい動画のテキストによる説明
duration	number	はい（TTV/ITV）	秒単位の長さ
ratio	string	はい（TTV/ITV）	1280:720、720:1280、960:960、1112:834、834:1112、1470:630
promptImage	string or array	はい（ITV）	URI 文字列、または { uri, position? } オブジェクトの配列
promptVideo	string	はい（seedance2 VTV）	入力動画の URI（seedance2 のみ）
videoUri	string	はい（gen4_aleph VTV）	入力動画の URI（gen4_aleph のみ）
references	array	いいえ	画像参照 — [{ type: "image", uri: "..." }]（ITV モード 2 と VTV のみ）

キャラクターの演技：POST /v1/character_performance

表情や身体の演技を加えてキャラクターをアニメーション化します。

互換性のあるモデル： act_two

const task = await client.characterPerformance.create({
  model: 'act_two',
  promptImage: 'https://cdn.yourapp.com/character.jpg',
  promptPerformance: 'https://cdn.yourapp.com/performance.mp4',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

共通パラメーター

パラメーター	型	説明
model	string	モデル ID（必須）
promptText	string	動画の内容を説明するテキストプロンプト
promptImage	string	入力画像の URL、データ URI、または runway:// URI
ratio	string	アスペクト比。例：'1280:720'、'720:1280'
duration	number	秒単位の動画の長さ（2～15、モデルによって異なります）

統合パターン

ユーザーの統合を支援する際は、次のパターンに従ってください。

1. ユースケースを特定する — どの種類の動画生成かを確認します（テキストから動画、画像から動画など）。
2. URL よりアップロードを優先する — 入力に runway:// URI を使用できるよう、デフォルトで +rw-integrate-uploads を使用します。外部 URL は、管理下にあるオリジンのもののみ使用してください（「セキュリティ」を参照）。
3. モデルを選択する — 品質、コスト、速度の要件に基づいて推奨します。
4. サーバー側のハンドラーを作成する — API ルートまたはサーバー関数を作成します。
5. 出力を処理する — 動画をダウンロードして保存し、署名付き URL をクライアントに渡さないでください。
6. エラー処理を追加する — try/catch で囲み、TaskFailedError を処理します。

例：Express.js の API ルート

import RunwayML from '@runwayml/sdk';
import express from 'express';

const client = new RunwayML();
const app = express();
app.use(express.json());

// `runway://` URIs bypass this check; external URLs must match the allowlist.
const ALLOWED_MEDIA_HOSTS = new Set(['cdn.yourapp.com', 'uploads.yourapp.com']);

function assertTrustedMediaUrl(raw) {
  const u = new URL(raw);
  if (u.protocol !== 'https:') throw new Error('https required');
  if (!ALLOWED_MEDIA_HOSTS.has(u.hostname)) throw new Error('untrusted media host');
  return u.toString();
}

app.post('/api/generate-video', async (req, res) => {
  try {
    const { prompt, imageUrl, model = 'gen4.5', duration = 5 } = req.body;

    const params = {
      model,
      promptText: prompt,
      ratio: '1280:720',
      duration
    };

    let task;
    if (imageUrl) {
      task = await client.imageToVideo.create({
        ...params,
        promptImage: assertTrustedMediaUrl(imageUrl)
      }).waitForTaskOutput();
    } else {
      task = await client.textToVideo.create(params).waitForTaskOutput();
    }

    res.json({ videoUrl: task.output[0] });
  } catch (error) {
    console.error('Video generation failed:', error);
    res.status(400).json({ error: error.message });
  }
});

ブラウザーからアップロードする場合：ファイルをサーバーに POST し、+rw-integrate-uploads でアップロードして、runway:// URI を渡してください。ブラウザーから生の URL を受け付けないでください。

例：Next.js の API ルート

// app/api/generate-video/route.ts
import RunwayML from '@runwayml/sdk';
import { NextRequest, NextResponse } from 'next/server';

const client = new RunwayML();

export async function POST(request: NextRequest) {
  const { prompt, imageUrl } = await request.json();

  try {
    const task = imageUrl
      ? await client.imageToVideo.create({
          model: 'gen4.5',
          promptImage: imageUrl,
          promptText: prompt,
          ratio: '1280:720',
          duration: 5
        }).waitForTaskOutput()
      : await client.textToVideo.create({
          model: 'gen4.5',
          promptText: prompt,
          ratio: '1280:720',
          duration: 5
        }).waitForTaskOutput();

    return NextResponse.json({ videoUrl: task.output[0] });
  } catch (error) {
    return NextResponse.json(
      { error: error instanceof Error ? error.message : 'Generation failed' },
      { status: 500 }
    );
  }
}

例：FastAPI のルート

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from runwayml import RunwayML

app = FastAPI()
client = RunwayML()

class VideoRequest(BaseModel):
    prompt: str
    image_url: str | None = None
    model: str = "gen4.5"
    duration: int = 5

@app.post("/api/generate-video")
async def generate_video(req: VideoRequest):
    try:
        if req.image_url:
            task = client.image_to_video.create(
                model=req.model,
                prompt_image=req.image_url,
                prompt_text=req.prompt,
                ratio="1280:720",
                duration=req.duration
            ).wait_for_task_output()
        else:
            task = client.text_to_video.create(
                model=req.model,
                prompt_text=req.prompt,
                ratio="1280:720",
                duration=req.duration
            ).wait_for_task_output()

        return {"video_url": task.output[0]}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

ヒント

• 出力 URL は 24～48 時間で期限切れになります。 生成後すぐに、動画を独自のストレージ（S3、GCS、ローカルファイルシステム）にダウンロードしてください。
• gen4_turbo には画像が必要です — テキストのみの生成には対応していません。
• 動画から動画へのモデル： gen4_aleph と seedance2 — 既存の動画の編集や変換に使用します。
• 長さはモデルによって異なります。 ほとんどのモデルは 2～10 秒に対応しており、seedance2 は最大 15 秒に対応しています。
• waitForTaskOutput() のデフォルトのタイムアウトは 10 分です。 生成に時間がかかる場合は、独自のポーリングループを実装するか、タイムアウトを延長してください。
• **ローカルファイルの場合は、**必ず最初に +rw-integrate-uploads でアップロードしてから、runway:// URI を渡してください。