rw-api-reference

What this skill does

# Runway Public API Reference

> **PREREQUISITE:** Run `+rw-check-compatibility` first to ensure the project has server-side capability.

Base URL: `https://api.dev.runwayml.com`

All requests require these headers:
```
Authorization: Bearer <RUNWAYML_API_SECRET>
X-Runway-Version: 2024-11-06
```

---

## Models & Endpoints

### Video Generation

| Model | Endpoint | Input | Cost (credits/sec) |
|-------|----------|-------|---------------------|
| `gen4.5` | `POST /v1/image_to_video` or `POST /v1/text_to_video` | Text and/or Image | 12 |
| `gen4_turbo` | `POST /v1/image_to_video` | Image required | 5 |
| `gen4_aleph` | `POST /v1/video_to_video` | Video + Text/Image | 15 |
| `act_two` | `POST /v1/character_performance` | Image/Video | 5 |
| `veo3` | `POST /v1/image_to_video` or `POST /v1/text_to_video` | Text/Image | 40 |
| `veo3.1` | `POST /v1/image_to_video` or `POST /v1/text_to_video` | Text/Image | 20-40 |
| `veo3.1_fast` | `POST /v1/image_to_video` or `POST /v1/text_to_video` | Text/Image | 10-15 |
| `seedance2` | `POST /v1/text_to_video`, `POST /v1/image_to_video`, or `POST /v1/video_to_video` | Text, Image, and/or Video | 36 |

Video duration: **2-15 seconds** (model-dependent). Aspect ratios are pixel-based: `1280:720`, `720:1280`, `1104:832`, `960:960`, `832:1104`, `1584:672`, etc.

**Seedance 2 specifics:**
- Modes: text-to-video, image-to-video (first/last frame or image reference), video-to-video
- Duration: required for TTV and ITV (in seconds)
- Aspect ratios (pixel-based): `1280:720`, `720:1280`, `960:960`, `1112:834`, `834:1112`, `1470:630`, `992:432`, `864:496`, `752:560`, `640:640`, `560:752`, `496:864`
- ITV supports two mutually exclusive modes: first/last frame (`promptImage` array with `position`) or image reference (`references` array)
- VTV input requirements: max 15 seconds, max 32 MB, min 720p resolution, MP4 recommended

### Image Generation

| Model | Endpoint | Cost (credits) |
|-------|----------|----------------|
| `gen4_image` | `POST /v1/text_to_image` | 5 (720p), 8 (1080p) |
| `gen4_image_turbo` | `POST /v1/text_to_image` | 2 |
| `gemini_2.5_flash` | `POST /v1/text_to_image` | 5 |

### Audio Generation

| Model | Endpoint | Use Case | Cost |
|-------|----------|----------|------|
| `eleven_multilingual_v2` | `POST /v1/text_to_speech` | Text to speech | 1 credit/50 chars |
| `eleven_text_to_sound_v2` | `POST /v1/sound_effect` | Sound effects | 1-2 credits |
| `eleven_voice_isolation` | `POST /v1/voice_isolation` | Isolate voice from audio | 1 credit/6 sec |
| `eleven_voice_dubbing` | `POST /v1/voice_dubbing` | Dub audio to other languages | 1 credit/2 sec |
| `eleven_multilingual_sts_v2` | `POST /v1/speech_to_speech` | Voice conversion | 1 credit/3 sec |

### Characters (Real-Time Avatars)

| Model | Description | Session Max Duration |
|-------|-------------|----------------------|
| `gwm1_avatars` | Real-time conversational avatars powered by GWM-1 | 5 minutes |

**Endpoints:**

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/v1/avatars` | Create a new Avatar |
| `GET` | `/v1/avatars/{id}` | Retrieve an Avatar |
| `PATCH` | `/v1/avatars/{id}` | Update an Avatar (name, voice, personality, documentIds) |
| `DELETE` | `/v1/avatars/{id}` | Delete an Avatar |
| `POST` | `/v1/realtime_sessions` | Create a new real-time session |
| `GET` | `/v1/realtime_sessions/{id}` | Retrieve session status (poll until `READY`) |
| `POST` | `/v1/realtime_sessions/{id}/consume` | Consume session credentials for WebRTC (one-time use) |

**Avatar creation parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Display name for the avatar |
| `referenceImage` | string | URL or `runway://` URI of the character image |
| `voice` | object | `{ type: 'runway-live-preset', presetId: 'clara' }` |
| `personality` | string | System prompt / personality instructions |
| `documentIds` | string[] | Optional. IDs of knowledge base documents to attach |

**Voice presets:** `clara` (soft), `victoria` (firm), `vincent` (authoritative). Preview all at [dev.runwayml.com](https://dev.runwayml.com/).

**Session statuses:** `NOT_READY` → `READY` → `RUNNING` → `COMPLETED` (or `FAILED` / `CANCELLED`)

### Documents (Knowledge Base)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/v1/documents` | Create a document (plain text or Markdown) |
| `GET` | `/v1/documents/{id}` | Retrieve a document |
| `DELETE` | `/v1/documents/{id}` | Delete a document |

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" },
  "personal