rw-integrate-image

集成图像生成

前置条件： 请先运行 +rw-check-compatibility。集成前运行 +rw-fetch-api-reference，以加载最新的 API 参考文档。API 凭据需要 +rw-setup-api-key。如果用户有本地参考图像，则需要 +rw-integrate-uploads。

帮助用户在服务端代码中添加 Runway 图像生成功能。

可用模型

模型	最适合的用途	成本	速度
gen4_image	最高质量	5 个 credits（720p），8 个 credits（1080p）	标准
gen4_image_turbo	快速生成	2 个 credits	快
gemini_2.5_flash	Google Gemini 模型	5 个 credits	标准

模型选择指南：

• 默认推荐：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	字符串	模型 ID（必填）
promptText	字符串	图像的文字描述（必填）
ratio	字符串	宽高比，例如 '1280:720'、'720:1280'、'1080:1080'
referenceImages	数组	可选。由 { uri, tag } 对象组成的数组，用于提供视觉引导

集成模式

1. 优先使用上传，而非 URL——默认使用 +rw-integrate-uploads，使输入为 runway:// URI。外部 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 是成本最低的选项，每张图像仅需 2 个 credits——适合原型开发。