runwayml · robinandeer · Apr 16, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "runway-api",
   "description": "Video generation at scale. Generate videos, images, and audio with Runway's API — batch ad campaigns, product videos, multishot stories, and creative iteration. Supports seedance2, gen4.5, veo3, Nano, Banana Pro, and more.",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "author": {
     "name": "Runway",
     "email": "ops@runwayml.com"

diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "runway-api",
   "displayName": "Runway API",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Video generation at scale. Generate videos, images, and audio with Runway's API — batch ad campaigns, product videos, multishot stories, and creative iteration. Supports seedance2, gen4.5, veo3, Nano, Banana Pro, and more.",
   "author": {
     "name": "Runway",

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.1.0
+
+- **`use-runway-api`:** Runtime script moved from `scripts/runway-api.mjs` (repo root) to `skills/use-runway-api/scripts/runway-api.mjs` so it ships with the skill when installed via `npx skills add`, Claude plugins, or Cursor plugins. SKILL.md now documents a concrete `<skill-dir>` resolution strategy with fallback locations.
+- **`use-runway-api`:** Added opinionated **Presenting Generation Output** section — lead with model + cost, embed images as Markdown, proactively offer to download locally, avoid pasting raw signed URLs.
+- **`use-runway-api`:** Added `RUNWAY_SKILLS_DIR` env var as a fallback hint for the skill path.
+- **`rw-api-reference`:** Added **Request Body Reference (raw JSON)** section with minimal POST bodies for every generation endpoint (text_to_image, text_to_video, image_to_video, video_to_video, text_to_speech, sound_effect, voice_isolation, voice_dubbing, speech_to_speech), plus `avatars`, `documents`, and `realtime_sessions`.
+- **`AUTH.md`:** Fixed env var names (`RUNWAY_SKILLS_API_SECRET`, `RUNWAY_SKILLS_API_SECRET_STAGE`, `RUNWAY_SKILLS_BASE_URL`) to match the runtime script.
+
 ## 2.0.0
 
 - **Media generation:** New `rw-generate-video`, `rw-generate-image`, `rw-generate-audio` skills that run Python scripts directly via `uv run` — no SDK setup required

diff --git a/skills/rw-api-reference/SKILL.md b/skills/rw-api-reference/SKILL.md
@@ -102,6 +102,154 @@ Video duration: **2-15 seconds** (model-dependent). Aspect ratios are pixel-base
 
 Each Avatar supports up to **50,000 tokens** of knowledge. Link documents to an Avatar via `client.avatars.update(id, { documentIds: [...] })`.
 
+---
+
+## Request Body Reference (raw JSON)
+
+Use these when calling the API directly (e.g. through `use-runway-api`'s `request` command) rather than via an SDK. Only required + common fields shown — consult `+rw-fetch-api-reference` for the full schema.
+
+### `POST /v1/text_to_image`
+
+```json
+{
+  "model": "gen4_image",
+  "promptText": "A serene Japanese garden with cherry blossoms",
+  "ratio": "1920:1080"
+}
+```
+
+- `model`: `gen4_image` | `gen4_image_turbo` | `gemini_2.5_flash` (required)
+- `promptText`: string, up to ~1000 chars (required)
+- `ratio`: one of `1920:1080`, `1080:1920`, `1024:1024`, `1360:768`, `1080:1080`, `1168:880`, `1440:1080`, `1080:1440`, `1808:768`, `2112:912` (required; 720p or 1080p variants depending on model)
+- `referenceImages`: optional `[{ "uri": "https://...", "tag": "MyTag" }]` — reference by `@MyTag` in `promptText`
+- `seed`: optional integer for reproducibility
+
+### `POST /v1/text_to_video`
+
+```json
+{
+  "model": "gen4.5",
+  "promptText": "A golden retriever running through wildflowers at sunset",
+  "ratio": "1280:720",
+  "duration": 5
+}
+```
+
+- `model`: `gen4.5` | `veo3` | `veo3.1` | `veo3.1_fast` | `seedance2` (required)
+- `duration`: integer seconds, 2–10 (required; model-specific valid values — e.g. veo3 only accepts 8)
+- `ratio`: e.g. `1280:720`, `720:1280`, `1104:832`, `832:1104`, `960:960` (required)
+
+### `POST /v1/image_to_video`
+
+```json
+{
+  "model": "gen4.5",
+  "promptImage": "https://example.com/cover.jpg",
+  "promptText": "A slow dolly-in shot",
+  "ratio": "1280:720",
+  "duration": 5
+}
+```
+
+- `model`: `gen4.5` | `gen4_turbo` | `veo3` | `veo3.1` | `veo3.1_fast` | `seedance2` (required)
+- `promptImage`: HTTPS URL, data URI, or `runway://` URI (required). Can also be `[{ "uri": "...", "position": "first" | "last" }]` for keyframes.
+- `promptText`: optional for most models, required for `gen4_turbo` when no image motion is obvious
+
+### `POST /v1/video_to_video`
+
+```json
+{
+  "model": "gen4_aleph",
+  "videoUri": "https://example.com/source.mp4",
+  "promptText": "Change the season to winter with snowfall",
+  "ratio": "1280:720"
+}
+```
+
+### `POST /v1/text_to_speech`
+
+```json
+{
+  "model": "eleven_multilingual_v2",
+  "text": "Hello, welcome to Runway.",
+  "voice": { "type": "runway-preset", "presetId": "clara" }
+}
+```
+
+- `voice`: `{ type: "runway-preset", presetId: "clara" | "victoria" | "vincent" | ... }` or a provider-specific voice object
+- `languageCode`: optional ISO code (auto-detected by default)
+
+### `POST /v1/sound_effect`
+
+```json
+{
+  "model": "eleven_text_to_sound_v2",
+  "promptText": "Thunderclap followed by heavy rain",
+  "duration": 5
+}
+```
+
+### `POST /v1/voice_isolation`
+
+```json
+{
+  "model": "eleven_voice_isolation",
+  "audioUri": "https://example.com/noisy.mp3"
+}
+```
+
+### `POST /v1/voice_dubbing`
+
+```json
+{
+  "model": "eleven_voice_dubbing",
+  "audioUri": "https://example.com/english.mp3",
+  "targetLanguage": "es"
+}
+```
+
+### `POST /v1/speech_to_speech`
+
+```json
+{
+  "model": "eleven_multilingual_sts_v2",
+  "audioUri": "https://example.com/source.mp3",
+  "voice": { "type": "runway-preset", "presetId": "victoria" }
+}
+```
+
+### `POST /v1/avatars`
+
+```json
+{
+  "name": "Support Agent",
+  "referenceImage": "https://example.com/portrait.jpg",
+  "voice": { "type": "runway-live-preset", "presetId": "clara" },
+  "personality": "You are a friendly support agent.",
+  "documentIds": []
+}
+```
+
+### `POST /v1/documents`
+
+```json
+{
+  "avatarId": "<avatar-id>",
+  "name": "FAQ",
+  "content": "Q: What is your return policy?\nA: 30 days, no questions asked."
+}
+```
+
+### `POST /v1/realtime_sessions`
+
+```json
+{
+  "avatarId": "<avatar-id>"
+}
+```
+
+---
+
 ### Management Endpoints
 
 | Method | Endpoint | Description |

diff --git a/skills/use-runway-api/AUTH.md b/skills/use-runway-api/AUTH.md
@@ -11,14 +11,14 @@ Use environment variables for direct Runway API actions. The API key must never
 Current shell before launching the editor:
 
 ```bash
-export RUNWAYML_API_SECRET=YOUR_KEY_HERE
+export RUNWAY_SKILLS_API_SECRET=YOUR_KEY_HERE
 cursor .
 ```
 
 Or add it to your shell profile, then restart the editor:
 
 ```bash
-echo 'export RUNWAYML_API_SECRET=YOUR_KEY_HERE' >> ~/.zshrc
+echo 'export RUNWAY_SKILLS_API_SECRET=YOUR_KEY_HERE' >> ~/.zshrc
 source ~/.zshrc
 ```
 
@@ -27,21 +27,26 @@ Replace `YOUR_KEY_HERE` locally in the terminal. Never paste the key into the ch
 ## Verify
 
 ```bash
-node <path-to-skills-repo>/scripts/runway-api.mjs auth status
+node <skill-dir>/scripts/runway-api.mjs auth status
 ```
 
-If `authenticated` is still `false`, restart the editor or launch it from a shell that already has `RUNWAYML_API_SECRET` set.
+`<skill-dir>` is the absolute directory of the `SKILL.md` you are reading — see the **Runtime Location** section in `SKILL.md` for how to resolve it.
+
+If `authenticated` is still `false`, restart the editor or launch it from a shell that already has `RUNWAY_SKILLS_API_SECRET` set.
 
 ## Non-production environments
 
-Set `RUNWAYML_BASE_URL` alongside the API key:
+Set a stage-specific key (preferred) and/or override the base URL:
 
 ```bash
-export RUNWAYML_BASE_URL=https://api.dev-stage.runwayml.com
+export RUNWAY_SKILLS_API_SECRET_STAGE=YOUR_STAGE_KEY
+export RUNWAY_SKILLS_BASE_URL=https://api.dev-stage.runwayml.com
 ```
 
+With `--stage` on any command, the CLI prefers `RUNWAY_SKILLS_API_SECRET_STAGE` and falls back to `RUNWAY_SKILLS_API_SECRET`.
+
 ## Notes
 
 - API keys require prepaid credits to work.
-- `RUNWAYML_BASE_URL` defaults to `https://api.dev.runwayml.com`.
+- `RUNWAY_SKILLS_BASE_URL` defaults to `https://api.dev.runwayml.com` (production) or `https://api.dev-stage.runwayml.com` when `--stage` is passed.
 - `auth status` verifies that the current environment can reach the API successfully.