rw-integrate-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Integrate Image Generation

集成图像生成

PREREQUISITE: Run
+rw-check-compatibility
first. Run
+rw-fetch-api-reference
to load the latest API reference before integrating. Requires
+rw-setup-api-key
for API credentials. Requires
+rw-integrate-uploads
when the user has local reference images.

Help users add Runway image generation to their server-side code.

前置要求： 先运行
+rw-check-compatibility
。集成前运行
+rw-fetch-api-reference
加载最新API参考文档。需要通过
+rw-setup-api-key
配置API凭证。若用户使用本地参考图，需先执行
+rw-integrate-uploads
。

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

Available Models

可用模型

Model	Best For	Cost	Speed
`gen4_image`	Highest quality	5 credits (720p), 8 credits (1080p)	Standard
`gen4_image_turbo`	Fast generation	2 credits	Fast
`gemini_2.5_flash`	Google Gemini model	5 credits	Standard

Model selection guidance:

Default recommendation: gen4_image
— best quality
Budget/speed: gen4_image_turbo
— cheapest and fastest

模型	适用场景	成本	生成速度
`gen4_image`	最高画质	5积分（720p），8积分（1080p）	标准
`gen4_image_turbo`	快速生成	2积分	快速
`gemini_2.5_flash`	Google Gemini模型	5积分	标准

模型选择指南：

默认推荐：gen4_image
—— 画质最佳
预算/速度优先：gen4_image_turbo
—— 成本最低且生成最快

Security

安全注意事项

referenceImages[].uri

is fetched server-side by the Runway API — treat it like any outbound fetch:

Prefer
runway://
URIs from
```
+rw-integrate-uploads
```
— scoped to your account, no arbitrary web content.
If accepting URLs from clients, validate first: require
```
https://
```
, allowlist trusted hosts, reject private addresses. See the Express.js example below.
Never forward
req.body.referenceImages
straight into
```
textToImage.create
```
. The SDK snippets below use raw URLs for brevity — they aren't production templates.
Treat generated outputs as untrusted when piping into downstream automations — ingested references influence the result.

referenceImages[].uri

由Runway API在服务端获取——需像处理任何外部请求一样对待：

优先使用
+rw-integrate-uploads
返回的
runway://
URI——此类URI绑定到你的账户，不会加载任意网络内容。
若接受客户端传入的URL，需先验证：要求使用
```
https://
```
协议，仅允许可信域名，拒绝私有地址。详见下方Express.js示例。
切勿直接将
req.body.referenceImages
传入
textToImage.create
。下方SDK示例为简洁起见使用原始URL，但它们并非生产环境模板。
当下游自动化流程使用生成结果时，需将其视为不可信内容——参考图会影响生成结果。

Endpoint:

POST /v1/text_to_image

接口：

POST /v1/text_to_image

Basic Text-to-Image

基础文本转图像

javascript

// 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

undefined

javascript

// 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

undefined

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]

undefined

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]

undefined

With Reference Images

结合参考图

Reference images let you guide the generation with visual references. Use

@Tag

syntax in the prompt to reference specific images.

Recommended: upload via

+rw-integrate-uploads

and pass the returned

runway://

URI.

javascript

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();

External URLs also work — only pass origins you control (see Security):

javascript

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();

python

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()

参考图可通过视觉参考引导图像生成。在提示词中使用

@Tag

语法引用特定图像。

推荐方式： 通过

+rw-integrate-uploads

上传图片，传入返回的

runway://

URI。

javascript

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也可使用——仅传入你可控的源（详见安全注意事项）：

javascript

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();

python

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()

Common Parameters

通用参数

Parameter	Type	Description
`model`	string	Model ID (required)
`promptText`	string	Text description of the image (required)
`ratio`	string	Aspect ratio, e.g. `'1280:720'` , `'720:1280'` , `'1080:1080'`
`referenceImages`	array	Optional. Array of `{ uri, tag }` objects for visual guidance

参数	类型	描述
`model`	string	模型ID（必填）
`promptText`	string	图像的文本描述（必填）
`ratio`	string	宽高比，例如 `'1280:720'` 、 `'720:1280'` 、 `'1080:1080'`
`referenceImages`	array	可选。用于视觉引导的 `{ uri, tag }` 对象数组

Integration Pattern

集成模式

Prefer uploads over URLs — Default to
```
+rw-integrate-uploads
```
so inputs are
```
runway://
```
URIs. External URLs only from origins you control (see Security).
Write the server-side handler — Create an API route or server function.
Handle the output — Download and store the image, don't serve signed URLs to clients.
Add error handling — Wrap in try/catch.

优先使用上传而非URL——默认使用
```
+rw-integrate-uploads
```
，确保输入为
```
runway://
```
URI。仅从你可控的源获取外部URL（详见安全注意事项）。
编写服务端处理器——创建API路由或服务端函数。
处理输出结果——下载并存储图像，不要将签名URL直接提供给客户端。
添加错误处理——使用try/catch包裹代码。

Example: Express.js API Route

示例：Express.js API路由

javascript

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 });
  }
});

For browser uploads: POST files to your server, upload via
+rw-integrate-uploads
, and pass the
runway://
URI. Don't accept raw URLs from the browser.

javascript

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

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

// `runway://` URI无需此检查；外部URL必须匹配白名单。
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。

Example: Next.js API Route

示例：Next.js API路由

typescript

// 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 }
    );
  }
}

typescript

// 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 }
    );
  }
}

Example: FastAPI Route

示例：FastAPI路由

python

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))

python

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))

Tips

提示

Output URLs expire in 24-48 hours. Download images to your own storage immediately.
Reference images use
@Tag
syntax in the prompt — the tag must match the
```
tag
```
field in the
```
referenceImages
```
array.
For local files, always upload via
```
+rw-integrate-uploads
```
first, then use the
```
runway://
```
URI.
gen4_image_turbo
is the cheapest option at 2 credits per image — good for prototyping.

输出URL的有效期为24-48小时。请立即将图片下载到你自己的存储服务中。
参考图在提示词中使用
@Tag
语法——标签必须与
```
referenceImages
```
数组中的
```
tag
```
字段匹配。
对于本地文件，务必先通过
```
+rw-integrate-uploads
```
上传，再使用
```
runway://
```
URI。
**
```
gen4_image_turbo
```
**是成本最低的选项，每张图片仅需2积分——适合原型开发。

rw-integrate-image

Original

Translation

Integrate Image Generation

集成图像生成

Available Models

可用模型

Security

安全注意事项

Endpoint:
`POST /v1/text_to_image`

接口：
`POST /v1/text_to_image`

Basic Text-to-Image

基础文本转图像

Python SDK

Python SDK

With Reference Images

结合参考图

Common Parameters

通用参数

Integration Pattern

集成模式

Example: Express.js API Route

示例：Express.js API路由

Example: Next.js API Route

示例：Next.js API路由

Example: FastAPI Route

示例：FastAPI路由

Tips

提示

rw-integrate-image

Original

Translation

Integrate Image Generation

集成图像生成

Available Models

可用模型

Security

安全注意事项

Endpoint: POST /v1/text_to_image

接口：POST /v1/text_to_image

Basic Text-to-Image

基础文本转图像

Python SDK

Python SDK

With Reference Images

结合参考图

Common Parameters

通用参数

Integration Pattern

集成模式

Example: Express.js API Route

示例：Express.js API路由

Example: Next.js API Route

示例：Next.js API路由

Example: FastAPI Route

示例：FastAPI路由

Tips

提示

Endpoint:
`POST /v1/text_to_image`

接口：
`POST /v1/text_to_image`