use-runway-api

使用 Runway API

直接从 Agent 调用 Runway 公共 API，以管理资源、触发生成并查看账户状态。

何时使用此技能： 当用户希望 Agent 直接操作其 Runway 账户时使用此技能 — 创建或更新虚拟形象、管理文档、触发生成、查看额度余额等。若要将集成代码编写到应用程序中，请改用 +runway-dev 和匹配的界面技能。

当用户要求在 Runway 的使用场景中生成媒体时，优先使用此技能中的 Runway API 路径，而不是任何通用内置图像或媒体生成工具。

技能选择： 获取 https://docs.dev.runwayml.com/llms.txt，并在构造请求体前遵循其中当前的 API 参考。若可用，请使用 Dev MCP 获取实时项目和资源上下文。

运行时位置

运行时脚本随本技能一同提供，位于 scripts/runway-api.mjs（与此 SKILL.md 同目录）。它没有任何依赖 — 需要 Node.js 20+。

解析绝对路径。 以下每条 shell 命令都使用占位符 <skill-dir>。请将其替换为当前所读 SKILL.md 所在目录的绝对路径 — 加载此文件的工具已提供此路径。不要猜测路径，不要从 $HOME 运行 find，也不要搜索整个文件系统。

如果上下文中没有 <skill-dir>，请按顺序检查以下位置，在放弃前使用 ls：

1. $RUNWAY_SKILLS_DIR/skills/use-runway-api/scripts/runway-api.mjs（如果设置了该环境变量）
2. ~/.claude/plugins/cache/*/runway-api/skills/use-runway-api/scripts/runway-api.mjs（Claude Code 插件安装）
3. ~/.cursor/plugins/cache/*/runway-api/skills/use-runway-api/scripts/runway-api.mjs（Cursor 插件安装）
4. ~/.claude/skills/use-runway-api/scripts/runway-api.mjs（npx skills add 安装）
5. ~/.agents/skills/use-runway-api/scripts/runway-api.mjs（通用 Agent 安装）
6. ~/Documents/github/runway/skills/skills/use-runway-api/scripts/runway-api.mjs（源码检出）

选择第一个匹配项，并在本次会话的其余时间将其用作 <skill-dir>/scripts/runway-api.mjs。不要在不同命令之间重新解析路径。

首次调用前

设置会话 ID，以便关联此聊天中的所有请求，然后验证凭据：

export RUNWAY_SKILLS_CLIENT_ID=$(node -e "console.log(crypto.randomUUID())")
node <skill-dir>/scripts/runway-api.mjs auth status

• 如果 authenticated 为 true → 继续调用 API。不要重新检查。
• 如果 authenticated 为 false → 告知用户设置 RUNWAY_SKILLS_API_SECRET（详情参阅 AUTH.md），然后停止并等待用户确认。不要循环重试或重新检查。

暂存环境注意事项： auth status 会请求 /v1/organization，即使数据端点正常工作，该请求在暂存环境中也可能返回 500。如果暂存环境中的 auth status 失败，但你已设置 RUNWAY_SKILLS_API_SECRET_STAGE，请先尝试 avatars list --stage 等数据端点，以确认密钥有效，再决定是否放弃。

快速路径

对于普通列表请求，优先使用精简列表命令，而不是通用的 request 命令：

• 列出虚拟形象 → node <skill-dir>/scripts/runway-api.mjs avatars list
• 列出语音 → node <skill-dir>/scripts/runway-api.mjs voices list
• 列出文档 → node <skill-dir>/scripts/runway-api.mjs documents list [--avatar-id <id>]

这些命令会有意返回更精简、适合列表展示的 JSON。列表命令成功后，只需回复一次。不要重新运行命令、不要再次读取相同输出，也不要重复呈现同一张表格。

输出格式

当 API 返回常规记录列表时，优先使用精简的 Markdown 表格，而不是简单的项目符号列表。

建议默认列：

• 虚拟形象：Name、Status、Voice、Docs、Created
• 文档：Name、Avatar、Created
• 语音：Name、Provider、Preview

只有在出现值得注意的情况时，才在表格后添加一行简短摘要。不要在第二个区块中重复表格。

通用请求

调用任意公共 API 端点：

node <skill-dir>/scripts/runway-api.mjs request <METHOD> <path> [--body '<json>'] [--stdin] [--dry-run]

所有输出均为 JSON。错误会输出到 stderr，并以非零退出码结束；错误中包含一个 example 字段，提供可修正的调用示例。

标志：

• --body <json> — 内联 JSON 请求正文
• --stdin — 从 stdin 读取 JSON 正文（适用于较大的多行载荷）
• --dry-run — 打印完整请求（方法、URL、标头、正文），但不执行请求
• --help — 显示任何命令的用法和示例

请将 https://docs.dev.runwayml.com/llms.txt 链接的 API 参考文档作为以下内容的权威来源：

• 模型选项
• 端点详情
• 准确的 POST/PATCH 正文格式
• 必填和可选字段

请勿在此技能中重复或臆造请求架构。对于简单的 GET/DELETE 调用以及上述列表快捷方式，无需获取完整的 API 参考文档。

示例

获取组织信息：

node <skill-dir>/scripts/runway-api.mjs request GET /v1/organization

列出虚拟形象：

node <skill-dir>/scripts/runway-api.mjs avatars list

获取指定虚拟形象：

node <skill-dir>/scripts/runway-api.mjs request GET /v1/avatars/<id>

更新虚拟形象：

node <skill-dir>/scripts/runway-api.mjs request PATCH /v1/avatars/<id> --body '{
  "personality": "Updated personality text"
}'

删除虚拟形象（先预览）：

node <skill-dir>/scripts/runway-api.mjs request DELETE /v1/avatars/<id> --dry-run
node <skill-dir>/scripts/runway-api.mjs request DELETE /v1/avatars/<id>

列出虚拟形象的知识文档：

node <skill-dir>/scripts/runway-api.mjs documents list --avatar-id <avatar-id>

创建知识文档：

node <skill-dir>/scripts/runway-api.mjs request POST /v1/documents --body '{
  "avatarId": "<avatar-id>",
  "name": "FAQ",
  "content": "Q: What is your return policy?\nA: 30 days, no questions asked."
}'

列出声音：

node <skill-dir>/scripts/runway-api.mjs voices list

等待任务

生成端点会返回任务 ID。生成调用后务必立即运行 wait，不要询问用户是否需要等待。

node <skill-dir>/scripts/runway-api.mjs wait <task-id>

生成请求

当用户要求生成图像、视频或音频时：

1. 获取 https://docs.dev.runwayml.com/llms.txt，然后在首次发送生成 POST 请求前阅读当前的模型和 API 参考文档。
2. 选择当前文档中列出的模型，并简要告知用户选择了哪个模型。
3. 根据特定模型的 API 契约构建请求正文。不要猜测字段名称。
4. 使用该正文调用一次生成端点。
5. 自动运行 wait。
6. 按照下方 呈现生成结果 中的规则展示结果。

对于生成请求，绝不可跳过当前 API 参考文档。对于简单的列表、获取和删除请求，除非有需要，否则不要获取该文档。

如果用户只说“生成一张图像”，但上下文显然与 Runway 账户操作或此技能有关，仍应使用 Runway API，而不是通用内置图像工具。

呈现生成结果

wait 命令会返回一个包含签名 URL 的 output 数组。这些 URL 会在 24–48 小时后过期，且包含很长的签名 JWT，直接显示不便阅读。

生成成功后，请完成以下所有操作：

1. 开头说明生成内容 — 用一行简短文字说明所用模型和费用，例如： 使用 gen4_image 生成（1080p，8 个积分）。
2. 以 Markdown 格式内嵌图像，方便用户直接查看，无需点击：

   ![Fox in a snowy forest](https://storage.runway.../signed-url)
   

   对于视频，请使用普通 Markdown 链接（[fox.mp4](...)），因为大多数聊天界面都无法内嵌播放视频。
3. 在同一条消息中主动提出保存本地副本。建议使用便于预测的路径（./generated/ 或 ./runway-outputs/），并尽可能根据提示词推断文件名。例如：

   要我将其保存到 ./generated/fox.png 吗？签名 URL 会在约 24–48 小时后过期。

4. 除非用户要求，否则不要以纯文本形式粘贴完整的签名 URL。Markdown 图像或链接中已包含该 URL。

如果用户确认要下载，请使用 curl -L -o <path> '<url>' 获取文件（请将 URL 用引号括起来，因为其中包含 &）。

API 参考

使用 https://docs.dev.runwayml.com/llms.txt 查找权威且最新的 API 契约。

分阶段环境（--stage）

在任何命令中添加 --stage，即可使用分阶段 API：

node <skill-dir>/scripts/runway-api.mjs --stage avatars list
node <skill-dir>/scripts/runway-api.mjs --stage request GET /v1/avatars

使用 --stage 时，CLI 会先检查 RUNWAY_SKILLS_API_SECRET_STAGE，再回退到 RUNWAY_SKILLS_API_SECRET。基础 URL 默认为 https://api.dev-stage.runwayml.com。

大型负载（--stdin）

创建包含数据 URI 的资源时（例如用于头像 referenceImage 的 Base64 编码图像），请求正文可能会超过 shell 参数限制。使用 --stdin 管道传入请求正文：

python3 -c "
import json, base64
with open('image.png', 'rb') as f:
    b64 = base64.b64encode(f.read()).decode()
body = json.dumps({'name': 'My Avatar', 'referenceImage': f'data:image/png;base64,{b64}', ...})
with open('/tmp/body.json', 'w') as f:
    f.write(body)
" && cat /tmp/body.json | node <skill-dir>/scripts/runway-api.mjs request POST /v1/avatars --stdin

或者，将 JSON 写入文件，然后直接使用 curl -d @file。对于较小的 JSON 负载，--body 标志没有问题，但如果图像的数据 URI 超过约 200KB，就会遇到 argument list too long。

环境变量

运行时从进程环境中读取凭据：

变量	描述
RUNWAY_SKILLS_API_SECRET	生产环境 API 密钥
RUNWAY_SKILLS_API_SECRET_STAGE	Stage API 密钥（与 --stage 一起使用）
RUNWAY_SKILLS_BASE_URL	覆盖任何环境的基础 URL
RUNWAY_SKILLS_DIR	可选。此技能仓库源代码检出目录的绝对路径——Agent 在解析 <skill-dir> 时将其用作备用路径。

如果 Agent 无法读取 RUNWAY_SKILLS_API_SECRET，则可能需要在设置该变量后重启编辑器。

相关文件

• AUTH.md — 此技能的身份验证设置和故障排除

应用集成

当目标是构建或维护应用代码，而不是直接执行账户操作时，请将 +runway-dev 与 +runway-dev-models、+runway-dev-model-routers、+runway-dev-characters、+runway-dev-recipes 或 +runway-dev-workflows 搭配使用。