Back to Details

use-runway-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Use Runway API

使用Runway API

Call the Runway public API directly from the agent to manage resources, trigger generations, and inspect account state.
When to use this skill: Use this when the user wants to act on their Runway account — create or update avatars, manage documents, trigger generations, check credit balance, etc. For writing integration code into a project, use the 
+integrate-*
skills instead.
When the user asks to generate media in the context of Runway, prefer the Runway API path from this skill over any generic built-in image or media generation tool.
Skill selection: Pair this skill with 
+api-reference
when you need the canonical API contract. Do not use 
+integrate-image
, 
+integrate-video
, 
+integrate-audio
, 
+integrate-characters
, or 
+integrate-documents
unless the task is to write or modify application code.
通过Agent直接调用Runway公开API来管理资源、触发生成任务并查看账户状态。
何时使用此技能： 当用户需要对其Runway账户执行操作时使用——创建或更新虚拟形象、管理文档、触发生成任务、查看信用余额等。如果是要在项目中编写集成代码，请使用
+integrate-*
类技能。
当用户在Runway相关场景下要求生成媒体时，优先使用本技能中的Runway API路径，而非任何通用内置的图像或媒体生成工具。
技能选择： 当你需要标准API契约时，请将此技能与
+api-reference
搭配使用。除非任务是编写或修改应用代码，否则不要使用
+integrate-image
、
+integrate-video
、
+integrate-audio
、
+integrate-characters
或
+integrate-documents
。

Runtime Location

运行时位置

The runtime script ships inside this skill at 
scripts/runway-api.mjs
(co-located with this 
SKILL.md
). It has zero dependencies — Node.js 20+ is required.
Resolving the absolute path. Every shell command below uses the placeholder 
<skill-dir>
. Replace it with the absolute directory of the 
SKILL.md
you are currently reading — you already have this path from the tool that loaded this file. Do not guess the path, run 
find
from 
$HOME
, or search the whole filesystem.
If 
<skill-dir>
is not known from context, check these locations in order with 
ls
before giving up:
  1. $RUNWAY_SKILLS_DIR/skills/use-runway-api/scripts/runway-api.mjs
    (if the env var is set)
  2. ~/.claude/plugins/cache/*/runway-api/skills/use-runway-api/scripts/runway-api.mjs
    (Claude Code plugin install)
  3. ~/.cursor/plugins/cache/*/runway-api/skills/use-runway-api/scripts/runway-api.mjs
    (Cursor plugin install)
  4. ~/.claude/skills/use-runway-api/scripts/runway-api.mjs
    (
    npx skills add
    install)
  5. ~/.agents/skills/use-runway-api/scripts/runway-api.mjs
    (generic agent install)
  6. ~/Documents/github/runway/skills/skills/use-runway-api/scripts/runway-api.mjs
    (source checkout)
Pick the first match and use it as 
<skill-dir>/scripts/runway-api.mjs
for the rest of the session. Do not re-resolve between commands.
运行时脚本随本技能一起发布，位于
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
。请勿在命令之间重新解析路径。

Before Your First Call

首次调用前的准备

Set a session ID so all requests in this chat can be correlated, then verify credentials:
bash
export RUNWAY_SKILLS_CLIENT_ID=$(node -e "console.log(crypto.randomUUID())")
node <skill-dir>/scripts/runway-api.mjs auth status
  • If 
    authenticated
    is 
    true
    → proceed to the API call. Do not re-check.
  • If 
    authenticated
    is 
    false
    → tell the user to set 
    RUNWAY_SKILLS_API_SECRET
    (see 
    AUTH.md
    for details), then stop and wait for the user to confirm. Do not retry or re-check in a loop.
Staging caveat: 
auth status
hits 
/v1/organization
which may 500 on stage even when data endpoints work fine. If stage 
auth status
fails but you have 
RUNWAY_SKILLS_API_SECRET_STAGE
set, try a data endpoint like 
avatars list --stage
to confirm the key works before giving up.
设置会话ID，以便关联本次聊天中的所有请求，然后验证凭据：
bash
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
）来确认密钥可用，再决定是否放弃。

Fast Paths

快速路径

For plain list requests, use the compact list commands first instead of the generic 
request
command:
  • list avatars → 
    node <skill-dir>/scripts/runway-api.mjs avatars list
  • list voices → 
    node <skill-dir>/scripts/runway-api.mjs voices list
  • list documents → 
    node <skill-dir>/scripts/runway-api.mjs documents list [--avatar-id <id>]
These commands return smaller, list-friendly JSON on purpose. After a successful list command, answer once. Do not re-run the command, do not read back the same output, and do not render the same table twice.
对于简单的列表请求，请优先使用简洁的列表命令，而非通用的
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。成功执行列表命令后，只需回复一次。请勿重新运行命令，不要重复读取相同输出，也不要重复渲染同一表格。

Output Format

输出格式

When the API returns a regular list of records, prefer a compact markdown table over a bare bullet list.
Good defaults:
  • avatars: 
    Name
    , 
    Status
    , 
    Voice
    , 
    Docs
    , 
    Created
  • documents: 
    Name
    , 
    Avatar
    , 
    Created
  • voices: 
    Name
    , 
    Provider
    , 
    Preview
After the table, add one short summary line only if something notable stands out. Do not repeat the table in a second block.
当API返回常规记录列表时，优先使用简洁的Markdown表格，而非纯项目符号列表。
默认推荐列：
  • 虚拟形象：
    名称
    、
    状态
    、
    语音
    、
    文档数
    、
    创建时间
  • 文档：
    名称
    、
    所属虚拟形象
    、
    创建时间
  • 语音：
    名称
    、
    提供商
    、
    预览
表格后，仅当有值得注意的内容时才添加一行简短总结。请勿在第二个区块中重复表格内容。

Generic Request

通用请求

Call any public API endpoint:
bash
node <skill-dir>/scripts/runway-api.mjs request <METHOD> <path> [--body '<json>'] [--stdin] [--dry-run]
All output is JSON. Errors go to stderr with a non-zero exit code and include an 
example
field with a correctable invocation.
Flags:
  • --body <json>
    — inline JSON request body
  • --stdin
    — read JSON body from stdin (useful for large or multi-line payloads)
  • --dry-run
    — print the full request (method, URL, headers, body) without executing it
  • --help
    — show usage and examples for any command
Use 
+api-reference
as the canonical source for:
  • model choices
  • endpoint details
  • exact POST/PATCH body shapes
  • required and optional fields
Do not duplicate or invent request schemas in this skill. For simple GET/DELETE calls and the list fast paths above, you do not need to load 
+api-reference
.
调用任意公开API端点：
bash
node <skill-dir>/scripts/runway-api.mjs request <METHOD> <path> [--body '<json>'] [--stdin] [--dry-run]
所有输出均为JSON格式。错误信息会输出到stderr，返回非零退出码，并包含一个
example
字段，提供可修正的调用示例。
标志：
  • --body <json>
    — 内联JSON请求体
  • --stdin
    — 从标准输入读取JSON请求体（适用于大型或多行负载）
  • --dry-run
    — 打印完整请求（方法、URL、请求头、请求体）但不执行
  • --help
    — 显示任意命令的用法和示例
请将
+api-reference
作为以下内容的标准来源：
  • 模型选择
  • 端点详情
  • 准确的POST/PATCH请求体结构
  • 必填和可选字段
请勿在本技能中重复或自创请求模式。对于简单的GET/DELETE调用以及上述列表快速路径，无需加载
+api-reference
。

Examples

示例

Get organization info:
bash
node <skill-dir>/scripts/runway-api.mjs request GET /v1/organization
List avatars:
bash
node <skill-dir>/scripts/runway-api.mjs avatars list
Get a specific avatar:
bash
node <skill-dir>/scripts/runway-api.mjs request GET /v1/avatars/<id>
Update an avatar:
bash
node <skill-dir>/scripts/runway-api.mjs request PATCH /v1/avatars/<id> --body '{
  "personality": "Updated personality text"
}'
Delete an avatar (preview first):
bash
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>
List knowledge documents for an avatar:
bash
node <skill-dir>/scripts/runway-api.mjs documents list --avatar-id <avatar-id>
Create a knowledge document:
bash
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."
}'
List voices:
bash
node <skill-dir>/scripts/runway-api.mjs voices list
获取组织信息：
bash
node <skill-dir>/scripts/runway-api.mjs request GET /v1/organization
列出虚拟形象：
bash
node <skill-dir>/scripts/runway-api.mjs avatars list
获取特定虚拟形象：
bash
node <skill-dir>/scripts/runway-api.mjs request GET /v1/avatars/<id>
更新虚拟形象：
bash
node <skill-dir>/scripts/runway-api.mjs request PATCH /v1/avatars/<id> --body '{
  "personality": "Updated personality text"
}'
删除虚拟形象（先预览）：
bash
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>
列出虚拟形象的知识库文档：
bash
node <skill-dir>/scripts/runway-api.mjs documents list --avatar-id <avatar-id>
创建知识库文档：
bash
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."
}'
列出语音：
bash
node <skill-dir>/scripts/runway-api.mjs voices list

Waiting for Tasks

等待任务完成

Generation endpoints return a task ID. Always run 
wait
immediately after a generation call — do not ask the user whether to wait.
bash
node <skill-dir>/scripts/runway-api.mjs wait <task-id>
生成类端点会返回任务ID。触发生成调用后，请立即运行
wait
命令——无需询问用户是否等待。
bash
node <skill-dir>/scripts/runway-api.mjs wait <task-id>

Generation Requests

生成请求

When the user asks to generate an image, video, or audio:
  1. Read 
    +api-reference
    once before the first generation POST. It is the canonical source for model options, request body shapes, and valid field values.
  2. Choose the model from 
    +api-reference
    and tell the user which one you picked, briefly.
  3. Build the request body from 
    +api-reference
    . Do not guess field names.
  4. Call the generation endpoint once with that body.
  5. Run 
    wait
    automatically.
  6. Present the result following the rules in Presenting Generation Output below.
For generation requests, never skip the 
+api-reference
read. For simple list/get/delete requests, do not load it unless needed.
If the user says only "generate an image" but the surrounding context is clearly about Runway account actions or this skill, still use the Runway API rather than a generic built-in image tool.
当用户要求生成图像、视频或音频时：
  1. 在首次发送生成POST请求前，先读取
    +api-reference
    。它是模型选项、请求体结构和有效字段值的标准来源。
  2. 从
    +api-reference
    中选择模型，并简要告知用户你选择的模型。
  3. 根据
    +api-reference
    构建请求体。请勿猜测字段名称。
  4. 使用该请求体调用生成端点一次。
  5. 自动运行
    wait
    命令。
  6. 按照下方展示生成结果的规则呈现结果。
对于生成请求，切勿跳过读取
+api-reference
的步骤。对于简单的列表/获取/删除请求，除非需要，否则无需加载它。
如果用户仅说“生成一张图片”，但上下文明显涉及Runway账户操作或本技能，仍应使用Runway API而非通用内置图像工具。

Presenting Generation Output

展示生成结果

The 
wait
command returns a task with an 
output
array of signed URLs. These URLs expire in 24–48 hours and are long signed JWT blobs that are awkward to read inline.
After a successful generation, do all of the following:
  1. Lead with what was generated — one short line stating the model and cost, e.g. 
    Generated with gen4_image (1080p, 8 credits).
  2. Embed images inline as Markdown so the user can see them without clicking:
    markdown
    ![Fox in a snowy forest](https://storage.runway.../signed-url)
    For videos, link them as plain Markdown links (
    [fox.mp4](...)
    ) since inline video does not render in most chat UIs.
  3. Offer to save a local copy in the same message, proactively. Suggest a predictable path (
    ./generated/
    or 
    ./runway-outputs/
    ) and infer a filename from the prompt when possible. Example:
    Want me to save it to 
    ./generated/fox.png
    ? The signed URL expires in ~24–48h.
  4. Do not paste the full signed URL as raw text unless the user asks for it. The Markdown image/link already contains it.
If the user confirms a download, fetch with 
curl -L -o <path> '<url>'
(quote the URL — it contains 
&
).
wait
命令会返回一个包含
output
数组的任务，该数组包含带签名的URL。这些URL会在24-48小时后过期，且是冗长的签名JWT字符串，直接内联显示会很不友好。
成功生成后，请完成以下所有步骤：
  1. 先说明生成内容——用一行简短文字说明使用的模型和成本，例如： 
    使用gen4_image生成（1080p，消耗8个信用点）。
  2. 将图像以内联Markdown形式嵌入，让用户无需点击即可查看：
    markdown
    ![雪地森林中的狐狸](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 Reference

API参考

Use 
+api-reference
for the canonical API contract. Use 
+fetch-api-reference
only when you specifically need the latest docs content from 
docs.dev.runwayml.com
.
请将
+api-reference
作为标准API契约的来源。仅当你特别需要从
docs.dev.runwayml.com
获取最新文档内容时，才使用
+fetch-api-reference
。

Staging (--stage)

预发布环境（--stage）

Add 
--stage
to any command to target the staging API:
bash
node <skill-dir>/scripts/runway-api.mjs --stage avatars list
node <skill-dir>/scripts/runway-api.mjs --stage request GET /v1/avatars
With 
--stage
, the CLI checks 
RUNWAY_SKILLS_API_SECRET_STAGE
first, then falls back to 
RUNWAY_SKILLS_API_SECRET
. The base URL defaults to 
https://api.dev-stage.runwayml.com
.
在任意命令后添加
--stage
即可指向预发布API：
bash
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
。

Large Payloads (--stdin)

大型负载（--stdin）

When creating resources with data URIs (e.g. base64-encoded images for avatar 
referenceImage
), the body can exceed shell argument limits. Use 
--stdin
to pipe the body:
bash
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
Alternatively, write the JSON to a file and use 
curl -d @file
directly. The 
--body
flag is fine for small JSON payloads but will hit 
argument list too long
for data URIs of images over ~200KB.
当创建包含数据URI的资源时（例如虚拟形象
referenceImage
的base64编码图像），请求体可能会超出shell参数限制。请使用
--stdin
来传递请求体：
bash
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
标志足够，但对于超过约200KB的图像数据URI，会触发
argument list too long
错误。

Environment Variables

环境变量

The runtime reads credentials from the process environment:
VariableDescription
RUNWAY_SKILLS_API_SECRET
Production API key
RUNWAY_SKILLS_API_SECRET_STAGE
Stage API key (used with 
--stage
)
RUNWAY_SKILLS_BASE_URL
Override the base URL for any environment
RUNWAY_SKILLS_DIR
Optional. Absolute path to the source checkout of this skills repo — used by the agent as a fallback when resolving 
<skill-dir>
.
If the agent cannot see 
RUNWAY_SKILLS_API_SECRET
, the editor likely needs to be restarted after the variable is set.
运行时会从进程环境中读取凭据：
变量描述
RUNWAY_SKILLS_API_SECRET
生产环境API密钥
RUNWAY_SKILLS_API_SECRET_STAGE
预发布环境API密钥（与
--stage
搭配使用）
RUNWAY_SKILLS_BASE_URL
覆盖任意环境的基础URL
RUNWAY_SKILLS_DIR
可选。本技能仓库源码检出的绝对路径——当解析
<skill-dir>
时，Agent会将其用作回退路径。
如果Agent无法读取
RUNWAY_SKILLS_API_SECRET
，可能需要在设置变量后重启编辑器。

Related Files

相关文件

  • AUTH.md
    — auth setup and troubleshooting for this skill
  • AUTH.md
    — 本技能的身份验证设置和故障排除指南

Related Skills

相关技能

SkillWhen to use
+api-reference
Full API reference — models, endpoints, costs, rate limits
+fetch-api-reference
Fetch latest docs from docs.dev.runwayml.com
+integrate-video
Write video generation code into a project
+integrate-image
Write image generation code into a project
+integrate-audio
Write audio generation code into a project
+integrate-characters
Write avatar session code into a project
+integrate-documents
Write knowledge document code into a project
技能使用场景
+api-reference
完整API参考——模型、端点、成本、速率限制
+fetch-api-reference
从docs.dev.runwayml.com获取最新文档
+integrate-video
在项目中编写视频生成代码
+integrate-image
在项目中编写图像生成代码
+integrate-audio
在项目中编写音频生成代码
+integrate-characters
在项目中编写虚拟形象会话代码
+integrate-documents
在项目中编写知识库文档代码