api-reference

Runway 公共 API 参考

前置条件： 请先运行 +check-compatibility，确保项目具备服务器端能力。

基础 URL：https://api.dev.runwayml.com

所有请求都需要以下标头：

Authorization: Bearer <RUNWAYML_API_SECRET>
X-Runway-Version: 2024-11-06

---

模型与端点

视频生成

模型	端点	输入	成本（积分/秒）
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 等。

图像生成

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

音频生成

模型	端点	用途	成本
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 秒

角色（实时虚拟形象）

模型	描述	会话最长时长
gwm1_avatars	由 GWM-1 驱动的实时对话虚拟形象	5 分钟

端点：

方法	端点	描述
POST	/v1/avatars	创建新的虚拟形象
GET	/v1/avatars/{id}	获取虚拟形象
PATCH	/v1/avatars/{id}	更新虚拟形象（名称、语音、个性、documentIds）
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）

文档（知识库）

方法	端点	描述
POST	/v1/documents	创建文档（纯文本或 Markdown）
GET	/v1/documents/{id}	获取文档
DELETE	/v1/documents/{id}	删除文档

每个虚拟形象最多支持 50,000 个 token 的知识。通过 client.avatars.update(id, { documentIds: [...] }) 将文档关联到虚拟形象。

管理端点

方法	端点	描述
GET	/v1/tasks/{id}	获取任务状态和输出
DELETE	/v1/tasks/{id}	取消/删除任务
POST	/v1/uploads	创建临时上传
GET	/v1/organization	组织信息和额度余额
POST	/v1/organization/usage	额度使用历史（最多 90 天）

---

任务生命周期

所有生成端点都会返回一个任务对象。流程如下：

1. 提交 — POST /v1/<endpoint> → 返回 { "id": "task_xxx" }
2. 轮询 — GET /v1/tasks/{id} → 返回包含 status 的任务
3. 获取输出 — 当 status === "SUCCEEDED" 时，output 数组中包含签名 URL

任务状态

状态	含义
PENDING	排队中，等待开始
RUNNING	正在生成
SUCCEEDED	已完成 — 输出 URL 可用
FAILED	生成失败 — 检查 failure 字段
THROTTLED	达到并发上限 — 自动排队

SDK 轮询（推荐）

SDK 提供了 waitForTaskOutput() 方法，可自动处理轮询：

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

手动轮询（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 数组，其中包含指向生成内容的签名 URL
• 输出 URL 会在 24-48 小时内过期
• 请下载输出并存储在自己的存储空间中 — 不要向最终用户提供签名 URL
• 视频输出为 MP4，图像输出为 PNG/JPEG

---

输入要求

大小限制

类型	通过 URL	通过 Data URI	通过上传
图像	16 MB	5 MB	200 MB
视频	32 MB	16 MB	200 MB
音频	32 MB	16 MB	200 MB

支持的格式

• 图像： JPEG、PNG、WebP（不支持 GIF）
• 视频编解码器： H.264、H.265/HEVC、AV1、VP8/VP9、Apple ProRes、Theora
• 音频： MP3、AAC、FLAC、PCM、ALAC

URL 要求

如果通过 URL 提供素材：

• 仅支持 HTTPS（不支持 HTTP）
• 仅支持域名（不支持 IP 地址）
• 不得重定向
• 必须支持 HTTP HEAD 请求
• 必须返回有效的 Content-Type 和 Content-Length 标头
• URL 长度上限：2,048 个字符

---

速率限制与层级

层级	并发数	每日生成量	每月上限	解锁条件
1（默认）	1-2	50-200	$100	—
2	3	500-1,000	$500	1 天 + $50
3	5	1,000-2,000	$2,000	7 天 + $100
4	10	5,000-10,000	$20,000	14 天 + $1,000
5	20	25,000-30,000	$100,000	7 天 + $5,000

• 没有每分钟请求数限制 — 仅有每日生成配额
• 超出并发限制 → THROTTLED 状态（自动排队，不会拒绝）
• 超出每日限制 → 429 Too Many Requests
• 每日限制按滚动 24 小时窗口计算

---

错误处理

HTTP 错误

代码	含义	操作
400	输入验证失败	修正输入，不要重试
401	API 密钥无效	检查密钥，不要重试
429	触发速率限制	使用指数退避 + 随机抖动重试
502/503/504	服务器过载	使用指数退避 + 随机抖动重试

任务失败代码

代码	含义	是否重试？
SAFETY.INPUT.*	输入内容审核	否 — 不予退款
SAFETY.OUTPUT.*	输出内容审核	是 — 尝试使用不同的提示词
INTERNAL.BAD_OUTPUT	质量问题	是
ASSET.INVALID	输入格式错误	修正输入
INTERNAL	服务器错误	是

SDK 会自动处理暂时性错误的重试。

---

Data URI 支持

可以传入 Base64 编码的图像，而不是 URL：

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

适用于小型图像，或不想托管文件的情况。受上述 Data URI 大小限制约束。