Ephemeral uploads

You upload a file, get a runway:// URI back, and use it anywhere a URL or data URI is accepted.

Uploading with an SDK#

Pass a Node fs stream, or a File-like object, to createEphemeral:

import * as fs from 'node:fs';
import RunwayML from '@runwayml/sdk';
 
const client = new RunwayML();
 
const myFile = fs.createReadStream('./path/to/file.mp4');
const { uri } = await client.uploads.createEphemeral(myFile);
 
console.log(uri); // runway://...

Other types go through the toFile helper. A filename is required:

import * as fs from 'node:fs/promises';
import RunwayML, { toFile } from '@runwayml/sdk';
 
const client = new RunwayML();
 
const { uri } = await client.uploads.createEphemeral(
  toFile(
    await fs.readFile('./path/to/file.mp4'),
    'file.mp4',
  ),
);

toFile accepts Blobs and Blob-like objects, Buffer, ArrayBuffer, typed arrays such as Uint8Array, DataView, Response and Response-like objects, and any async iterator yielding those types.

The resulting URI drops straight into a generation:

const task = await client.imageToVideo
  .create({
    model: 'gen4.5',
    promptImage: uri, // runway://...
    promptText: 'A timelapse on a sunny day',
    ratio: '1280:720',
    duration: 5,
  })
  .waitForTaskOutput();

Constraints#

• URIs are valid for 24 hours from creation. After that, re-upload.
• Maximum file size 200MB; minimum 512 bytes.
• You must have purchased credits to use the feature.
• Uploads are rate limited.

A URI can be reused across multiple generations within its 24-hour window, which saves bandwidth when the same asset feeds several requests. If you know a file will be used repeatedly, upload it once rather than passing it inline each time.

Uploading without an SDK#

Start the upload with POST /v1/uploads:

{
  "filename": "filename.mp4",
  "type": "ephemeral"
}

filename must carry an extension representative of the file's contents. type must be "ephemeral".

The response:

{
  "uploadUrl": "https://...",
  "fields": { },
  "runwayUri": "runway://..."
}

POST to uploadUrl as multipart form data: send every key in fields as a form field, and the file contents as the file field. Once the upload succeeds, runwayUri is ready to use in a generation.

If the upload fails, do not retry it. Make a fresh POST /v1/uploads request and start over. See HTTP errors for handling the failure modes robustly.

Related#

• Inputs — size limits, codecs and the URL/data URI comparison
• Outputs — result URLs expire too
• Tasks and uploads — full /v1/uploads endpoint details