rw-integrate-image

画像生成を統合する

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

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

利用可能なモデル

モデル	最適な用途	コスト	速度
gen4_image	最高品質	5 クレジット（720p）、8 クレジット（1080p）	標準
gen4_image_turbo	高速生成	2 クレジット	高速
gemini_2.5_flash	Google Gemini モデル	5 クレジット	標準

モデル選択のガイダンス：

• デフォルトの推奨：gen4_image — 最高品質
• 予算や速度を重視する場合：gen4_image_turbo — 最も安価で高速

セキュリティ

referenceImages[].uri は Runway API によってサーバーサイドで取得されます。他の外部リクエストと同様に扱ってください。

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

エンドポイント：POST /v1/text_to_image

基本的なテキストから画像への変換

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

const client = new RunwayML();

const task = await client.textToImage.create({
  model: 'gen4_image',
  promptText: 'A serene Japanese garden with cherry blossoms and a koi pond',
  ratio: '1280:720'
}).waitForTaskOutput();

const imageUrl = task.output[0];

# Python SDK
from runwayml import RunwayML

client = RunwayML()

task = client.text_to_image.create(
    model='gen4_image',
    prompt_text='A serene Japanese garden with cherry blossoms and a koi pond',
    ratio='1280:720'
).wait_for_task_output()

image_url = task.output[0]

参照画像を使用する場合

参照画像を使うと、視覚的な参照情報を使って生成をガイドできます。プロンプトでは @Tag 構文を使って特定の画像を参照してください。

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

import fs from 'fs';

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

const task = await client.textToImage.create({
  model: 'gen4_image',
  promptText: 'A portrait in the style of @Reference',
  referenceImages: [
    { uri: refUpload.runwayUri, tag: 'Reference' }
  ],
  ratio: '1280:720'
}).waitForTaskOutput();

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

const task = await client.textToImage.create({
  model: 'gen4_image',
  promptText: '@EiffelTower painted in the style of @StarryNight',
  referenceImages: [
    { uri: 'https://cdn.yourapp.com/eiffel-tower.jpg', tag: 'EiffelTower' },
    { uri: 'https://cdn.yourapp.com/starry-night.jpg', tag: 'StarryNight' }
  ],
  ratio: '1280:720'
}).waitForTaskOutput();

task = client.text_to_image.create(
    model='gen4_image',
    prompt_text='@EiffelTower painted in the style of @StarryNight',
    reference_images=[
        {"uri": "https://cdn.yourapp.com/eiffel-tower.jpg", "tag": "EiffelTower"},
        {"uri": "https://cdn.yourapp.com/starry-night.jpg", "tag": "StarryNight"}
    ],
    ratio='1280:720'
).wait_for_task_output()

共通パラメーター

パラメーター	型	説明
model	string	モデル ID（必須）
promptText	string	画像のテキストによる説明（必須）
ratio	string	アスペクト比。例：'1280:720'、'720:1280'、'1080:1080'
referenceImages	array	任意。視覚的なガイダンスに使う { uri, tag } オブジェクトの配列

統合パターン

1. URL よりアップロードを優先する — 入力が runway:// URI になるよう、デフォルトで +rw-integrate-uploads を使用してください。外部 URL は自分が管理するオリジンからのものに限ってください（「セキュリティ」を参照）。
2. サーバーサイドのハンドラーを作成する — API ルートまたはサーバー関数を作成してください。
3. 出力を処理する — 画像をダウンロードして保存し、署名付き URL をクライアントに配信しないでください。
4. エラー処理を追加する — try/catch で囲んでください。

例：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 validateReferenceImages(refs) {
  if (!Array.isArray(refs)) throw new Error('referenceImages must be an array');
  return refs.map(({ uri, tag }) => {
    if (typeof uri !== 'string' || typeof tag !== 'string') {
      throw new Error('each reference needs a uri and tag');
    }
    if (uri.startsWith('runway://')) return { uri, tag };
    const u = new URL(uri);
    if (u.protocol !== 'https:') throw new Error('https required');
    if (!ALLOWED_MEDIA_HOSTS.has(u.hostname)) throw new Error('untrusted media host');
    return { uri: u.toString(), tag };
  });
}

app.post('/api/generate-image', async (req, res) => {
  try {
    const { prompt, model = 'gen4_image', ratio = '1280:720', referenceImages } = req.body;

    const task = await client.textToImage.create({
      model,
      promptText: prompt,
      ratio,
      ...(referenceImages && { referenceImages: validateReferenceImages(referenceImages) })
    }).waitForTaskOutput();

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

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

例：Next.js API ルート

// app/api/generate-image/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, referenceImages } = await request.json();

  try {
    const task = await client.textToImage.create({
      model: 'gen4_image',
      promptText: prompt,
      ratio: '1280:720',
      ...(referenceImages && { referenceImages })
    }).waitForTaskOutput();

    return NextResponse.json({ imageUrl: 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 ImageRequest(BaseModel):
    prompt: str
    model: str = "gen4_image"
    ratio: str = "1280:720"
    reference_images: list[dict] | None = None

@app.post("/api/generate-image")
async def generate_image(req: ImageRequest):
    try:
        params = {
            "model": req.model,
            "prompt_text": req.prompt,
            "ratio": req.ratio,
        }
        if req.reference_images:
            params["reference_images"] = req.reference_images

        task = client.text_to_image.create(**params).wait_for_task_output()
        return {"image_url": task.output[0]}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

ヒント

• 出力 URL の有効期限は 24～48 時間です。 画像はすぐにダウンロードし、自分のストレージに保存してください。
• 参照画像はプロンプトで @Tag 構文を使います。タグは referenceImages 配列の tag フィールドと一致させる必要があります。
• ローカルファイルの場合は、必ず最初に +rw-integrate-uploads 経由でアップロードし、その後 runway:// URI を使用してください。
• gen4_image_turbo は画像 1 枚あたり 2 クレジットで最も安価な選択肢です。プロトタイピングに適しています。