runwayml 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
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 uvmust succeedRUNWAYML_API_SECRETmust 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=URLfetches arbitrary remote images via the Runway API. Prefer local file paths (uploaded asrunway://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), orgen4_image_turboif 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_SECRETonly — no--api-keyflag, to keep secrets out of shell history and process listings.
Filename Convention
Pattern: yyyy-mm-dd-hh-mm-ss-name.png
Examples
Basic image:
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):
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):
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-> setRUNWAYML_API_SECRETin the environment (e.g.export RUNWAYML_API_SECRET=...or a.envfile).Error: Task failed -- SAFETY.INPUT.*-> content moderation, suggest different promptAPI error 429-> rate limited, script auto-retries