integrate-uploads

集成上传

前置条件： 请先运行 +check-compatibility。集成前运行 +fetch-api-reference，以加载最新的 API 参考文档。API 凭据需要运行 +setup-api-key。

帮助用户将本地文件（图像、视频、音频）上传到 Runway 的临时存储，以便将其用作生成模型的输入。

何时使用上传

在以下情况下使用 Uploads API：

• 用户有想要用作输入的本地文件（而非公开 URL）
• 文件超过数据 URI 大小限制（图像为 5 MB，视频/音频为 16 MB）
• 文件的 URL 不符合 Runway 的 URL 要求（HTTPS、正确的标头、无重定向）

以下情况无需上传：

• 资源已经位于具有正确标头的公开 HTTPS URL 上
• 资源足够小，可以使用数据 URI（图像小于 5 MB，视频小于 16 MB）

工作原理

1. 申请临时上传槽位 → 获取预签名上传 URL 和表单字段
2. 将文件上传到预签名 URL
3. 将返回的 runway:// URI 用作任何生成端点的输入

runway:// URI 的有效期为 24 小时。

SDK 上传（推荐）

Node.js

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

const client = new RunwayML();

// Upload from a file stream
const upload = await client.uploads.createEphemeral(
  fs.createReadStream('/path/to/image.jpg')
);

// Use the runway:// URI in any generation call
const task = await client.imageToVideo.create({
  model: 'gen4.5',
  promptImage: upload.runwayUri,
  promptText: 'The scene comes to life',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

Node.js SDK 接受以下类型：

• fs.ReadStream — 文件流
• File 对象 — 来自 Web API
• Blob 对象
• Buffer / ArrayBuffer / 类型化数组
• Response 对象 — 来自 fetch()
• 异步可迭代对象

Python

from runwayml import RunwayML
from pathlib import Path

client = RunwayML()

# Upload from a file path
upload = client.uploads.create_ephemeral(
    Path('/path/to/image.jpg')
)

# Use the runway:// URI
task = client.image_to_video.create(
    model='gen4.5',
    prompt_image=upload.runway_uri,
    prompt_text='The scene comes to life',
    ratio='1280:720',
    duration=5
).wait_for_task_output()

Python SDK 接受以下类型：

• pathlib.Path 对象
• IOBase 对象（类文件对象）
• (filename, content) 二元组

REST API 上传（手动）

如果不使用 SDK，上传流程分为三个步骤：

步骤 1：创建上传槽位

const response = await fetch('https://api.dev.runwayml.com/v1/uploads', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.RUNWAYML_API_SECRET}`,
    'X-Runway-Version': '2024-11-06',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filename: 'image.jpg',
    type: 'ephemeral'
  })
});

const { uploadUrl, fields, runwayUri } = await response.json();

步骤 2：使用预签名 URL 上传文件

const formData = new FormData();

// Add all presigned form fields first
for (const [key, value] of Object.entries(fields)) {
  formData.append(key, value);
}

// Add the file last
formData.append('file', fileBuffer, 'image.jpg');

await fetch(uploadUrl, {
  method: 'POST',
  body: formData
});

步骤 3：使用 runway:// URI

const task = await fetch('https://api.dev.runwayml.com/v1/image_to_video', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.RUNWAYML_API_SECRET}`,
    'X-Runway-Version': '2024-11-06',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gen4.5',
    promptImage: runwayUri,
    promptText: 'Animate this scene',
    ratio: '1280:720',
    duration: 5
  })
});

上传限制

限制	值
文件最小大小	512 字节
文件最大大小	200 MB
URI 有效期	24 小时
需要额度	是（必须已购买额度）

集成模式

Express.js — 带文件生成的上传端点

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

const client = new RunwayML();
const app = express();
const upload = multer({ storage: multer.memoryStorage() });

app.post('/api/image-to-video', upload.single('image'), async (req, res) => {
  try {
    // Upload the user's file to Runway
    const runwayUpload = await client.uploads.createEphemeral(req.file.buffer);

    // Use the uploaded file for video generation
    const task = await client.imageToVideo.create({
      model: 'gen4.5',
      promptImage: runwayUpload.runwayUri,
      promptText: req.body.prompt || 'Animate this image',
      ratio: '1280:720',
      duration: 5
    }).waitForTaskOutput();

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

Next.js — 上传 + 生成

// app/api/image-to-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 formData = await request.formData();
  const imageFile = formData.get('image') as File;
  const prompt = formData.get('prompt') as string;

  try {
    // Upload file to Runway
    const upload = await client.uploads.createEphemeral(imageFile);

    // Generate video from the uploaded image
    const task = await client.imageToVideo.create({
      model: 'gen4.5',
      promptImage: upload.runwayUri,
      promptText: prompt || 'Animate this image',
      ratio: '1280:720',
      duration: 5
    }).waitForTaskOutput();

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

FastAPI — 上传 + 生成

from fastapi import FastAPI, UploadFile, Form, HTTPException
from runwayml import RunwayML

app = FastAPI()
client = RunwayML()

@app.post("/api/image-to-video")
async def image_to_video(image: UploadFile, prompt: str = Form("Animate this image")):
    try:
        # Upload to Runway
        content = await image.read()
        upload = client.uploads.create_ephemeral((image.filename, content))

        # Generate video
        task = client.image_to_video.create(
            model="gen4.5",
            prompt_image=upload.runway_uri,
            prompt_text=prompt,
            ratio="1280:720",
            duration=5
        ).wait_for_task_output()

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

提示

• 在将本地文件传递给生成端点之前，务必先上传。 不要尝试传递本地文件路径——那样行不通。
• runway:// URI 会在 24 小时后过期。 如果需要再次使用某项资源，请重新上传。
• SDK 会自动处理预签名 URL 流程——优先使用 SDK，而不是手动调用 REST。
• 对于需要图像/视频输入的模型（图像转视频、视频转视频、角色表演），请先上传资源，再传递 runway:// URI。
• 通过上传方式，每个文件最大为 200 MB——大于 URL（16 MB）或数据 URI（5 MB）的限制。