From runway-api
Integrates RunwayML text-to-image API with reference image support into Node.js or Python server-side code. Use for AI-generated images in apps.
npx claudepluginhub runwayml/skillsThis skill is limited to using the following tools:
> **PREREQUISITE:** Run `+rw-check-compatibility` first. Run `+rw-fetch-api-reference` to load the latest API reference before integrating. Requires `+rw-setup-api-key` for API credentials. Requires `+rw-integrate-uploads` when the user has local reference images.
Generates AI images from text prompts using Runway API via Python scripts run with uv. Supports reference images, aspect ratios, and models like gen4_image, gen4_image_turbo, gemini_2.5_flash. Useful for prototyping visuals or design assets.
Generates AI images using OpenAI, Azure OpenAI, Google, OpenRouter, DashScope, GLM-Image, MiniMax, and Replicate APIs. Supports text-to-image, reference images, aspect ratios, batch from prompt files. Use for generate/create/draw requests. [Deprecated: use baoyu-imagine]
Generates new images from text prompts via EachLabs API using models like Flux, GPT Image, Gemini, Imagen, Seedream. Use for text-to-image creation in code sessions.
Share bugs, ideas, or general feedback.
PREREQUISITE: Run
+rw-check-compatibilityfirst. Run+rw-fetch-api-referenceto load the latest API reference before integrating. Requires+rw-setup-api-keyfor API credentials. Requires+rw-integrate-uploadswhen the user has local reference images.
Help users add Runway image generation to their server-side code.
| Model | Best For | Cost | Speed |
|---|---|---|---|
gen4_image | Highest quality | 5 credits (720p), 8 credits (1080p) | Standard |
gen4_image_turbo | Fast generation | 2 credits | Fast |
gemini_2.5_flash | Google Gemini model | 5 credits | Standard |
Model selection guidance:
gen4_image — best qualitygen4_image_turbo — cheapest and fastestreferenceImages[].uri is fetched server-side by the Runway API — treat it like any outbound fetch:
runway:// URIs from +rw-integrate-uploads — scoped to your account, no arbitrary web content.https://, allowlist trusted hosts, reject private addresses. See the Express.js example below.req.body.referenceImages straight into textToImage.create. The SDK snippets below use raw URLs for brevity — they aren't production templates.POST /v1/text_to_image// Node.js SDK
import RunwayML from '@runwayml/sdk';
const client = new RunwayML();
const task = await client.textToImage.create({
model: 'gen4_image',
promptText: 'A serene Japanese garden with cherry blossoms and a koi pond',
ratio: '1280:720'
}).waitForTaskOutput();
const imageUrl = task.output[0];
# Python SDK
from runwayml import RunwayML
client = RunwayML()
task = client.text_to_image.create(
model='gen4_image',
prompt_text='A serene Japanese garden with cherry blossoms and a koi pond',
ratio='1280:720'
).wait_for_task_output()
image_url = task.output[0]
Reference images let you guide the generation with visual references. Use @Tag syntax in the prompt to reference specific images.
Recommended: upload via +rw-integrate-uploads and pass the returned runway:// URI.
import fs from 'fs';
const refUpload = await client.uploads.createEphemeral(
fs.createReadStream('/path/to/reference.jpg')
);
const task = await client.textToImage.create({
model: 'gen4_image',
promptText: 'A portrait in the style of @Reference',
referenceImages: [
{ uri: refUpload.runwayUri, tag: 'Reference' }
],
ratio: '1280:720'
}).waitForTaskOutput();
External URLs also work — only pass origins you control (see Security):
const task = await client.textToImage.create({
model: 'gen4_image',
promptText: '@EiffelTower painted in the style of @StarryNight',
referenceImages: [
{ uri: 'https://cdn.yourapp.com/eiffel-tower.jpg', tag: 'EiffelTower' },
{ uri: 'https://cdn.yourapp.com/starry-night.jpg', tag: 'StarryNight' }
],
ratio: '1280:720'
}).waitForTaskOutput();
task = client.text_to_image.create(
model='gen4_image',
prompt_text='@EiffelTower painted in the style of @StarryNight',
reference_images=[
{"uri": "https://cdn.yourapp.com/eiffel-tower.jpg", "tag": "EiffelTower"},
{"uri": "https://cdn.yourapp.com/starry-night.jpg", "tag": "StarryNight"}
],
ratio='1280:720'
).wait_for_task_output()
| Parameter | Type | Description |
|---|---|---|
model | string | Model ID (required) |
promptText | string | Text description of the image (required) |
ratio | string | Aspect ratio, e.g. '1280:720', '720:1280', '1080:1080' |
referenceImages | array | Optional. Array of { uri, tag } objects for visual guidance |
+rw-integrate-uploads so inputs are runway:// URIs. External URLs only from origins you control (see Security).import RunwayML from '@runwayml/sdk';
import express from 'express';
const client = new RunwayML();
const app = express();
app.use(express.json());
// `runway://` URIs bypass this check; external URLs must match the allowlist.
const ALLOWED_MEDIA_HOSTS = new Set(['cdn.yourapp.com', 'uploads.yourapp.com']);
function validateReferenceImages(refs) {
if (!Array.isArray(refs)) throw new Error('referenceImages must be an array');
return refs.map(({ uri, tag }) => {
if (typeof uri !== 'string' || typeof tag !== 'string') {
throw new Error('each reference needs a uri and tag');
}
if (uri.startsWith('runway://')) return { uri, tag };
const u = new URL(uri);
if (u.protocol !== 'https:') throw new Error('https required');
if (!ALLOWED_MEDIA_HOSTS.has(u.hostname)) throw new Error('untrusted media host');
return { uri: u.toString(), tag };
});
}
app.post('/api/generate-image', async (req, res) => {
try {
const { prompt, model = 'gen4_image', ratio = '1280:720', referenceImages } = req.body;
const task = await client.textToImage.create({
model,
promptText: prompt,
ratio,
...(referenceImages && { referenceImages: validateReferenceImages(referenceImages) })
}).waitForTaskOutput();
res.json({ imageUrl: task.output[0] });
} catch (error) {
console.error('Image generation failed:', error);
res.status(400).json({ error: error.message });
}
});
For browser uploads: POST files to your server, upload via
+rw-integrate-uploads, and pass therunway://URI. Don't accept raw URLs from the browser.
// app/api/generate-image/route.ts
import RunwayML from '@runwayml/sdk';
import { NextRequest, NextResponse } from 'next/server';
const client = new RunwayML();
export async function POST(request: NextRequest) {
const { prompt, referenceImages } = await request.json();
try {
const task = await client.textToImage.create({
model: 'gen4_image',
promptText: prompt,
ratio: '1280:720',
...(referenceImages && { referenceImages })
}).waitForTaskOutput();
return NextResponse.json({ imageUrl: task.output[0] });
} catch (error) {
return NextResponse.json(
{ error: error instanceof Error ? error.message : 'Generation failed' },
{ status: 500 }
);
}
}
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from runwayml import RunwayML
app = FastAPI()
client = RunwayML()
class ImageRequest(BaseModel):
prompt: str
model: str = "gen4_image"
ratio: str = "1280:720"
reference_images: list[dict] | None = None
@app.post("/api/generate-image")
async def generate_image(req: ImageRequest):
try:
params = {
"model": req.model,
"prompt_text": req.prompt,
"ratio": req.ratio,
}
if req.reference_images:
params["reference_images"] = req.reference_images
task = client.text_to_image.create(**params).wait_for_task_output()
return {"image_url": task.output[0]}
except Exception as e:
raise HTTPException(status_code=500, detail=str(e))
@Tag syntax in the prompt — the tag must match the tag field in the referenceImages array.+rw-integrate-uploads first, then use the runway:// URI.gen4_image_turbo is the cheapest option at 2 credits per image — good for prototyping.