integrate-video

集成视频生成

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

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

可用模型

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

模型选择建议：

• 默认推荐：gen4.5 ——质量与费用的平衡最佳
• 注重预算：gen4_turbo（需要图像）或 veo3.1_fast
• 追求最高质量：veo3（费用最高）
• 视频到视频编辑：gen4_aleph（唯一选项）

端点

文本生成视频：POST /v1/text_to_video

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

兼容模型： 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

将静态图像制作成动态视频。

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

// Node.js SDK
const task = await client.imageToVideo.create({
  model: 'gen4.5',
  promptImage: 'https://example.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://example.com/landscape.jpg',
    prompt_text='Camera slowly pans right revealing a mountain range',
    ratio='1280:720',
    duration=5
).wait_for_task_output()

如果用户有本地图像文件，请先使用 +integrate-uploads 上传：

// Upload local file first
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,  // Use the runway:// URI
  promptText: 'The scene comes to life with gentle wind',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

视频到视频：POST /v1/video_to_video

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

兼容模型： gen4_aleph

// Node.js SDK
const task = await client.videoToVideo.create({
  model: 'gen4_aleph',
  promptVideo: 'https://example.com/source.mp4',
  promptText: 'Transform into an animated cartoon style',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

角色表演：POST /v1/character_performance

为角色制作面部／身体表演动画。

兼容模型： act_two

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

常用参数

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

集成模式

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

1. 确定使用场景 ——需要哪种视频生成方式？（文本生成视频、图像生成视频等）
2. 检查本地文件 ——如果用户有本地图像／视频，请先使用 +integrate-uploads
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());

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: 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(500).json({ error: error.message });
  }
});

示例：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 是唯一的视频到视频模型 ——使用它编辑／转换现有视频。
• 时长范围为 2-10 秒。 更长的视频需要串联多次生成。
• waitForTaskOutput() 默认超时时间为 10 分钟。 对于耗时较长的生成任务，可以自行实现轮询循环或延长超时时间。
• 对于本地文件，请务必先使用 +integrate-uploads 上传，然后传入 runway:// URI。