rw-api-reference

Runway 公共 API 参考

前置条件： 先运行 +rw-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
seedance2	POST /v1/text_to_video、POST /v1/image_to_video 或 POST /v1/video_to_video	文本、图像和/或视频	36

视频时长：2-15 秒（取决于模型）。宽高比以像素为单位：1280:720、720:1280、1104:832、960:960、832:1104、1584:672 等。

Seedance 2 特性：

• 模式：文生视频、图生视频（首帧/末帧或图像参考）、视频转视频
• 时长：TTV 和 ITV 必填（以秒为单位）
• 宽高比（以像素为单位）：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 支持两种互斥模式：首帧/末帧（包含 position 的 promptImage 数组）或图像参考（references 数组）
• VTV 输入要求：最长 15 秒，最大 32 MB，最低分辨率为 720p，建议使用 MP4

图像生成

模型	端点	费用（积分）
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 秒

Characters（实时虚拟形象）

模型	描述	会话最长时长
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）

Documents（知识库）

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

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

---

请求正文参考（原始 JSON）

直接调用 API 时（例如通过 use-runway-api 的 request 命令），而非通过 SDK 调用时，请使用以下内容。这里只展示必填字段和常用字段；完整架构请查阅 +rw-fetch-api-reference。

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（必填）
• promptText：字符串，最多约 1000 个字符（必填）
• ratio：以下值之一：1920:1080、1080:1920、1024:1024、1360:768、1080:1080、1168:880、1440:1080、1080:1440、1808:768、2112:912（必填；根据模型提供 720p 或 1080p 版本）
• referenceImages：可选，[{ "uri": "https://...", "tag": "MyTag" }] — 在 promptText 中通过 @MyTag 引用
• seed：可选整数，用于确保结果可复现

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（必填）
• duration：整数秒数，2–10（必填；有效值因模型而异，例如 veo3 仅接受 8）
• ratio：例如 1280:720、720:1280、1104:832、832:1104、960:960（必填）

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（必填）
• promptImage：HTTPS URL、data URI 或 runway:// URI（必填）。也可以使用 [{ "uri": "...", "position": "first" | "last" }] 来设置关键帧。
• promptText：大多数模型可选；如果没有明显的图像运动，则 gen4_turbo 必填

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" | ... } 或特定提供商的语音对象
• languageCode：可选 ISO 代码（默认自动检测）

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

---

管理端点

方法	端点	描述
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 大小限制约束。