runway

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Runway API

Use the Runway API via direct

curl

calls to generate AI videos from images, text, or video inputs.

Official docs:
https://docs.dev.runwayml.com/

通过直接调用

curl

使用Runway API，从图片、文本或视频输入生成AI视频。

官方文档：
https://docs.dev.runwayml.com/

When to Use

使用场景

Use this skill when you need to:

Generate video from images (image-to-video)
Generate video from text prompts (text-to-video)
Transform existing videos (video-to-video)
Generate images from text (text-to-image)
Upscale video resolution (4X upscale)
Generate sound effects or speech

当你需要以下操作时使用该技能：

从图片生成视频（图生视频）
从文本提示生成视频（文本生成视频）
转换现有视频（视频转视频）
从文本生成图片（文本生图）
提升视频分辨率（4倍超分）
生成音效或语音

Prerequisites

前置条件

Sign up at Runway Developer Portal
Purchase credits ($10 for 1000 credits)
Create an API key in the dashboard
Store it in the environment variable
```
RUNWAY_API_KEY
```

bash

export RUNWAY_API_KEY="your-api-key"

在Runway开发者门户注册账号
购买点数（10美元可购1000点数）
在控制台中创建API密钥
将密钥存储到环境变量
```
RUNWAY_API_KEY
```
中

bash

export RUNWAY_API_KEY="your-api-key"

Pricing

定价

Credits are consumed per generation
~25 credits per 5-second video

Important: When using
$VAR
in a command that pipes to another command, wrap the command containing
$VAR
in
bash -c '...'
. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'

每次生成会消耗点数
每5秒视频约消耗25点数

重要提示： 当在包含管道的命令中使用
$VAR
时，请将包含
$VAR
的命令用
bash -c '...'
包裹。由于Claude Code的bug，直接使用管道时环境变量会被静默清除。
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'

How to Use

使用方法

All examples below assume you have

RUNWAY_API_KEY

set.

Base URL:

https://api.dev.runwayml.com/v1

Required headers for all requests:

```
Authorization: Bearer ${RUNWAY_API_KEY}
```
```
X-Runway-Version: 2024-11-06
```
```
Content-Type: application/json
```

以下所有示例均假设你已设置好

RUNWAY_API_KEY

。

基础URL：

https://api.dev.runwayml.com/v1

所有请求必填的请求头：

```
Authorization: Bearer ${RUNWAY_API_KEY}
```
```
X-Runway-Version: 2024-11-06
```
```
Content-Type: application/json
```

1. Check Organization Credits

1. 查看组织余额

Check your credit balance:

bash

bash -c 'curl -s -X GET "https://api.dev.runwayml.com/v1/organization" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06"'

查询你的点数余额：

bash

bash -c 'curl -s -X GET "https://api.dev.runwayml.com/v1/organization" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06"'

2. Image to Video

2. 图生视频

Generate a video from an image:

Write to

/tmp/runway_request.json

json

{
  "model": "gen4_turbo",
  "promptImage": "https://example.com/your-image.jpg",
  "promptText": "A timelapse of clouds moving across the sky",
  "ratio": "1280:720",
  "duration": 5
}

Then run:

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/image_to_video" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

Response:

json

{
  "id": "task-id-here"
}

从图片生成视频：

将以下内容写入

/tmp/runway_request.json

：

json

{
  "model": "gen4_turbo",
  "promptImage": "https://example.com/your-image.jpg",
  "promptText": "A timelapse of clouds moving across the sky",
  "ratio": "1280:720",
  "duration": 5
}

然后运行：

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/image_to_video" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

响应：

json

{
  "id": "task-id-here"
}

3. Text to Video

3. 文本生成视频

Generate a video from text only:

Note: Text-to-video only supports duration values of 4, 6, or 8 seconds (not arbitrary values like image-to-video).

Write to

/tmp/runway_request.json

json

{
  "model": "veo3.1",
  "promptText": "A serene forest with sunlight filtering through the trees",
  "ratio": "1280:720",
  "duration": 6
}

Then run:

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/text_to_video" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

仅从文本生成视频：

注意： 文本生成视频仅支持4、6或8秒的时长（不像图生视频支持任意时长）。

将以下内容写入

/tmp/runway_request.json

：

json

{
  "model": "veo3.1",
  "promptText": "A serene forest with sunlight filtering through the trees",
  "ratio": "1280:720",
  "duration": 6
}

然后运行：

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/text_to_video" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

4. Video to Video

4. 视频转视频

Transform an existing video:

Write to

/tmp/runway_request.json

json

{
  "model": "gen4_aleph",
  "videoUri": "https://example.com/source-video.mp4",
  "promptText": "Add magical sparkles and fairy dust effects",
  "ratio": "1280:720"
}

Then run:

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/video_to_video" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

转换现有视频：

将以下内容写入

/tmp/runway_request.json

：

json

{
  "model": "gen4_aleph",
  "videoUri": "https://example.com/source-video.mp4",
  "promptText": "Add magical sparkles and fairy dust effects",
  "ratio": "1280:720"
}

然后运行：

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/video_to_video" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

5. Text to Image

5. 文本生图

Generate images from text:

Write to

/tmp/runway_request.json

json

{
  "model": "gen4_image_turbo",
  "promptText": "A futuristic cityscape at sunset",
  "ratio": "1920:1080",
  "referenceImages": []
}

Then run:

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/text_to_image" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

从文本生成图片：

将以下内容写入

/tmp/runway_request.json

：

json

{
  "model": "gen4_image_turbo",
  "promptText": "A futuristic cityscape at sunset",
  "ratio": "1920:1080",
  "referenceImages": []
}

然后运行：

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/text_to_image" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

6. Check Task Status

6. 检查任务状态

Poll for task completion. Replace

<your-task-id>

with the actual task ID:

bash

bash -c 'curl -s -X GET "https://api.dev.runwayml.com/v1/tasks/<your-task-id>" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06"'

Response when complete:

json

{
  "id": "task-id",
  "status": "SUCCEEDED",
  "output": ["https://cdn.runwayml.com/generated-video.mp4"]
}

Possible statuses:

PENDING

RUNNING

SUCCEEDED

FAILED

轮询任务完成情况。将

<your-task-id>

替换为实际的任务ID：

bash

bash -c 'curl -s -X GET "https://api.dev.runwayml.com/v1/tasks/<your-task-id>" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06"'

完成时的响应：

json

{
  "id": "task-id",
  "status": "SUCCEEDED",
  "output": ["https://cdn.runwayml.com/generated-video.mp4"]
}

可能的状态：

PENDING

（待处理）、

RUNNING

（运行中）、

SUCCEEDED

（成功）、

FAILED

（失败）

7. Cancel a Task

7. 取消任务

Cancel a running task. Replace

<your-task-id>

with the actual task ID:

bash

bash -c 'curl -s -X DELETE "https://api.dev.runwayml.com/v1/tasks/<your-task-id>" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06"'

取消正在运行的任务。将

<your-task-id>

替换为实际的任务ID：

bash

bash -c 'curl -s -X DELETE "https://api.dev.runwayml.com/v1/tasks/<your-task-id>" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06"'

8. Video Upscale (4X)

8. 视频4倍超分

Upscale video resolution:

Write to

/tmp/runway_request.json

json

{
  "model": "upscale_v1",
  "videoUri": "https://example.com/low-res-video.mp4"
}

Then run:

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/video_upscale" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

提升视频分辨率：

将以下内容写入

/tmp/runway_request.json

：

json

{
  "model": "upscale_v1",
  "videoUri": "https://example.com/low-res-video.mp4"
}

然后运行：

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/video_upscale" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

9. Generate Sound Effects

9. 生成音效

Generate audio from text:

Write to

/tmp/runway_request.json

json

{
  "model": "eleven_text_to_sound_v2",
  "promptText": "Thunder rumbling in the distance"
}

Then run:

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/sound_effect" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

从文本生成音频：

将以下内容写入

/tmp/runway_request.json

：

json

{
  "model": "eleven_text_to_sound_v2",
  "promptText": "Thunder rumbling in the distance"
}

然后运行：

bash

bash -c 'curl -s -X POST "https://api.dev.runwayml.com/v1/sound_effect" --header "Authorization: Bearer ${RUNWAY_API_KEY}" --header "X-Runway-Version: 2024-11-06" --header "Content-Type: application/json" -d @/tmp/runway_request.json'

Available Models

可用模型

Endpoint	Models
Image to Video	`gen4_turbo` , `gen3a_turbo` , `veo3.1` , `veo3`
Text to Video	`veo3.1` , `veo3.1_fast` , `veo3`
Video to Video	`gen4_aleph`
Text to Image	`gen4_image_turbo` , `gen4_image`
Video Upscale	`upscale_v1`

接口	模型
图生视频	`gen4_turbo` , `gen3a_turbo` , `veo3.1` , `veo3`
文本生成视频	`veo3.1` , `veo3.1_fast` , `veo3`
视频转视频	`gen4_aleph`
文本生图	`gen4_image_turbo` , `gen4_image`
视频超分	`upscale_v1`

Aspect Ratios

宽高比

Common ratios for video generation:

```
1280:720
```
(16:9 landscape)
```
720:1280
```
(9:16 portrait)
```
1024:1024
```
(1:1 square)

视频生成常用宽高比：

```
1280:720
```
（16:9 横屏）
```
720:1280
```
（9:16 竖屏）
```
1024:1024
```
（1:1 正方形）

Guidelines

注意事项

Poll for completion: Video generation is async; poll
```
/tasks/{id}
```
until status is
```
SUCCEEDED
```
Use appropriate models:
```
gen4_turbo
```
is faster,
```
gen4_aleph
```
for video-to-video
Download promptly: Output URLs may expire after some time
Monitor credits: Check
```
/organization
```
endpoint to track usage
Handle rate limits: API returns 429 when rate limited; add delays

轮询完成状态：视频生成为异步操作；轮询
```
/tasks/{id}
```
直到状态变为
```
SUCCEEDED
```
使用合适的模型：
```
gen4_turbo
```
速度更快，
```
gen4_aleph
```
适用于视频转视频
及时下载输出：输出URL可能会在一段时间后过期
监控点数使用：调用
```
/organization
```
接口跟踪点数消耗
处理速率限制：当达到速率限制时API会返回429；请添加延迟重试