runway-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Runway Dev Platform

Workflow for integrating Runway Dev products into an application. Use MCP for live account state and management, the SDK for application code, and current docs for API contracts.

When to use: Building, modifying, debugging, or verifying a Runway integration, including work started from Dev Portal.

Do not use for: one-off media generation from the agent or direct REST CLI actions.

将Runway Dev产品集成到应用中的工作流。使用MCP处理实时账户状态与管理，使用SDK编写应用代码，并参考当前文档获取API契约。

适用场景： 构建、修改、调试或验证Runway集成，包括从Dev Portal启动的工作。

不适用场景： 通过Agent进行一次性媒体生成或直接的REST CLI操作。

Start with the work

从实际工作入手

Make useful progress before explaining setup. Inspect the workspace and existing configuration without narrating each check. Ask a question only when missing information blocks the next change.

Existing project: find its server boundary and user-facing integration point. Add a server route or function before integrating a frontend-only project.
Empty workspace: ask what the user wants to build. You may recommend a small web app with visible inputs and output as a Runway starting point, but do not claim the user requested one.
Before giving credential setup instructions, test whether
```
RUNWAYML_API_SECRET
```
is present without printing its value, for example with
```
test -n "${RUNWAYML_API_SECRET:-}"
```
. If it is present, skip dotenv instructions.
Use the official SDK. Install
```
@runwayml/sdk
```
for Node or
```
runwayml
```
for Python only if the project needs it and does not already have it.
Keep updates short. Do not narrate a long setup sequence or checklist.

在解释设置之前先推进有效工作。检查工作区和现有配置，但无需逐一说明每个检查步骤。仅当缺失信息阻碍下一步操作时才提出问题。

现有项目：确定其服务器边界和面向用户的集成点。在集成纯前端项目之前，先添加服务器路由或函数。
空工作区：询问用户想要构建什么。你可以推荐一个带有可见输入和输出的小型Web应用作为Runway入门项目，但不要声称这是用户要求的。
在提供凭据设置说明之前，测试
```
RUNWAYML_API_SECRET
```
是否存在，但不要打印其值，例如使用
```
test -n "${RUNWAYML_API_SECRET:-}"
```
。如果已存在，则跳过dotenv相关说明。
使用官方SDK。仅当项目需要且尚未安装时，才为Node安装
```
@runwayml/sdk
```
或为Python安装
```
runwayml
```
。
更新内容要简洁。不要冗长叙述设置流程或检查清单。

Current contracts

当前契约

Installed skill prose is workflow guidance, not the canonical API schema. Resolve current contracts in this order:

Fetch https://docs.dev.runwayml.com/llms.txt.
Fetch only the exact linked documentation subset relevant to the task.
If that subset does not define the contract, read https://docs.dev.runwayml.com/api.md.
If machine-readable detail is still needed, use https://docs.dev.runwayml.com/openapi.json.

Do not invent endpoints, field names, or model constraints.

已安装的技能说明是工作流指南，而非标准API架构。按以下顺序确定当前契约：

获取https://docs.dev.runwayml.com/llms.txt。
仅获取与任务相关的精确链接文档子集。
如果该子集未定义契约，请阅读https://docs.dev.runwayml.com/api.md。
如果仍需机器可读的详细信息，请使用https://docs.dev.runwayml.com/openapi.json。

请勿自行创建端点、字段名称或模型约束。

MCP policy

MCP 策略

Encourage connecting Dev MCP as the happy path for live account context and management. Connect

https://dev.runwayml.com/mcp

with Runway OAuth. Never put an API key in MCP config or automate browser OAuth.

If the user declines or the connection fails, never block account-independent work. Continue with live docs, existing application config, or environment configuration. SDK and API integration code remain allowed. Stop only when the next requested step requires live account discovery, account or resource mutations, or billable verification.

Never imitate an unavailable MCP account-management or resource-management tool with a REST call. Explain the MCP dependency only when it blocks the requested action.

Call MCP tools only when the result affects the next step:

```
whoami
```
when identity or access is uncertain.
```
list_projects
```
when a live
```
projectId
```
must be selected or verified. Never guess one.
```
list_models
```
when model access, selection, or current constraints matter.
```
get_credit_balance
```
immediately before an approved billable verification.

鼓励将Dev MCP作为获取实时账户上下文和进行账户管理的最佳路径。通过Runway OAuth连接

https://dev.runwayml.com/mcp

。切勿将API密钥放入MCP配置中，也不要自动化浏览器OAuth流程。

如果用户拒绝连接或连接失败，切勿阻止与账户无关的工作。继续使用实时文档、现有应用配置或环境配置。仍然允许编写SDK和API集成代码。仅当下一步请求需要实时账户发现、账户或资源变更，或计费验证时才停止。

切勿使用REST调用模拟不可用的MCP账户管理或资源管理工具。仅当MCP依赖阻碍请求的操作时才说明该依赖。

仅当结果会影响下一步操作时才调用MCP工具：

当身份或访问权限不确定时，调用
```
whoami
```
。
当必须选择或验证实时
```
projectId
```
时，调用
```
list_projects
```
。切勿猜测
```
projectId
```
。
当模型访问权限、选择或当前约束很重要时，调用
```
list_models
```
。
在已批准的计费验证前立即调用
```
get_credit_balance
```
。

API key (SDK only)

API密钥（仅适用于SDK）

MCP uses OAuth. SDK calls use an organization-scoped API key from Developer Portal settings. Probe

RUNWAYML_API_SECRET

without printing it. If missing when a live SDK call is imminent, ask the user to store the key in a server-side environment file or secret manager. Never expose it client-side, in chat, or in source control; ensure local environment files are ignored.

MCP使用OAuth。SDK调用使用来自开发者门户设置的组织级API密钥。探测

RUNWAYML_API_SECRET

是否存在，但不要打印其值。如果在即将进行实时SDK调用时发现密钥缺失，请要求用户将密钥存储在服务器端环境文件或密钥管理器中。切勿在客户端、聊天中或源代码控制中暴露该密钥；确保本地环境文件被忽略。

SDK requests

SDK 请求

Build one valid SDK request from the current API docs and, when needed, MCP
```
list_models
```
constraints.

Chain the wait helper directly from the create call:

await client.<operation>.create({...}).waitForTaskOutput()

in Node or

client.<operation>.create(...).wait_for_task_output()

in Python. Do not await

create()

before calling the helper.

Catch the SDK's
```
TaskFailedError
```
and surface its task details. Submit once; do not add a manual polling loop or auto-resubmit.
Use MCP
```
get_task
```
only to inspect or debug an existing task outside the application's SDK flow.
Wire successful output into the application's intended UI or consumer. Persist outputs if the app needs them after signed URLs expire (~24–48h).

根据当前API文档以及（必要时）MCP
```
list_models
```
的约束，构建一个有效的SDK请求。
将等待助手直接链式调用在创建操作之后：Node中使用
```
await client.<operation>.create({...}).waitForTaskOutput()
```
，Python中使用
```
client.<operation>.create(...).wait_for_task_output()
```
。不要在调用助手之前先等待
```
create()
```
完成。
捕获SDK的
```
TaskFailedError
```
并显示任务详情。仅提交一次；不要添加手动轮询循环或自动重新提交。
仅在应用SDK流程之外检查或调试现有任务时，才使用MCP
```
get_task
```
。
将成功的输出连接到应用的目标UI或消费者。如果应用在签名URL过期（约24-48小时）后仍需要输出，请持久化存储这些输出。

Terminology

术语对照表

UI / quickstart	MCP / API
Characters	avatars ( `list_avatars` , `get_avatar` )
Character ID	avatar UUID
Model Router config ID	immutable slug ( `configId` )
live Session	`POST /v1/realtime_sessions`

UI / 快速入门术语	MCP / API术语
Characters	avatars ( `list_avatars` , `get_avatar` )
Character ID	avatar UUID
Model Router配置ID	不可变slug ( `configId` )
实时会话	`POST /v1/realtime_sessions`

Errors

错误处理

Validation error → show message, fix field from MCP constraints or docs, retry once.
Auth/permission → stop; ask user to authenticate or pick accessible project.
Rate limit → honor retry interval.
```
FAILED
```
task → report failure details; do not auto-resubmit.
Missing MCP tool → continue account-independent implementation; stop only when live account state or management is required.

验证错误 → 显示错误信息，根据MCP约束或文档修复字段，重试一次。
授权/权限错误 → 停止操作；请用户进行身份验证或选择可访问的项目。
速率限制 → 遵守重试间隔。
任务
```
FAILED
```
→ 报告失败详情；不要自动重新提交。
MCP工具缺失 → 继续进行与账户无关的实现；仅当需要实时账户状态或管理时才停止。

Surface skills

表层技能

Skill	When
`+runway-dev-models`	Model generation integration
`+runway-dev-model-routers`	Model Router setup and routed calls
`+runway-dev-characters`	Characters / realtime sessions
`+runway-dev-recipes`	Recipe pipelines
`+runway-dev-workflows`	Runway app workflows → API endpoints

Use

+runway-dev

with the relevant surface skill or skills when both are installed. Surface skills repeat their minimum setup so they remain useful when installed alone. Usually one surface matches the user's goal; load more when the task crosses surfaces.

技能	使用场景
`+runway-dev-models`	模型生成集成
`+runway-dev-model-routers`	Model Router设置与路由调用
`+runway-dev-characters`	角色/实时会话
`+runway-dev-recipes`	流程管道
`+runway-dev-workflows`	Runway应用工作流 → API端点

当

+runway-dev

与相关表层技能均已安装时，将两者结合使用。表层技能会重复其最小设置步骤，以便单独安装时仍能发挥作用。通常一个表层技能即可匹配用户目标；当任务涉及多个领域时，加载更多相关技能。