Back to Details

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

前置检查

  1. command -v uv
    must succeed
  2. 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.
  1. 执行
    command -v uv
    必须成功
  2. 环境中必须设置
    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

可用模型

ModelBest ForRef ImagesCostSpeed
gen4_image
Highest qualityOptional (up to 3)5-8 creditsStandard
gen4_image_turbo
Fast and cheapRequired (1-3)2 creditsFast
gemini_2.5_flash
Google GeminiOptional (up to 3)5 creditsStandard
模型适用场景参考图片成本速度
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

参数说明

ParamDescriptionDefault
--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 directorycwd
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
    -> 请求频率受限，脚本会自动重试