Inputs

When starting tasks through the Runway API, you’ll often need to provide assets like images. Some restrictions exist for what you can provide.

Assets can be provided via URLs or Data URIs.

URLs

In all cases, URLs must meet some basic minimum requirements:

1. All URLs must be HTTPS.
2. URLs must reference a domain name, not an IP address.
3. The server should respond with valid Content-Type and Content-Length headers.
4. Redirects are not followed. If the URL returns a 3XX response code, the request is considered failed.
5. The length of any single URL should not exceed 2048 characters.
6. The file size of the image asset that the URL points to should not exceed 16MB.

Additionally, the server responding to the request must support HTTP HEAD requests.

Content-Types

When specifying a URL, the Content-Type response header must be specified, and it must match the media type of your asset. File extensions in URLs are not considered. The Content-Types that are supported are listed below for the supported asset types.

Be aware that application/octet-stream and other generic values are explicitly not supported.

User agent

Runway will use a User-Agent header that starts with RunwayML API/ when making requests to your server. If you use a scraping-prevention tool or WAF, be sure to allowlist our user agent string prefix.

Data URIs (base64 encoded images)

A data URI allows you to pass the base64 encoded images as part of a request to our API, rather than passing a URL to the asset hosted on another server. This can reduce the complexity of your integration by eliminating an upload step.

Data URIs are supported anywhere URLs are expected. However, they come with some restrictions:

1. The length of the encoded data URI must be under 5MB (1024 × 1024 × 5 bytes). Keep in mind that base64-encoding your asset increases its size by about 33%: this means that you may not be able to use data URIs with assets larger than about 3.3MB. This limit supersedes type-specific file size limits.
2. The data URI must include an appropriate content type string. For instance, your data URI should start with something like data:image/jpg;base64,.

If a data URI is not base64 encoded, it may not be accepted.

Considerations

If you do not already have your asset stored in object storage, submitting your asset with a data URI can save you a step. Using a data URI may also help to reduce the latency of API calls.

However, the ~3MB limit may be too small for some assets, especially for video. If you cannot be sure that all assets are safely within the 5MB un-encoded size limit, you should upload assets to object storage instead. Uploaded assets (in other words, using a URL) have a limit of 16MB per image.

Type-specific requirements

Images

For fields that accept images, the asset referenced by the URL must use one of the following codecs, along with the corresponding Content-Type header:

Codec	Content-Type header
JPEG	image/jpg or image/jpeg
PNG	image/png
WebP	image/webp

All images are limited to 16MB.

Aspect ratios and auto-cropping

Gen-4 Turbo supports Landscape 1280:720 1584:672 1104:832, Portrait 720:1280 832:1104 and Square 960:960 outputs.

Gen-3 Alpha Turbo supports 1280:768 or 768:1280 outputs.

If your input asset is not exactly of the above listed ratios, the model will auto-crop your asset from the center to the aspect ratio parameter provided.