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

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

Audio Generation

Characters (Real-Time Avatars)

Endpoints:

Avatar creation parameters:

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)

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 rather than via an SDK. Only required + common fields shown.

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

---

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

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

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

• 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

Task Failure Codes

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.