api-reference（API reference 文档）

Runway Public API Reference

PREREQUISITE: Run +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-10 seconds. Aspect ratios: 1280:720, 720:1280, 1104:832, etc.

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: [...]}).

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.