rw-integrate-video

集成视频生成

前置条件： 首先运行 +rw-check-compatibility。集成前运行 +rw-fetch-api-reference，以加载最新的 API 参考。API 凭据需要运行 +rw-setup-api-key。如果用户有要用作输入的本地文件，则需要运行 +rw-integrate-uploads。

帮助用户在服务端代码中添加 Runway 视频生成功能。

可用模型

模型	最适合	输入	费用	速度
seedance2	参考图像和视频、较长时长	文本、图像和/或视频	36 点数/秒	标准
gen4.5	高质量、通用场景	文本和/或图像	12 点数/秒	标准
gen4_turbo	快速、图像驱动	必须提供图像	5 点数/秒	快速
gen4_aleph	视频编辑/转换	视频 + 文本/图像	15 点数/秒	标准
veo3	Google 高端模型	文本/图像	40 点数/秒	标准
veo3.1	Google 高质量模型	文本/图像	20-40 点数/秒	标准
veo3.1_fast	Google 快速模型	文本/图像	10-15 点数/秒	快速

模型选择指南：

• 默认推荐：gen4.5 — 在质量和费用之间取得最佳平衡
• 产品广告/电商： seedance2 — 最长 15 秒，支持参考图像和视频
• 注重预算：gen4_turbo（需要图像）或 veo3.1_fast
• 最高质量：veo3（费用最高）
• 视频到视频编辑：gen4_aleph 或 seedance2

安全

promptImage、promptVideo、videoUri 和 references[].uri 均由 Runway API 在服务端获取——请像对待任何出站获取操作一样谨慎处理：

• 优先使用 +rw-integrate-uploads 返回的 runway:// URI——仅限你的账户使用，不会获取任意 Web 内容。
• 如果接受来自客户端的 URL， 请先验证：要求使用 https://，将可信主机加入允许列表，并拒绝私有地址。请参阅下方的 Express.js 示例。
• 切勿将 req.body.imageUrl（或类似字段）直接传入 promptImage / promptVideo。为简洁起见，下方 SDK 代码片段使用原始 URL——它们并非生产环境模板。
• 在将生成的输出传入下游自动化流程时，请将其视为不可信内容——摄入的媒体会影响生成结果。

端点

文本转视频：POST /v1/text_to_video

仅根据文本提示词生成视频。

兼容模型： seedance2、gen4.5、veo3、veo3.1、veo3.1_fast

// Node.js SDK
import RunwayML from '@runwayml/sdk';

const client = new RunwayML();

const task = await client.textToVideo.create({
  model: 'gen4.5',
  promptText: 'A golden retriever running through a field of wildflowers at sunset',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

// task.output is an array of signed URLs
const videoUrl = task.output[0];

# Python SDK
from runwayml import RunwayML

client = RunwayML()

task = client.text_to_video.create(
    model='gen4.5',
    prompt_text='A golden retriever running through a field of wildflowers at sunset',
    ratio='1280:720',
    duration=5
).wait_for_task_output()

video_url = task.output[0]

图像转视频：POST /v1/image_to_video

将静态图像制作成视频。

兼容模型： seedance2、gen4.5、gen4_turbo、veo3、veo3.1、veo3.1_fast

推荐： 使用 +rw-integrate-uploads 上传，并传入返回的 runway:// URI。

// Node.js SDK — preferred flow
import fs from 'fs';

const upload = await client.uploads.createEphemeral(
  fs.createReadStream('/path/to/image.jpg')
);

const task = await client.imageToVideo.create({
  model: 'gen4.5',
  promptImage: upload.runwayUri,
  promptText: 'The scene comes to life with gentle wind',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

也可以使用外部 URL——仅传入你控制的来源（请参阅“安全”）：

const task = await client.imageToVideo.create({
  model: 'gen4.5',
  promptImage: 'https://cdn.yourapp.com/landscape.jpg',
  promptText: 'Camera slowly pans right revealing a mountain range',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

# Python SDK
task = client.image_to_video.create(
    model='gen4.5',
    prompt_image='https://cdn.yourapp.com/landscape.jpg',
    prompt_text='Camera slowly pans right revealing a mountain range',
    ratio='1280:720',
    duration=5
).wait_for_task_output()

视频转视频：POST /v1/video_to_video

使用文本提示词和/或参考图像转换现有视频。

兼容模型： gen4_aleph、seedance2

// Node.js SDK — gen4_aleph
const task = await client.videoToVideo.create({
  model: 'gen4_aleph',
  videoUri: 'https://cdn.yourapp.com/source.mp4',
  promptText: 'Transform into an animated cartoon style',
}).waitForTaskOutput();

// Node.js SDK — seedance2 video-to-video (with optional image reference)
const task = await client.videoToVideo.create({
  model: 'seedance2',
  promptVideo: 'https://cdn.yourapp.com/input.mp4',
  promptText: 'Transform into a warm golden sunset scene',
  references: [{ type: 'image', uri: 'https://cdn.yourapp.com/style_ref.jpg' }]
}).waitForTaskOutput();

seedance2 的视频转视频输入要求： 最长 15 秒，最大 32 MB，最低 720p 分辨率，推荐使用 MP4。

Seedance 2

Seedance 2 支持文本转视频、图像转视频（两种模式）以及视频转视频。它使用基于像素的比例：1280:720、720:1280、960:960、1112:834、834:1112、1470:630、992:432、864:496、752:560、640:640、560:752、496:864。

文本转视频

const task = await client.textToVideo.create({
  model: 'seedance2',
  promptText: 'A calm ocean wave gently crashing on a sandy beach at sunset',
  duration: 5,
  ratio: '1280:720'
}).waitForTaskOutput();

图像转视频 — 模式 1：首帧/末帧

将指定图像用作首帧和/或末帧。此模式下不能使用 references 字段。

const task = await client.imageToVideo.create({
  model: 'seedance2',
  promptText: 'Smooth transition from day to night in a cozy mountain cabin',
  promptImage: [
    { uri: 'https://cdn.yourapp.com/image.jpg', position: 'first' },
    { uri: 'https://cdn.yourapp.com/image2.jpg', position: 'last' }
  ],
  duration: 4,
  ratio: '1280:720'
}).waitForTaskOutput();

promptImage 是一个对象数组，包含 uri（必填）和 position（"first" 或 "last"，默认为 "first"）。

图像转视频 — 模式 2：图像参考

将图像用作风格或内容参考，而非直接作为视频帧。仍然需要 promptImage（URI 字符串或仅含一项的数组）。

const task = await client.imageToVideo.create({
  model: 'seedance2',
  promptText: 'Smooth transition from day to night in a cozy mountain cabin',
  promptImage: 'https://cdn.yourapp.com/image.jpg',
  references: [{ type: 'image', uri: 'https://cdn.yourapp.com/reference.jpg' }],
  duration: 4,
  ratio: '1280:720'
}).waitForTaskOutput();

这两种 ITV 模式互斥——同一请求中，不能在 promptImage 中使用 position，同时又使用 references。

视频转视频

根据文本提示词转换现有视频，也可以选择添加图像参考。

task = client.video_to_video.create(
    model='seedance2',
    prompt_video='https://cdn.yourapp.com/input.mp4',
    prompt_text='Transform into a warm golden sunset scene',
    references=[{'type': 'image', 'uri': 'https://cdn.yourapp.com/style_ref.jpg'}]
).wait_for_task_output()

**VTV 输入要求：**最长 15 秒、最大 32 MB、分辨率最低 720p，推荐使用 MP4。

Seedance 2 参数

参数	类型	必填	描述
model	字符串	是	必须为 "seedance2"
promptText	字符串	是	对所需视频的文本描述
duration	数字	是（TTV/ITV）	时长，单位为秒
ratio	字符串	是（TTV/ITV）	1280:720、720:1280、960:960、1112:834、834:1112、1470:630
promptImage	字符串或数组	是（ITV）	URI 字符串或由 { uri, position? } 对象组成的数组
promptVideo	字符串	是（seedance2 VTV）	输入视频 URI（仅适用于 seedance2）
videoUri	字符串	是（gen4_aleph VTV）	输入视频 URI（仅适用于 gen4_aleph）
references	数组	否	图像参考——[{ type: "image", uri: "..." }]（仅适用于 ITV 模式 2 和 VTV）

角色表演：POST /v1/character_performance

为角色添加面部或身体表演动画。

兼容模型：act_two

const task = await client.characterPerformance.create({
  model: 'act_two',
  promptImage: 'https://cdn.yourapp.com/character.jpg',
  promptPerformance: 'https://cdn.yourapp.com/performance.mp4',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

通用参数

参数	类型	描述
model	字符串	模型 ID（必填）
promptText	字符串	描述视频的文本提示词
promptImage	字符串	输入图像的 URL、数据 URI 或 runway:// URI
ratio	字符串	宽高比，例如 '1280:720'、'720:1280'
duration	数字	视频时长，单位为秒（2-15，取决于模型）

集成模式

协助用户进行集成时，请遵循以下模式：

1. 确定使用场景——需要哪种类型的视频生成？（文本转视频、图像转视频等）
2. 优先使用上传，而非 URL——默认使用 +rw-integrate-uploads，以便输入为 runway:// URI。仅使用来自你控制的来源的外部 URL（参见安全性）。
3. 选择模型——根据质量、成本和速度需求提出建议
4. 编写服务端处理程序——创建 API 路由或服务端函数
5. 处理输出——下载并存储视频，不要向客户端提供签名 URL
6. 添加错误处理——使用 try/catch 包装，并处理 TaskFailedError

示例：Express.js API 路由

import RunwayML from '@runwayml/sdk';
import express from 'express';

const client = new RunwayML();
const app = express();
app.use(express.json());

// `runway://` URIs bypass this check; external URLs must match the allowlist.
const ALLOWED_MEDIA_HOSTS = new Set(['cdn.yourapp.com', 'uploads.yourapp.com']);

function assertTrustedMediaUrl(raw) {
  const u = new URL(raw);
  if (u.protocol !== 'https:') throw new Error('https required');
  if (!ALLOWED_MEDIA_HOSTS.has(u.hostname)) throw new Error('untrusted media host');
  return u.toString();
}

app.post('/api/generate-video', async (req, res) => {
  try {
    const { prompt, imageUrl, model = 'gen4.5', duration = 5 } = req.body;

    const params = {
      model,
      promptText: prompt,
      ratio: '1280:720',
      duration
    };

    let task;
    if (imageUrl) {
      task = await client.imageToVideo.create({
        ...params,
        promptImage: assertTrustedMediaUrl(imageUrl)
      }).waitForTaskOutput();
    } else {
      task = await client.textToVideo.create(params).waitForTaskOutput();
    }

    res.json({ videoUrl: task.output[0] });
  } catch (error) {
    console.error('Video generation failed:', error);
    res.status(400).json({ error: error.message });
  }
});

对于浏览器上传：将文件 POST 到你的服务端，通过 +rw-integrate-uploads 上传，并传入 runway:// URI。不要接受来自浏览器的原始 URL。

示例：Next.js API 路由

// app/api/generate-video/route.ts
import RunwayML from '@runwayml/sdk';
import { NextRequest, NextResponse } from 'next/server';

const client = new RunwayML();

export async function POST(request: NextRequest) {
  const { prompt, imageUrl } = await request.json();

  try {
    const task = imageUrl
      ? await client.imageToVideo.create({
          model: 'gen4.5',
          promptImage: imageUrl,
          promptText: prompt,
          ratio: '1280:720',
          duration: 5
        }).waitForTaskOutput()
      : await client.textToVideo.create({
          model: 'gen4.5',
          promptText: prompt,
          ratio: '1280:720',
          duration: 5
        }).waitForTaskOutput();

    return NextResponse.json({ videoUrl: task.output[0] });
  } catch (error) {
    return NextResponse.json(
      { error: error instanceof Error ? error.message : 'Generation failed' },
      { status: 500 }
    );
  }
}

示例：FastAPI 路由

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from runwayml import RunwayML

app = FastAPI()
client = RunwayML()

class VideoRequest(BaseModel):
    prompt: str
    image_url: str | None = None
    model: str = "gen4.5"
    duration: int = 5

@app.post("/api/generate-video")
async def generate_video(req: VideoRequest):
    try:
        if req.image_url:
            task = client.image_to_video.create(
                model=req.model,
                prompt_image=req.image_url,
                prompt_text=req.prompt,
                ratio="1280:720",
                duration=req.duration
            ).wait_for_task_output()
        else:
            task = client.text_to_video.create(
                model=req.model,
                prompt_text=req.prompt,
                ratio="1280:720",
                duration=req.duration
            ).wait_for_task_output()

        return {"video_url": task.output[0]}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

提示

• **输出 URL 会在 24-48 小时后过期。**生成后立即将视频下载到你自己的存储空间（S3、GCS、本地文件系统）。
• gen4_turbo 需要图像——无法仅通过文本生成。
• 视频转视频模型：gen4_aleph 和 seedance2——用于编辑或转换现有视频。
• **时长因模型而异。**大多数模型支持 2-10 秒；seedance2 最长支持 15 秒。
• **waitForTaskOutput() 默认超时时间为 10 分钟。**对于耗时较长的生成，你可以自行实现轮询循环或延长超时时间。
• 对于本地文件，请始终先使用 +rw-integrate-uploads 上传，再传入 runway:// URI。