runway-image

What it does

Guides an AI agent to generate, edit, and iterate still images using Runway's official API, prioritizing native Gen-4 Image and Gen-4 Image Turbo workflows. It includes how to choose between text-to-image, reference-guided generation, or natural-language edits, and emphasizes task polling, artifact handling, production retries, cost controls, and QA checks. It explicitly excludes Runway video endpoints, UIs, unofficial wrappers, or third-party gateways.

How it works

• Establish a detailed first response before actions: specify desired output (subject, environment, style, aspect), mode (text-only, reference-guided, or edit), references with roles, delivery details, and runtime (REST, Python SDK, or Node SDK). If details are missing, propose defaults and ask only questions that materially affect cost or output; do not bill without approval.
• Use the Runway-native models: gen4_image for high-quality generation and edits; gen4_image_turbo for faster, lower-cost iterations with references. Each model has defined inputs, reference requirements, and cost credits per image.
• Follow the exact native request schema: include model, promptText, ratio, referenceImages with required uri, optional tag, and optional seed and content moderation fields. Enforce tag formatting and note constraints on references.
• Manage input media: support HTTPS URLs, data URIs, and runway:// ephemeral uploads; limit formats to JPEG/PNG/WebP; cite size limits and host requirements. Provide guidance on using signed asset endpoints for customer-hosted references.
• Apply prompt and reference design: write descriptive text prompts; use tagged references to control composition; for edits, describe target and invariants; perform one complex change per iteration.
• Operate in an asynchronous lifecycle: create a task and poll GET /v1/tasks/{id} with status handling (PENDING, THROTTLED, RUNNING, SUCCEEDED, FAILED, CANCELLED). Use exponential backoff and store results locally; download outputs promptly and store manifests. Do not cancel remote tasks via local cancellation unless intended.
• Provide a complete direct REST example (Python) for creating a text-only gen4_image task, polling, and downloading outputs while redacting credentials.

When to use it

• When implementing Runway text-to-image or reference-driven image generation, or natural-language image edits.
• When you need task polling, secure artifact handling, production retries, cost controls, or Runway image API QA.
• Do not use for Runway video generation or third-party gateway APIs.

What it can touch

• Network endpoints via REST or SDKs (Python or Node) to Runway API: v1/text_to_image, v1/tasks/{id}, v1/uploads.
• Local storage for task manifests and outputs; signing and storing artifacts per policy.

Caveats

• Verified against Runway documentation as of 2026-07-09; capabilities and endpoints may change—recheck API reference, model catalog, pricing, and terms before production.
• Keys must be kept secret; never expose bearer tokens to reference hosts or output CDNs; organizational keys may not be revoked by user removal alone.
• No documented Gen-4 still-image mask/inpaint route; edits use source as reference with described changes; do not invent masks or weights.
• Pricing notes: costs per image depend on model and resolution; Turbo uses reference-driven iteration with different costs; confirm current rates.
• Output URLs expire in 24–48 hours; download promptly and store in own controlled bucket.