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:
- All URLs must be HTTPS.
- URLs must reference a domain name, not an IP address.
- The server should respond with valid
Content-Type
andContent-Length
headers. - Redirects are not followed. If the URL returns a 3XX response code, the request is considered failed.
Additionally, the server responding to the request must support HTTP HEAD
requests.
Content-Type
s
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-Type
s 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:
- 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.
- 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 usehttp://
or other schemes, likeftp://
. - 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 to11.22.33.44
). Be sure to set up HTTPS on the host for that record. - 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). - 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 theContent-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 theContent-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
.
You’ll receive output that looks like this:
- Your server should be returning a
200
status code. - Be sure you’re returning an acceptable
Content-Type
. - A
Content-Length
should be provided with an accurate file size.