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.

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 2.2MB un-encoded size limit, you should upload assets to object storage instead.

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-3 Alpha Turbo returns either 1280x768 or 768x1280 outputs. If your input asset is not exactly of this ratio, the model will auto-crop your asset from the center to the aspect ratio parameter provided.

Troubleshooting assets

When submitting an asset, the API may return a 400 Bad Request response if the asset cannot be used. If you’re using SDKs, a BadRequestError will be thrown in Node or raised in Python.

The message in the error response body will include two pieces of pertinent information: the field that the error occurred for (e.g., promptImage) and the reason for the failure.

Common error reasons

Invalid data URI.

The provided data URI is malformed and could not be parsed. Be sure you're using a library to encode the URI.

Unsupported asset type. Data URIs must include the content type of the value they encode.

Your data URI specifies a media type that's not supported. See the list of supported media types above.

Invalid URL

You provided a URL that is non-standard and cannot be parsed.

Only HTTPS URLs are allowed.

All URLs must start with https://. You cannot use http:// or other schemes, like ftp://.

URLs must be hosted on a domain.

You cannot provide a URL that points to an IP address. For instance, https://11.22.33.44/foo/bar would be rejected. You can instead create an A or AAAA record for your domain that points at the IP address of your host (in the example here, an A record pointing to 11.22.33.44). Be sure to set up HTTPS on the host for that record.

Failed to fetch asset. The URL may be incorrect or the server hosting the asset may be down.

When we attempted to fetch the asset, we encountered a non-HTTP connection issue. This might be a DNS issue, TCP connection issue, TLS problem, protocol error, or an unexpectedly closed connection. Check that the URL is working and that connections are not being rejected.

Failed to fetch asset. Received HTTP response code "..."

When we attempted to fetch the asset, we did not get a 200 status code. The resposne code that we received is provided in the reason. Be aware that we do not follow redirects (via the Location HTTP response header).

Timeout while fetching asset.

It took longer than ten seconds to download the provided asset.

Assets must use an approved Content-Type response header. We received application/octet-stream, which is not allowed.

Your server returned application/octet-stream for the Content-Type HTTP response header. This is not allowed. See the list of supported media types above.

Unsupported Content-Type response header: "...".

Your server returned an unsupported value for the Content-Type HTTP response header, which is noted in the response. See the list of supported media types above.

Content-Length not provided

Your server did not specify a Content-Length HTTP response header. Lengths must be provided; we do not support streaming responses of unknown length.

Asset size exceeds XX.XMB.

Your server specified a Content-Length HTTP response header that exceeds the maximum size for the asset type. This error may also be returned if the number of bytes returned by the server does not match the number specified in the Content-Length response header. The maximum size is specified in the reason and in the documentation above.

Asset size exceeds XX.XMB.

Your server specified a Content-Length HTTP response header that exceeds the maximum size for the asset type. The maximum size is specified in the reason.

Invalid asset dimensions. Height and width must not exceed 8000px. Got XXxYY.

The provided asset is larger than 8000px on one of its sides. Assets must be less than 8000px on either side.

Invalid asset aspect ratio. width / height ratio must be between XX and YY. Got ZZ.

The aspect ratio (the asset width divided by the asset height) must be between the values XX and YY. The computed aspect ratio is included in the reason as ZZ.

Debugging failures

You can investigate the cause(s) for many common failures by simulating our request for your asset. To do this, we’ll run a cURL command against the URL you’ll specify for your asset. For this example, we’ll use the asset URL https://example.com/assets/image.jpg.

curl "https://example.com/assets/image.jpg" \
   -I \
   -H "User-Agent: RunwayML API/1.0"

You’ll receive output that looks like this:

% curl "https://example.com/assets/image.jpg" \
   -I \
   -H "User-Agent: RunwayML API/1.0"
HTTP/2 200
content-type: image/jpg
content-length: 123456
vary: Accept-Encoding
cache-control: max-age=14400
accept-ranges: bytes
alt-svc: h3=":443"; ma=86400

1. Your server should be returning a 200 status code.
2. Be sure you’re returning an acceptable Content-Type.
3. A Content-Length should be provided with an accurate file size.