Requesting a video resolution and verifying the delivered dimensions are separate steps. Choose an output preference for ingestion, then inspect the file against your application's requirements. A filename ending in .mp4 does not tell you its dimensions or video codec.
This guide shows how to inspect a downloaded file with ffprobe and apply a small application-side dimension check. It is useful when an editor, preview service or analysis pipeline requires a particular frame size.
Understand what the resolution option selects
Tornado API's max_resolution is a source-format preference. The current create-job reference describes numeric values as selecting the highest available resolution at or below the requested value. If all available formats exceed it, selection falls back to the smallest available format rather than resizing the video. Resolution is classified using the shorter dimension, including for vertical videos.
That fallback matters when a downstream service has a strict limit. Do not treat the request option as an application-side validator. Inspect the delivered file before passing it on. Asking for a larger resolution also does not recover image detail absent from the source.
Start with the Python ingestion tutorial if you need the submit-and-poll flow. Keep the original job ID, requested options and observed output together so you can explain a mismatch later.
Inspect the local file
Install FFmpeg, which includes ffprobe, from a trusted distribution for your system. After downloading a result through your authorized access path, run this command against the local file:
ffprobe -v error -select_streams v:0 \
-show_entries stream=codec_name,width,height,sample_aspect_ratio,display_aspect_ratio \
-of json delivered.mp4
The command selects the first video stream and writes selected metadata as JSON. The ffprobe documentation explains stream selection, entry selection and output writers. This reads metadata; it does not resize or re-encode the file.
For a locally generated 640-by-360 test clip, the relevant stream fields were:
{
"codec_name": "mpeg4",
"width": 640,
"height": 360,
"sample_aspect_ratio": "1:1",
"display_aspect_ratio": "16:9"
}
This is a synthetic local fixture, not a Tornado API result or a claim about the codec your jobs will return. The complete ffprobe result wraps these fields in a streams array and may include additional sections.
Check your consumer's actual requirement
A service might accept any frame up to a bounding box, require one exact width and height, or reject particular codecs. Write that requirement explicitly instead of using a label such as “HD” as the entire validation rule.
Here is a deliberately narrow check for consumers that require exact coded dimensions. Save the command's JSON output as probe.json, then pass its parsed object to this function:
import json
def check_dimensions(probe, required_width, required_height):
streams = probe.get("streams", [])
if not streams:
return "no_video_stream"
video = streams[0]
width, height = video.get("width"), video.get("height")
if not isinstance(width, int) or not isinstance(height, int):
return "unknown_dimensions"
if width <= 0 or height <= 0:
return "unknown_dimensions"
if (width, height) == (required_width, required_height):
return "dimensions_match"
return "dimensions_mismatch"
with open("probe.json", encoding="utf-8") as file:
probe = json.load(file)
print(check_dimensions(probe, 640, 360))
The local fixture returns dimensions_match. The same file checked against 1280 by 720 returns dimensions_mismatch; an empty stream list returns no_video_stream. These checks were exercised locally. They do not validate a live media job or prove a downstream service will accept the file.
Coded dimensions are only one property. Rotation metadata and non-square pixels can affect how an image is displayed. This example does not normalize either, select among multiple video tracks, inspect audio, check duration or test decoding. Extend validation according to the consumer's documented contract, and test playback or processing with that consumer.
Decide what to do with a mismatch
If the consumer accepts the original dimensions, preserve them and record what was delivered. If it needs exact dimensions, add a separate, explicit transformation step under your application's control. Decide whether to fit, crop or pad the image based on the intended display. Avoid silently stretching it to fill a different aspect ratio.
If you suspect a selection issue, compare the saved request with the actual file and the current API reference. Changing the request repeatedly without inspecting the result makes the cause harder to identify. Keep the first successful file while you investigate.
A smaller delivered file also does not by itself establish a smaller bill. Review the usage guide and your account's usage records separately from output dimensions.
Keep access failures separate from format failures
If the file cannot be downloaded, resolve that before diagnosing resolution. The expired-link troubleshooting guide separates temporary access problems from missing objects. If the file is readable but rejected by the consumer, retain the inspection result and record that downstream rejection as its own stage.
Open the dashboard and test one authorized source through your intended workflow. Inspect the delivered dimensions, try the actual consumer, and only then expand to a representative set of horizontal and vertical sources.