skilld
All skills
runwayml avatar

/rw-generate-image

@c5674fd official
by Runwayrunwayml/skills70 stars
18

Generate images directly using the Runway API via runnable scripts. Supports text-to-image with optional reference images.

Ask your Agent

Use this Skill: https://skilld.dev/gh/runwayml/skills/rw-generate-image

This session only. Nothing lands on disk.

SKILL.md

≈35 tokens always: the name and description. ≈941 when used: this file.

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

  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.

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:

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

Source: SKILL.md on GitHub

Third-party checks

No alerts16d4 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    The skill follows best practices for secret management by using environment variables for the Runway API key. It contains a surface for indirect prompt injection through remote reference image URLs, which is explicitly noted in the skill's security documentation.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at c5674fd. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 5 months ago

Capability

What it can do
Reads files Edits files Runs commands
user-invocable
true
All 7 allowed tools
ReadGrepGlobEditWriteBash(uv run *)Bash(command -v uv)

Topics

  • API
  • Python
  • runway
  • image-generation
  • text-to-image
  • gen4
  • gemini
  • reference-images

README badge

README badge for runwayml/skills/rw-generate-image

What it does

Generates images via the Runway API using text prompts and optional reference images, with support for multiple models (gen4_image, gen4_image_turbo, gemini_2.5_flash) at different quality and cost tiers. The skill runs Python scripts that poll for completion and download results to your working directory.

Generated from the current SKILL.md.

Frequently asked

Does this skill require an API key, and how do I provide it?
Yes. The skill requires RUNWAYML_API_SECRET set as an environment variable. Never pass it as a CLI flag — it leaks into shell history and process listings.
Which models are available, and which should I use?
Three models: gen4_image (highest quality, 5-8 credits), gen4_image_turbo (fast, 2 credits, requires reference images), and gemini_2.5_flash (Google Gemini, 5 credits, default). Use gen4_image_turbo for speed with reference images, gen4_image for best quality, and gemini_2.5_flash for no preference.
Can I use reference images, and how?
Yes. Pass them via --reference-images tag=URL. Local file paths are preferred over remote URLs for security. gen4_image_turbo requires at least one reference image; the others accept up to 3 optional reference images.
What aspect ratios are supported?
Supported ratios vary by model. gemini_2.5_flash supports 1344x768, 768x1344, 1024x1024, etc. gen4_image supports 1280x720, 1360x768, 1920x1080, and others. Defaults are 1344x768 for gemini and 1280x720 for gen4 variants.
What happens if the request fails due to content moderation?
The script returns an error like Task failed -- SAFETY.INPUT.*. This indicates the prompt was flagged by content moderation; try rephrasing the prompt.

Generated from the current SKILL.md. These answers refresh after source changes.