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.
Size limits
Section titled “Size limits”The size limits of inputs differ based on whether they are provided as a URL or as a data URI in the JSON request body.
| Input type | URL size limit | Data URI size limit |
|---|---|---|
| Image | 16MB | 5MB |
| Video | 32MB | 16MB |
| Audio | 32MB | 16MB |
Inputs using URLs
Section titled “Inputs using URLs”In all cases, URLs must meet some basic minimum requirements:
- All URLs must be HTTPS.
- URLs must reference a domain name in the hostname position, not an IP address.
- The server should respond with valid
Content-TypeandContent-Lengthheaders. - Redirects are not followed. If the URL returns a 3XX response code, the request is considered failed.
- The length of any single URL should not exceed
2048characters.
Additionally, the server responding to the request must support HTTP HEAD requests.
Content-Type values
Section titled “Content-Type values”When specifying a URL, the Content-Type response header must be returned, 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
Section titled “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.
Inputs using Data URIs (base64 encoded)
Section titled “Inputs using Data URIs (base64 encoded)”A data URI allows you to pass the base64 encoded assets 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, but it also has a lower limit on the size of the assets that can be provided.
Data URIs are accepted in any field where a URL is accepted unless otherwise specified.
- An appropriate content type must be
specified in the data URI. For instance, your data URI for a JPEG should start with
something like
data:image/jpg;base64,. - Data URIs must use the base64 extension. The expected format is
data:content/type;base64,. - The size limit for your data URI (specified above) is the limit for the encoded data URI. Keep in mind that base64-encoding your asset increases its size by about 33%: to fit an image within the 5MB limit, the binary file must be 3.3MB or less.
Data URIs that do not follow these rules may be rejected with a 400 Bad Request error.
Considerations of URLs versus data URIs
Section titled “Considerations of URLs versus data URIs”If you do not already have your asset stored in object storage, submitting your asset with a data URI can save you a step. However, the data URI size limit may be too small for some assets. If you cannot be sure that all assets are safely within the un-encoded size limit, you should upload assets to object storage instead.
Submitting a request with data URIs instead of URLs will change the performance characteristics of your integration. Data URIs are part of the request payload, and thus cause your HTTP requests to take longer to submit: all data must be sent serially to our servers. Because the request body JSON must be processed before the assets can be extracted from their data URIs, this may increase the latency of our server responses.
URLs, on the other hand, can be immediately processed in parallel. This means the time between submitting your HTTP request and the start of processing is likely much lower. However, latency between our servers and the server hosting your assets may increase the total request time. Using a CDN or object storage service will help to minimize this cost.
Type-specific requirements
Section titled “Type-specific requirements”Images
Section titled “Images”For fields that accept images, the asset must use one of the following
encodings, along with the corresponding Content-Type header:
| Codec | Content-Type header |
|---|---|
| JPEG | image/jpg or image/jpeg |
| PNG | image/png |
| WebP | image/webp |
GIF images are not supported.
Videos
Section titled “Videos”For fields that accept videos, the asset must use one of the following
codecs, along with the corresponding Content-Type header:
| Container format | Usual file extension | Expected content type | Supported codecs |
|---|---|---|---|
| MP4 | .mp4 | video/mp4 | H.264, H.265/HEVC, AV1 |
| QuickTime | .mov | video/quicktime | H.264, H.265/HEVC, Apple ProRes (422 Proxy, 422 LT, 422, 422 HQ, 4444, 4444 XQ) |
| Matroska | .mkv | video/x-matroska | H.264, H.265/HEVC, VP8, VP9, AV1 |
| WebM | .webm | video/webm | VP8, VP9, AV1 |
| 3GPP | .3gp | video/3gpp | H.264 |
| Ogg | .ogv | video/ogg | Theora |
The following formats are supported but discouraged due to quality, performance, industry support, and file size:
| Container format | Usual file extension | Expected content type | Supported codecs |
|---|---|---|---|
| QuickTime | .mov | video/quicktime | MJPEG |
| Matroska | .mkv | video/x-matroska | MPEG2 (H.262) |
| AVI | .avi | video/x-msvideo | H.264, MJPEG, MSMPEG4v3 |
| Flash Video | .flv | video/x-flv | FLV1, H.264 |
| MPEG | .mpg, .mpeg | video/mpeg | MPEG2 (H.262) |
Note that file extension is not considered by the API. Use this value for reference only.
- H.264 / AVC - Most widely supported modern codec
- H.265 / HEVC - High efficiency successor to H.264
- AV1 - Royalty-free, modern codec
- VP8 / VP9 - Google’s codecs, primarily for WebM
- Apple ProRes - Professional editing codec (422 Proxy, 422 LT, 422, 422 HQ, 4444, 4444 XQ)
- MPEG2 (H.262) - Legacy codec for DVDs and broadcasts (discouraged)
- MJPEG - Motion JPEG, frame-by-frame compression (discouraged)
- Theora - Open codec for Ogg containers
- FLV1 - Legacy Flash Video codec (discouraged)
- MSMPEG4v3 - Legacy Microsoft codec (discouraged)
For fields that accept audio, the asset must use one of the following
codecs, along with the corresponding Content-Type header:
| Container format | Usual file extension | Content type | Supported codecs |
|---|---|---|---|
| MP3 | .mp3 | audio/mpeg, audio/mp3 | MP3 (MPEG-1/2 Layer 3) |
| WAV | .wav | audio/wav, audio/wave, audio/x-wav | PCM (uncompressed) |
| FLAC | .flac | audio/flac, audio/x-flac | FLAC (lossless) |
| M4A | .m4a | audio/mp4, audio/x-m4a | AAC, ALAC |
| AAC | .aac | audio/aac, audio/x-aac | AAC (raw) |
- MP3 (MPEG-1/2 Layer 3) - Universal compatibility, lossy compression
- AAC (Advanced Audio Coding) - Modern lossy codec, better quality than MP3 at same bitrate
- FLAC (Free Lossless Audio Codec) - Lossless compression, popular for archival
- PCM (Pulse Code Modulation) - Uncompressed audio, typically in WAV containers
- ALAC (Apple Lossless Audio Codec) - Apple’s lossless codec, typically in M4A containers
Aspect ratios and auto-cropping of inputs
Section titled “Aspect ratios and auto-cropping of inputs”Video inputs
Section titled “Video inputs”When using video models, be aware of the supported ratio parameters, which configures the dimensions of the output files.
Examples:
- Gen-4 Turbo and Act-Two support Landscape
1280:7201584:6721104:832, Portrait720:1280832:1104and Square960:960outputs. - Gen-4 Aleph supports Landscape
1280:7201584:6721104:832848:480, Portrait720:1280832:1104480:848and Square960:960outputs. - Gen-3 Alpha Turbo supports
1280:768or768:1280outputs.
If your input asset is not exactly of the ratio you specify, the model will auto-crop your asset from the center to the aspect ratio parameter provided.
Third party models (e.g., veo3.1, veo3.1_fast, veo3, etc.) may crop or resize inputs in other ways.
Image references
Section titled “Image references”Image references may be resized if they are too large or small to be provided to the model you choose. It is not recommended to provide reference images smaller than 640×640px or larger than 4K.