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.

Usage

bash

uv run scripts/generate_image.py --prompt "your description" --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.

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.

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

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

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.

Filename Convention

Pattern:

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"

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

rw-generate-image

NPX Install

Tags

SKILL.md Content

Generate Image

Usage

Preflight

Security Notes

Available Models

Model Selection Guidance

Parameters

Filename Convention

Examples

Output

Common Failures