recipe-full-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Full Runway API Setup

完整Runway API配置指南

PREREQUISITE: Run
+check-compatibility
first to ensure the project has server-side capability.

This recipe guides a user through the complete process of integrating Runway's public API into their project. It chains together the compatibility check, API key setup, and API integration skills.

前置要求: 先运行
+check-compatibility
确认项目具备服务端运行能力。

本指南将引导用户完成将Runway公共API集成到项目中的全流程，串联了兼容性检查、API密钥配置、API集成三个步骤的技能。

Workflow

工作流程

Phase 1: Compatibility Check

阶段1：兼容性检查

Use

+check-compatibility

to analyze the user's project.

Identify the project type (Node.js, Python, etc.)
Verify server-side capability
Check runtime version compatibility
Look for existing Runway SDK installation

If the project is INCOMPATIBLE, stop and explain the options:

Add a backend (Express, FastAPI, etc.)
Use a fullstack framework (Next.js, SvelteKit, Nuxt, Remix)
Add serverless functions (Vercel Functions, AWS Lambda)
Create a separate backend service

If NEEDS CHANGES, help the user make the required changes before proceeding.

If COMPATIBLE, proceed to Phase 2.

使用

+check-compatibility

分析用户的项目：

识别项目类型（Node.js、Python等）
验证服务端运行能力
检查运行时版本兼容性
查看是否已安装Runway SDK

如果项目不兼容，停止操作并告知可选解决方案：

新增后端服务（Express、FastAPI等）
使用全栈框架（Next.js、SvelteKit、Nuxt、Remix）
新增无服务器函数（Vercel Functions、AWS Lambda）
创建独立的后端服务

如果需要调整，先帮助用户完成必要的修改再继续后续步骤。

如果兼容，进入阶段2。

Phase 2: API Key Setup

阶段2：API密钥配置

Use

+setup-api-key

to configure credentials.

Direct the user to https://dev.runwayml.com/ to create an account and API key
Install the appropriate SDK (
```
@runwayml/sdk
```
for Node.js,
```
runwayml
```
for Python)
Configure the
```
RUNWAYML_API_SECRET
```
environment variable
Update
```
.gitignore
```
to exclude
```
.env
```
Remind about credit purchase requirement ($10 minimum)

Wait for the user to confirm they have their API key before proceeding.

使用

+setup-api-key

配置凭证：

引导用户访问https://dev.runwayml.com/ 创建账号并生成API密钥
安装对应SDK（Node.js使用
```
@runwayml/sdk
```
，Python使用
```
runwayml
```
）
配置
```
RUNWAYML_API_SECRET
```
环境变量
更新
```
.gitignore
```
排除
```
.env
```
文件
提醒用户需要预先充值（最低10美元）

等待用户确认已获取API密钥后再继续后续流程。

Phase 3: Determine What to Integrate

阶段3：确定集成内容

Ask the user what they want to build. Based on their response, use the appropriate integration skill:

User wants...	Skill to use
Generate videos from text	`+integrate-video` (text-to-video)
Animate images into video	`+integrate-video` (image-to-video) + `+integrate-uploads` if local files
Edit/transform existing videos	`+integrate-video` (video-to-video) + `+integrate-uploads`
Generate images from text	`+integrate-image`
Generate images with references	`+integrate-image` + `+integrate-uploads` if local refs
Text-to-speech	`+integrate-audio`
Sound effects	`+integrate-audio`
Voice isolation/dubbing	`+integrate-audio` + `+integrate-uploads`
Real-time conversational avatar	`+integrate-characters` + `+integrate-character-embed` (React UI)
Avatar with domain knowledge	`+integrate-characters` + `+integrate-documents` + `+integrate-character-embed`
Multiple capabilities	Integrate each one, sharing the same client instance

询问用户的开发需求，根据其回答使用对应的集成技能：

用户需求	所需使用的技能
文本生成视频	`+integrate-video` （文生视频）
图片动效生成视频	`+integrate-video` （图生视频） + 如果涉及本地文件需搭配 `+integrate-uploads`
编辑/转换现有视频	`+integrate-video` （视频生视频） + `+integrate-uploads`
文本生成图片	`+integrate-image`
参考图生成图片	`+integrate-image` + 如果涉及本地参考图需搭配 `+integrate-uploads`
文本转语音	`+integrate-audio`
音效生成	`+integrate-audio`
人声分离/配音	`+integrate-audio` + `+integrate-uploads`
实时对话虚拟人	`+integrate-characters` + `+integrate-character-embed` （React UI）
具备领域知识的虚拟人	`+integrate-characters` + `+integrate-documents` + `+integrate-character-embed`
多项能力需求	复用同一个客户端实例，分别集成对应能力

Phase 4: Write the Integration Code

阶段4：编写集成代码

Based on the user's framework and needs:

Create the API route/handler — server-side endpoint that calls Runway
Add upload handling if the user needs to accept files from their users
Add error handling — catch and handle task failures
Handle output storage — remind user that output URLs expire in 24-48 hours

根据用户的框架和需求：

创建API路由/处理函数 — 调用Runway的服务端端点
添加上传处理逻辑 如果需要接收用户上传的文件
添加错误处理 — 捕获并处理任务失败场景
处理输出存储 — 提醒用户生成结果的URL有效期为24-48小时

Phase 5: Test and Verify

阶段5：测试与验证

Help the user:

Run a test generation to verify everything works
Check for common issues (missing env var, insufficient credits, wrong model)
Confirm output is accessible

帮助用户完成以下操作：

运行一次生成测试，确认所有流程正常运行
排查常见问题（环境变量缺失、余额不足、模型选择错误）
确认生成的输出可正常访问

Decision Tree for Upload Requirements

上传需求决策树

When the user's workflow involves images or videos as input:

Does the input come from a public HTTPS URL?
├── YES → Pass the URL directly to the API
└── NO → Is it a local file or user-uploaded file?
    ├── YES → Use +integrate-uploads to upload first, then pass runway:// URI
    └── NO → Is it small enough for a data URI? (< 5MB image, < 16MB video)
        ├── YES → Convert to base64 data URI
        └── NO → Use +integrate-uploads

当用户的工作流需要将图片或视频作为输入时：

Does the input come from a public HTTPS URL?
├── YES → Pass the URL directly to the API
└── NO → Is it a local file or user-uploaded file?
    ├── YES → Use +integrate-uploads to upload first, then pass runway:// URI
    └── NO → Is it small enough for a data URI? (< 5MB image, < 16MB video)
        ├── YES → Convert to base64 data URI
        └── NO → Use +integrate-uploads

Important Reminders

重要提醒

Never expose the API key in client-side code. All API calls must happen server-side.
Output URLs expire. Always download and store generated content.
Credits are required. The API won't work without prepaid credits.
Rate limits exist. Rate limits exist. You should always check what is the rate limit before attempting concurrent generations.
Content moderation applies to both inputs and outputs. Safety-flagged inputs are non-refundable.
Be cost-conscious. Help users pick the right model for their budget. Credit cost can be found on https://docs.dev.runwayml.com/guides/pricing/

绝对不要在客户端代码中暴露API密钥，所有API调用必须在服务端执行
输出URL有有效期，请务必下载并存储生成的内容
需要预充值额度，没有预付费额度的话API无法调用
存在速率限制，调用前请先确认速率限制，再进行并发生成操作
内容审核规则同时适用于输入和输出，被安全标记的输入消耗的额度不予退还
注意控制成本，帮助用户选择符合预算的模型，额度消耗标准可查看https://docs.dev.runwayml.com/guides/pricing/