runwayml/rw-api-reference

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.

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "model": "eleven_text_to_sound_v2",
  "promptText": "Thunderclap followed by heavy rain",
  "duration": 5
}

POST /v1/voice_isolation

{
  "model": "eleven_voice_isolation",
  "audioUri": "https://example.com/noisy.mp3"
}

POST /v1/voice_dubbing

{
  "model": "eleven_voice_dubbing",
  "audioUri": "https://example.com/english.mp3",
  "targetLanguage": "es"
}

POST /v1/speech_to_speech

{
  "model": "eleven_multilingual_sts_v2",
  "audioUri": "https://example.com/source.mp3",
  "voice": { "type": "runway-preset", "presetId": "victoria" }
}

POST /v1/avatars

{
  "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

{
  "avatarId": "<avatar-id>",
  "name": "FAQ",
  "content": "Q: What is your return policy?\nA: 30 days, no questions asked."
}

POST /v1/realtime_sessions

{
  "avatarId": "<avatar-id>"
}

---

Management Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/tasks/{id} | Get task status and output | | DELETE | /v1/tasks/{id} | Cancel/delete a task | | POST | /v1/uploads | Create ephemeral upload | | GET | /v1/organization | Organization info & credit balance | | POST | /v1/organization/usage | Credit usage history (up to 90 days) |

---

Task Lifecycle

All generation endpoints return a task object. The flow is:

1. Submit — POST /v1/<endpoint> → returns { "id": "task_xxx" }
2. Poll — GET /v1/tasks/{id} → returns task with status
3. Retrieve output — When status === "SUCCEEDED", the output array contains signed URLs

Task Statuses

| Status | Meaning | |--------|---------| | PENDING | Queued, waiting to start | | RUNNING | Currently generating | | SUCCEEDED | Complete — output URLs available | | FAILED | Generation failed — check failure field | | THROTTLED | Concurrency limit hit — auto-queued |

SDK Polling (Recommended)

The SDKs provide a waitForTaskOutput() method that handles polling automatically:

// Node.js — polls until complete (default 10 min timeout)
const task = await client.imageToVideo.create({
  model: 'gen4.5',
  promptImage: 'https://example.com/image.jpg',
  promptText: 'A sunset timelapse',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

console.log(task.output); // Array of signed URLs

# Python
task = client.image_to_video.create(
    model='gen4.5',
    prompt_image='https://example.com/image.jpg',
    prompt_text='A sunset timelapse',
    ratio='1280:720',
    duration=5
).wait_for_task_output()

print(task.output)

Manual Polling (REST)

async function pollTask(taskId) {
  while (true) {
    const response = await fetch(`https://api.dev.runwayml.com/v1/tasks/${taskId}`, {
      headers: {
        'Authorization': `Bearer ${process.env.RUNWAYML_API_SECRET}`,
        'X-Runway-Version': '2024-11-06'
      }
    });
    const task = await response.json();

    if (task.status === 'SUCCEEDED') return task;
    if (task.status === 'FAILED') throw new Error(task.failure);

    await new Promise(r => setTimeout(r, 5000)); // poll every 5 seconds
  }
}

---

Output Handling

• Successful tasks return an output array with signed URLs to generated content
• Output URLs expire within 24-48 hours
• Download and store outputs in your own storage — do not serve signed URLs to end users
• Video outputs are MP4, image outputs are PNG/JPEG

---

Input Requirements

Size Limits

| Type | Via URL | Via Data URI | Via Upload | |------|---------|-------------|------------| | Image | 16 MB | 5 MB | 200 MB | | Video | 32 MB | 16 MB | 200 MB | | Audio | 32 MB | 16 MB | 200 MB |

Supported Formats

• Images: JPEG, PNG, WebP (no GIF)
• Video codecs: H.264, H.265/HEVC, AV1, VP8/VP9, Apple ProRes, Theora
• Audio: MP3, AAC, FLAC, PCM, ALAC

URL Requirements

If providing assets via URL:

• HTTPS only (no HTTP)
• Domain names only (no IP addresses)
• No redirects
• Must support HTTP HEAD requests
• Must return valid Content-Type and Content-Length headers
• Max URL length: 2,048 characters

---

Rate Limits & Tiers

| Tier | Concurrency | Daily Gens | Monthly Cap | Unlock | |------|-------------|------------|-------------|--------| | 1 (default) | 1-2 | 50-200 | $100 | — | | 2 | 3 | 500-1,000 | $500 | 1 day + $50 | | 3 | 5 | 1,000-2,000 | $2,000 | 7 days + $100 | | 4 | 10 | 5,000-10,000 | $20,000 | 14 days + $1,000 | | 5 | 20 | 25,000-30,000 | $100,000 | 7 days + $5,000 |

• No requests-per-minute limit — only daily generation quotas
• Exceeding concurrency → THROTTLED status (auto-queued, not rejected)
• Exceeding daily limit → 429 Too Many Requests
• Daily limits use a rolling 24-hour window

---

Error Handling

HTTP Errors

| Code | Meaning | Action | |------|---------|--------| | 400 | Input validation failure | Fix input, do not retry | | 401 | Invalid API key | Check key, do not retry | | 429 | Rate limited | Retry with exponential backoff + jitter | | 502/503/504 | Server overload | Retry with exponential backoff + jitter |

Task Failure Codes

| Code | Meaning | Retry? | |------|---------|--------| | SAFETY.INPUT.* | Input content moderation | No — not refundable | | SAFETY.OUTPUT.* | Output content moderation | Yes — try different prompt | | INTERNAL.BAD_OUTPUT | Quality issue | Yes | | ASSET.INVALID | Bad input format | Fix input | | INTERNAL | Server error | Yes |

The SDKs handle retries for transient errors automatically.

---

Data URI Support

Base64-encoded images can be passed instead of URLs:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

Useful for small images or when you don't want to host the file. Subject to the data URI size limits above.