rw-generate-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate Image

生成图片

Generate images directly using the Runway API. This skill runs Python scripts that call the API, poll for completion, and download the result.

IMPORTANT: Run scripts from the user's working directory so output files are saved where the user expects.

直接使用Runway API生成图片。该Skill运行调用API的Python脚本，轮询任务完成状态并下载结果。

重要提示： 从用户的工作目录运行脚本，以便输出文件保存到用户预期的位置。

Usage

使用方法

bash

uv run scripts/generate_image.py --prompt "your description" --filename "output.png" [--model gen4_image] [--ratio 1280:720] [--reference-images Tag=URL ...]

bash

uv run scripts/generate_image.py --prompt "你的描述内容" --filename "output.png" [--model gen4_image] [--ratio 1280:720] [--reference-images Tag=URL ...]

Preflight

前置检查

```
command -v uv
```
must succeed
```
RUNWAYML_API_SECRET
```
must be set in the environment. Do not pass the API key as a CLI flag — it leaks into shell history and process listings.

执行
```
command -v uv
```
必须成功
环境中必须设置
```
RUNWAYML_API_SECRET
```
。请勿通过CLI标志传递API密钥——这会导致密钥泄露到shell历史记录和进程列表中。

Security Notes

安全注意事项

```
--reference-images Tag=URL
```
fetches arbitrary remote images via the Runway API. Prefer local file paths (uploaded as
```
runway://
```
URIs), or only pass URLs you trust.
Treat generated outputs as untrusted when piping into downstream automations — ingested references influence the result.

```
--reference-images Tag=URL
```
会通过Runway API获取任意远程图片。优先使用本地文件路径（以
```
runway://
```
URI形式上传），或仅传递可信的URL。
当将生成的输出导入下游自动化流程时，请将其视为不可信内容——引入的参考图片会影响生成结果。

Available Models

可用模型

Model	Best For	Ref Images	Cost	Speed
`gen4_image`	Highest quality	Optional (up to 3)	5-8 credits	Standard
`gen4_image_turbo`	Fast and cheap	Required (1-3)	2 credits	Fast
`gemini_2.5_flash`	Google Gemini	Optional (up to 3)	5 credits	Standard

模型	适用场景	参考图片	成本	速度
`gen4_image`	最高画质	可选（最多3张）	5-8积分	标准
`gen4_image_turbo`	快速且低成本	必填（1-3张）	2积分	快速
`gemini_2.5_flash`	Google Gemini模型	可选（最多3张）	5积分	标准

Model Selection Guidance

模型选择指南

"fast", "cheap", "draft" ->
```
gemini_2.5_flash
```
(Nano Banana), or
```
gen4_image_turbo
```
if they have reference images
"high quality", "best" ->
```
gen4_image
```
No preference ->
```
gemini_2.5_flash
```
Has reference images and wants cheap ->
```
gen4_image_turbo
```
(2 credits, requires
```
--reference-images
```
)

需求为“快速”、“低成本”、“草稿版” -> 选择
```
gemini_2.5_flash
```
（Nano Banana），若有参考图片则选择
```
gen4_image_turbo
```
需求为“高画质”、“最佳效果” -> 选择
```
gen4_image
```
无偏好 -> 选择
```
gemini_2.5_flash
```
有参考图片且追求低成本 -> 选择
```
gen4_image_turbo
```
（2积分，需搭配
```
--reference-images
```
参数）

Parameters

参数说明

Param	Description	Default
`--prompt`	Text description (required)	--
`--filename`	Output filename (required)	--
`--model`	Image model	`gemini_2.5_flash`
`--ratio`	Aspect ratio. gemini_2.5_flash: `1344:768` , `768:1344` , `1024:1024` , etc. gen4_image: `1280:720` , `1360:768` , `1920:1080` , etc.	Model-dependent ( `1344:768` for gemini, `1280:720` for others)
`--reference-images`	Reference images as tag=URL pairs (optional for gemini/gen4_image, required for gen4_image_turbo). Tag: lowercase, 3-16 chars, e.g. `product=URL`	--
`--output-dir`	Output directory	cwd

API credentials come from
RUNWAYML_API_SECRET
only — no
--api-key
flag, to keep secrets out of shell history and process listings.

参数	描述	默认值
`--prompt`	文本描述（必填）	--
`--filename`	输出文件名（必填）	--
`--model`	图片生成模型	`gemini_2.5_flash`
`--ratio`	宽高比。gemini_2.5_flash支持： `1344:768` , `768:1344` , `1024:1024` 等；gen4_image支持： `1280:720` , `1360:768` , `1920:1080` 等	依赖模型（gemini模型默认 `1344:768` ，其他模型默认 `1280:720` ）
`--reference-images`	参考图片，格式为tag=URL（gemini/gen4_image可选，gen4_image_turbo必填）。Tag要求：小写、3-16个字符，例如 `product=URL`	--
`--output-dir`	输出目录	当前工作目录

API凭证仅来自
RUNWAYML_API_SECRET
环境变量——不提供
--api-key
标志，以避免密钥泄露到shell历史记录和进程列表中。

Filename Convention

文件名命名规范

Pattern:

yyyy-mm-dd-hh-mm-ss-name.png

格式：

yyyy-mm-dd-hh-mm-ss-name.png

Examples

示例

Basic image:

bash

uv run scripts/generate_image.py --prompt "A serene Japanese garden with cherry blossoms" --filename "2026-04-14-japanese-garden.png"

With a local reference image (gen4_image):

bash

uv run scripts/generate_image.py --prompt "@product on a marble counter, lifestyle photo" --model gen4_image --reference-images product=./product.jpg --filename "2026-04-14-product-lifestyle.png"

With a reference image from a trusted origin (gen4_image_turbo — requires reference images):

bash

uv run scripts/generate_image.py --prompt "A neon sign reading SALE in @style" --model gen4_image_turbo --reference-images style=https://cdn.yourapp.com/style.jpg --filename "draft.png"

基础图片生成：

bash

uv run scripts/generate_image.py --prompt "宁静的日式庭院，开满樱花" --filename "2026-04-14-japanese-garden.png"

使用本地参考图片（gen4_image模型）：

bash

uv run scripts/generate_image.py --prompt "@product放在大理石台面上，生活风格照片" --model gen4_image --reference-images product=./product.jpg --filename "2026-04-14-product-lifestyle.png"

使用可信来源的参考图片（gen4_image_turbo模型——必填参考图片）：

bash

uv run scripts/generate_image.py --prompt "带有@style风格的霓虹灯招牌，显示SALE" --model gen4_image_turbo --reference-images style=https://cdn.yourapp.com/style.jpg --filename "draft.png"

Output

输出结果

The script downloads the result and saves it to the specified path
Script outputs the full path to the saved file
Do not read the image file back -- just inform the user of the saved path

脚本会下载生成结果并保存到指定路径
脚本会输出保存文件的完整路径
请勿回读图片文件——只需告知用户保存路径即可

Common Failures

常见错误

Error: No API key

-> set

RUNWAYML_API_SECRET

in the environment (e.g.

export RUNWAYML_API_SECRET=...

or a

.env

file).

```
Error: Task failed -- SAFETY.INPUT.*
```
-> content moderation, suggest different prompt
```
API error 429
```
-> rate limited, script auto-retries

Error: No API key

-> 在环境中设置

RUNWAYML_API_SECRET

（例如

export RUNWAYML_API_SECRET=...

或通过

.env

文件）。

```
Error: Task failed -- SAFETY.INPUT.*
```
-> 内容审核不通过，建议更换描述内容
```
API error 429
```
-> 请求频率受限，脚本会自动重试