Back to Details

api-reference

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Runway Public API Reference

Runway 公共API参考

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
前提条件： 请先运行 
+check-compatibility
以确保项目具备服务端运行能力。
基础URL：
https://api.dev.runwayml.com
所有请求都需要携带以下请求头：
Authorization: Bearer <RUNWAYML_API_SECRET>
X-Runway-Version: 2024-11-06

Models & Endpoints

模型与端点

Video Generation

视频生成

ModelEndpointInputCost (credits/sec)
gen4.5
POST /v1/image_to_video
or 
POST /v1/text_to_video
Text and/or Image12
gen4_turbo
POST /v1/image_to_video
Image required5
gen4_aleph
POST /v1/video_to_video
Video + Text/Image15
act_two
POST /v1/character_performance
Image/Video5
veo3
POST /v1/image_to_video
or 
POST /v1/text_to_video
Text/Image40
veo3.1
POST /v1/image_to_video
or 
POST /v1/text_to_video
Text/Image20-40
veo3.1_fast
POST /v1/image_to_video
or 
POST /v1/text_to_video
Text/Image10-15
Video duration: 2-10 seconds. Aspect ratios: 
1280:720
, 
720:1280
, 
1104:832
, etc.
模型端点输入成本（积分/秒）
gen4.5
POST /v1/image_to_video
或 
POST /v1/text_to_video
文本和/或图像12
gen4_turbo
POST /v1/image_to_video
必须传入图像5
gen4_aleph
POST /v1/video_to_video
视频 + 文本/图像15
act_two
POST /v1/character_performance
图像/视频5
veo3
POST /v1/image_to_video
或 
POST /v1/text_to_video
文本/图像40
veo3.1
POST /v1/image_to_video
或 
POST /v1/text_to_video
文本/图像20-40
veo3.1_fast
POST /v1/image_to_video
或 
POST /v1/text_to_video
文本/图像10-15
视频时长：2-10秒。支持的宽高比：
1280:720
、
720:1280
、
1104:832
等。

Image Generation

图像生成

ModelEndpointCost (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
模型端点成本（积分）
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

音频生成

ModelEndpointUse CaseCost
eleven_multilingual_v2
POST /v1/text_to_speech
Text to speech1 credit/50 chars
eleven_text_to_sound_v2
POST /v1/sound_effect
Sound effects1-2 credits
eleven_voice_isolation
POST /v1/voice_isolation
Isolate voice from audio1 credit/6 sec
eleven_voice_dubbing
POST /v1/voice_dubbing
Dub audio to other languages1 credit/2 sec
eleven_multilingual_sts_v2
POST /v1/speech_to_speech
Voice conversion1 credit/3 sec
模型端点使用场景成本
eleven_multilingual_v2
POST /v1/text_to_speech
文本转语音1积分/50字符
eleven_text_to_sound_v2
POST /v1/sound_effect
音效生成1-2积分
eleven_voice_isolation
POST /v1/voice_isolation
音频人声分离1积分/6秒
eleven_voice_dubbing
POST /v1/voice_dubbing
多语言音频配音1积分/2秒
eleven_multilingual_sts_v2
POST /v1/speech_to_speech
声音转换1积分/3秒

Characters (Real-Time Avatars)

角色（实时数字人）

ModelDescriptionSession Max Duration
gwm1_avatars
Real-time conversational avatars powered by GWM-15 minutes
Endpoints:
MethodEndpointDescription
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:
ParameterTypeDescription
name
stringDisplay name for the avatar
referenceImage
stringURL or 
runway://
URI of the character image
voice
object
{ type: 'runway-live-preset', presetId: 'clara' }
personality
stringSystem 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
)
模型描述会话最大时长
gwm1_avatars
由GWM-1驱动的实时对话数字人5分钟
端点列表：
请求方法端点描述
POST
/v1/avatars
创建新的数字人
GET
/v1/avatars/{id}
获取指定数字人信息
PATCH
/v1/avatars/{id}
更新数字人信息（名称、声音、人设、关联文档ID）
DELETE
/v1/avatars/{id}
删除指定数字人
POST
/v1/realtime_sessions
创建新的实时会话
GET
/v1/realtime_sessions/{id}
查询会话状态（轮询直到状态变为
READY
）
POST
/v1/realtime_sessions/{id}/consume
获取WebRTC会话凭证（单次有效）
数字人创建参数：
参数类型描述
name
string数字人展示名称
referenceImage
string角色形象图片的URL或
runway://
URI
voice
object格式为 
{ type: 'runway-live-preset', presetId: 'clara' }
personality
string系统提示词/人设指令
documentIds
string[]可选，要关联的知识库文档ID列表
声音预设： 
clara
（柔和）、
victoria
（沉稳）、
vincent
（权威）。可前往 dev.runwayml.com 预览所有预设。
会话状态流转： 
NOT_READY
→ 
READY
→ 
RUNNING
→ 
COMPLETED
（或 
FAILED
/ 
CANCELLED
）

Documents (Knowledge Base)

文档（知识库）

MethodEndpointDescription
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: [...] })
.
请求方法端点描述
POST
/v1/documents
创建文档（支持纯文本或Markdown）
GET
/v1/documents/{id}
获取指定文档内容
DELETE
/v1/documents/{id}
删除指定文档
每个数字人最多支持 5万token 的知识库容量。可通过 
client.avatars.update(id, { documentIds: [...] })
为数字人关联知识库文档。

Management Endpoints

管理端点

MethodEndpointDescription
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)
请求方法端点描述
GET
/v1/tasks/{id}
获取任务状态和输出结果
DELETE
/v1/tasks/{id}
取消/删除任务
POST
/v1/uploads
创建临时上传凭证
GET
/v1/organization
获取组织信息和积分余额
POST
/v1/organization/usage
查询积分使用历史（最多支持90天）

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
所有生成类接口都会返回一个任务对象，调用流程如下：
  1. 提交任务 — 调用 
    POST /v1/<endpoint>
    → 返回 
    { "id": "task_xxx" }
  2. 轮询状态 — 调用 
    GET /v1/tasks/{id}
    → 返回带
    status
    字段的任务信息
  3. 获取输出 — 当 
    status === "SUCCEEDED"
    时，
    output
    数组包含生成资源的签名URL

Task Statuses

任务状态

StatusMeaning
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
状态含义
PENDING
队列中，等待执行
RUNNING
生成中
SUCCEEDED
生成完成，可获取输出URL
FAILED
生成失败，请查看
failure
字段获取详情
THROTTLED
并发达到上限，已自动进入队列等待

SDK Polling (Recommended)

SDK轮询（推荐）

The SDKs provide a 
waitForTaskOutput()
method that handles polling automatically:
javascript
// 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
undefined
官方SDK提供了 
waitForTaskOutput()
方法，可自动处理轮询逻辑：
javascript
// Node.js — 自动轮询直到任务完成（默认超时时间10分钟）
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); // 签名URL数组
python
undefined

Python

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)
undefined
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)
undefined

Manual Polling (REST)

手动轮询（REST）

javascript
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
  }
}
javascript
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)); // 每5秒轮询一次
  }
}

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
  • 成功执行的任务会返回
    output
    数组，其中包含生成内容的签名URL
  • 输出URL的有效期为24-48小时
  • 请将输出内容下载并存储到你自己的存储服务中，不要直接将签名URL提供给终端用户
  • 视频输出为MP4格式，图像输出为PNG/JPEG格式

Input Requirements

输入要求

Size Limits

大小限制

TypeVia URLVia Data URIVia Upload
Image16 MB5 MB200 MB
Video32 MB16 MB200 MB
Audio32 MB16 MB200 MB
类型URL传入Data URI传入上传传入
图像16 MB5 MB200 MB
视频32 MB16 MB200 MB
音频32 MB16 MB200 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
  • 图像： JPEG、PNG、WebP（不支持GIF）
  • 视频编码： H.264、H.265/HEVC、AV1、VP8/VP9、Apple ProRes、Theora
  • 音频： MP3、AAC、FLAC、PCM、ALAC

URL Requirements

URL要求

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
如果通过URL传入资源：
  • 仅支持HTTPS（不支持HTTP）
  • 仅支持域名（不支持IP地址）
  • 不能有重定向
  • 必须支持HTTP HEAD请求
  • 必须返回有效的
    Content-Type
    和
    Content-Length
    响应头
  • URL最大长度：2048字符

Rate Limits & Tiers

速率限制与等级

TierConcurrencyDaily GensMonthly CapUnlock
1 (default)1-250-200$100—
23500-1,000$5001 day + $50
351,000-2,000$2,0007 days + $100
4105,000-10,000$20,00014 days + $1,000
52025,000-30,000$100,0007 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
等级并发数日生成量上限月消费上限解锁条件
1（默认）1-250-200$100—
23500-1000$500使用满1天 + 消费满$50
351000-2000$2000使用满7天 + 消费满$100
4105000-10000$20000使用满14天 + 消费满$1000
52025000-30000$100000使用满7天 + 消费满$5000
  • 没有每分钟请求次数限制，仅限制日生成配额
  • 超过并发限制 → 返回
    THROTTLED
    状态（自动进入队列，不会直接拒绝请求）
  • 超过日配额限制 → 返回
    429 Too Many Requests
  • 日限制采用滚动24小时窗口计算

Error Handling

错误处理

HTTP Errors

HTTP错误

CodeMeaningAction
400Input validation failureFix input, do not retry
401Invalid API keyCheck key, do not retry
429Rate limitedRetry with exponential backoff + jitter
502/503/504Server overloadRetry with exponential backoff + jitter
状态码含义处理建议
400输入参数校验失败修正输入参数，不要重试
401API密钥无效检查密钥是否正确，不要重试
429触发速率限制采用指数退避+随机抖动策略重试
502/503/504服务端过载采用指数退避+随机抖动策略重试

Task Failure Codes

任务失败错误码

CodeMeaningRetry?
SAFETY.INPUT.*
Input content moderationNo — not refundable
SAFETY.OUTPUT.*
Output content moderationYes — try different prompt
INTERNAL.BAD_OUTPUT
Quality issueYes
ASSET.INVALID
Bad input formatFix input
INTERNAL
Server errorYes
The SDKs handle retries for transient errors automatically.
错误码含义可重试？
SAFETY.INPUT.*
输入内容未通过内容审核不可重试，不予退款
SAFETY.OUTPUT.*
输出内容未通过内容审核可重试，尝试更换提示词
INTERNAL.BAD_OUTPUT
生成内容质量不合格可重试
ASSET.INVALID
输入资源格式错误修正输入资源后重试
INTERNAL
服务端错误可重试
SDK会自动处理瞬时错误的重试逻辑。

Data URI Support

Data URI支持

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.
可以传入Base64编码的图像替代URL：
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
该方式适合小图像，或不想托管文件的场景，需遵守上文提到的Data URI大小限制。