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) の 2 要素タプル

REST API によるアップロード（手動）

SDK を使用しない場合、アップロードの手順は 3 つです。

ステップ 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 を使った手順を自動的に処理します。 手動の REST 呼び出しより SDK を優先してください。
• 画像／動画入力が必要なモデル（画像から動画、動画から動画、キャラクターパフォーマンス）では、先にアセットをアップロードしてから runway:// URI を渡してください。
• アップロードで扱えるファイルの最大サイズは 200 MBです。URL（16 MB）やデータ URI（5 MB）の制限より大きなファイルを扱えます。