Ephemeral uploads

When providing files as inputs, there are size limits for assets provided by URL or data URI. URLs need to be downloaded and data URIs must be processed as part of the request body: both consume resources at the time a generation is started. To avoid these limits, you can upload ephemeral files to the Runway API using the uploads API.

Uploading files

You can upload a file to Runway by using our SDKs.

Node

You can pass Node fs streams or Files (or File-like objects) 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 files can be uploaded by passing them to the toFile hlper from @runwayml/sdk. Supported types include:

• Blob and Blob-like objects
• Buffer
• ArrayBuffer
• Typed arrays (e.g., Uint8Array)
• DataView
• Response and Response-like objects
• Any async iterator object that yields strings, Buffers, ArrayBuffers, ArrayBufferViews, Blob-like objects, or DataViews.

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')
    // You must pass a filename
    'file.mp4',
  ),
);
console.log(uri); // runway://...

Python

You can pass the following types to create_ephemeral:

• pathlib.Path object or an object that implements os.PathLike
• An IOBase object (e.g., BytesIO) with a name property containing the filename

from pathlib import Path

from runwayml import RunwayML
client = RunwayML()

my_file = Path('./path/to/file.mp4')
response = client.uploads.create_ephemeral(file=my_file)
print(response.uri)  # runway://...

If you do not have a Path or IOBase with a name, you can pass a two-tuple in the form (filename, content) where filename is the name of the file and content is one of:

• A file-like object (e.g., the output of open())
• bytes

from runwayml import RunwayML
client = RunwayML()

with open('./path/to/file.mp4') as my_file:
  response = client.uploads.create_ephemeral(
    file=('file.mp4', my_file),
  )
print(response.uri)  # runway://...

The resulting runway:// URI can be used anywhere that a URL or data URI can be used in the API.

Considerations

• runway:// URIs are only valid for 24 hours.
• The maximum uploadable file is 200MB. The minimum uploadable file is 512 bytes.
• You must have purchased credits to use this feature.
• There is a rate limit on the upload of ephemeral files.

Ephemeral uploads may be used multiple times, which can conserve bandwidth. If you intend to use a file multiple times, consider using ephemeral uploads. Be aware, though, that the URI will expire 24 hours after creation and the file must be re-uploaded.

Using ephemeral uploads without an SDK

Tip

See the API Reference for full details on using the /v1/uploads endpoint.

If you use our REST API directly, you can still use ephemeral uploads. By calling POST /v1/uploads with the following JSON body, you can start an upload:

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

• filename: A string containing the filename of the file you are uploading. The file extension must be representative of the file’s contents.
• type: Must be set to "ephemeral".

The server will respond with the following details:

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

The runwayUri value is the value that may be used when creating a new generation in the Runway API.

To upload the file to Runway’s servers, create a POST request to the URL at uploadUrl. Pass the fields in the dictionary fields as the multipart form-encoded POST body, and the contents of the file as as the file field.

Once the upload completes successfully, the runway:// URI is ready to use.

If the upload fails, do not retry. Instead, make a new request to /v1/uploads and start over. Be sure to follow our guidelines for handling errors to ensure your integration robustly handles different kinds of failure modes.