mcpField
R
rw-generate-image

rw-generate-image

github.com/runwaymlCreative & media74324 installsUpdated 2d ago
Repository

About rw-generate-image

rw-generate-image is a skill for generating images through the Runway API, for creators and developers who want to create and save images from the command line. It provides model, aspect-ratio, and reference-image options, then polls the task and downloads the result.

Key features

  1. 01Generate images from text prompts
  2. 02Choose models and aspect ratios
  3. 03Provide reference images
  4. 04Poll generation tasks and download results
  5. 05Read API credentials from an environment variable

Use cases

  1. 01Create images from text descriptions
  2. 02Build scene images using product photos
  3. 03Generate visual drafts from reference images

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/runwayml/skills --skill rw-generate-image

After installing, type/rw-generate-imagein Claude Code to confirm it loaded.

Details

From the project README

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

ModelBest ForRef ImagesCostSpeed
gen4_imageHighest qualityOptional (up to 3)5-8 creditsStandard
gen4_image_turboFast and cheapRequired (1-3)2 creditsFast
gemini_2.5_flashGoogle GeminiOptional (up to 3)5 creditsStandard

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

ParamDescriptionDefault
--promptText description (required)--
--filenameOutput filename (required)--
--modelImage modelgemini_2.5_flash
--ratioAspect 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-imagesReference 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-dirOutput directorycwd

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

Comments

Markdown supported