Runway API 视频生成接入完整指南

1# 安装官方 SDK
2pip install runwayml
3
4# 验证安装
5python -c "import runwayml; print(runwayml.__version__)"

1# macOS / Linux
2export RUNWAYML_API_SECRET="你的-api-key"
3
4# Windows PowerShell
5$env:RUNWAYML_API_SECRET="你的-api-key"

1import time
2from runwayml import RunwayML
3
4# 初始化客户端（自动读取 RUNWAYML_API_SECRET）
5client = RunwayML()
6
7# 创建文生视频任务
8response = client.image_to_video.create(
9    model="gen4_turbo",          # 模型：gen4_turbo / gen45 / seedance_2.5
10    prompt_text="一只金毛犬在金色夕阳下的沙滩上奔跑，海浪轻拍海岸，毛发随风飘动，电影级运镜",  # 文字描述
11    duration=5,                   # 时长：5 或 10 秒
12    ratio="16:9",                # 宽高比：16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9
13)
14
15task_id = response.id
16print(f"任务已创建，ID: {task_id}")
17
18# 轮询任务状态（建议间隔 ≥ 5 秒）
19while True:
20    task = client.tasks.retrieve(task_id)
21    print(f"当前状态: {task.status}")
22
23    if task.status == "SUCCEEDED":
24        # 成功，输出视频地址
25        video_url = task.output[0]
26        print(f"✅ 视频生成成功: {video_url}")
27        break
28    elif task.status == "FAILED":
29        raise Exception(f"任务失败: {task.failure_code} - {task.failure}")
30
31    time.sleep(5)  # 避免 429 限流

1python text_to_video.py

1import time
2from runwayml import RunwayML
3
4client = RunwayML()
5
6# 图生视频：传入图片 URL + 运动提示
7response = client.image_to_video.create(
8    model="gen4_turbo",
9    prompt_image="https://example.com/your-photo.jpg",  # 输入图片的公网 URL
10    prompt_text="镜头缓缓推进，人物微微转头微笑，背景树叶随风摇曳",  # 可选：运动描述
11    duration=5,
12    ratio="16:9",
13)
14
15task_id = response.id
16print(f"图生视频任务已创建，ID: {task_id}")
17
18while True:
19    task = client.tasks.retrieve(task_id)
20    if task.status == "SUCCEEDED":
21        print(f"✅ 视频地址: {task.output[0]}")
22        break
23    elif task.status == "FAILED":
24        print(f"❌ 失败原因: {task.failure}")
25        break
26    time.sleep(5)

1import os
2import requests
3from urllib.parse import urlparse
4
5def download_video(video_url, save_dir="videos"):
6    """下载 Runway 生成的视频到本地"""
7    os.makedirs(save_dir, exist_ok=True)
8
9    # 用 URL 末尾的文件名作为保存名
10    file_name = os.path.basename(urlparse(video_url).path) or "runway_video.mp4"
11    save_path = os.path.join(save_dir, file_name)
12
13    response = requests.get(video_url, stream=True)
14    response.raise_for_status()
15
16    with open(save_path, "wb") as f:
17        for chunk in response.iter_content(chunk_size=8192):
18            f.write(chunk)
19
20    print(f"✅ 视频已保存: {save_path}")
21    return save_path
22
23# 配合上面的文生视频代码使用
24# download_video(video_url)

1export RUNWAYML_API_SECRET="你的-api-key"

1curl -X POST https://api.dev.runwayml.com/v1/image_to_video \
2  -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
3  -H "X-Runway-Version: 2024-11-06" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "model": "gen4_turbo",
7    "promptText": "一只金毛犬在金色夕阳下的沙滩上奔跑，海浪轻拍海岸，电影级运镜",
8    "duration": 5,
9    "ratio": "16:9"
10  }'

1{
2  "id": "2e5e2e23-7f7a-4e8d-b6c5-3e9c0e0e3e3e",
3  "createdAt": "2026-08-21T10:00:00.000Z",
4  "status": "THROTTLED",
5  "model": "gen4_turbo"
6}

1TASK_ID="2e5e2e23-7f7a-4e8d-b6c5-3e9c0e0e3e3e"
2
3curl https://api.dev.runwayml.com/v1/tasks/$TASK_ID \
4  -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
5  -H "X-Runway-Version: 2024-11-06"

1#!/bin/bash
2# poll_task.sh：轮询 Runway 任务直到完成
3TASK_ID=$1
4API_KEY=$RUNWAYML_API_SECRET
5
6while true; do
7  RESULT=$(curl -s https://api.dev.runwayml.com/v1/tasks/$TASK_ID \
8    -H "Authorization: Bearer $API_KEY" \
9    -H "X-Runway-Version: 2024-11-06")
10
11  STATUS=$(echo $RESULT | python -c "import sys,json; print(json.load(sys.stdin)['status'])")
12
13  echo "当前状态: $STATUS"
14
15  if [ "$STATUS" = "SUCCEEDED" ]; then
16    echo "✅ 任务成功"
17    echo $RESULT
18    break
19  elif [ "$STATUS" = "FAILED" ]; then
20    echo "❌ 任务失败"
21    echo $RESULT
22    break
23  fi
24
25  sleep 5
26done

1chmod +x poll_task.sh
2./poll_task.sh 2e5e2e23-7f7a-4e8d-b6c5-3e9c0e0e3e3e

1{
2  "id": "2e5e2e23-...",
3  "status": "SUCCEEDED",
4  "output": ["https://runwayml-prod-videos.s3.amazonaws.com/xxx.mp4"]
5}

1VIDEO_URL="https://runwayml-prod-videos.s3.amazonaws.com/xxx.mp4"
2curl -o my_video.mp4 "$VIDEO_URL"

1import time
2import requests
3
4def poll_with_retry(task_id, api_key, max_retries=20):
5    """带指数退避的任务轮询"""
6    for i in range(max_retries):
7        resp = requests.get(
8            f"https://api.dev.runwayml.com/v1/tasks/{task_id}",
9            headers={
10                "Authorization": f"Bearer {api_key}",
11                "X-Runway-Version": "2024-11-06",
12            },
13        )
14
15        if resp.status_code == 429:
16            wait = min(2 ** i, 60)  # 指数退避，最长 60 秒
17            print(f"触发限流，{wait} 秒后重试")
18            time.sleep(wait)
19            continue
20
21        resp.raise_for_status()
22        data = resp.json()
23
24        if data["status"] == "SUCCEEDED":
25            return data["output"][0]
26        elif data["status"] == "FAILED":
27            raise Exception(f"任务失败: {data.get('failure')}")
28
29        time.sleep(5)
30
31    raise TimeoutError("任务超时未完成")

1response = client.image_to_video.create(
2    model="gen4_turbo",
3    prompt_image="https://cdn.shop.com/products/sneaker-001.jpg",
4    prompt_text="运动鞋特写，镜头绕鞋身 360 度缓慢旋转，背景纯白，柔和影棚光，高端商品广告质感",
5    duration=5,
6    ratio="16:9",
7)

1# 批量生成 9:16 竖屏视频的分镜镜头
2shots = [
3    "城市夜景航拍，霓虹灯闪烁，车流如银河",
4    "咖啡杯特写，热气升腾，背景虚化",
5    "书页翻动特写，光影流转，复古质感",
6]
7
8for i, prompt in enumerate(shots):
9    response = client.image_to_video.create(
10        model="gen4_turbo",
11        prompt_text=prompt,
12        duration=5,
13        ratio="9:16",   # 竖屏适配抖音/小红书
14    )
15    # 后续下载后用剪映/PR拼接

1response = client.image_to_video.create(
2    model="gen45",
3    prompt_text="地球绕太阳公转的 3D 动画演示，太阳在中心发光，地球沿椭圆轨道缓慢移动，背景为深空星云，教学示意图风格",
4    duration=10,
5    ratio="16:9",
6)