The Constraint Table
- →Choose legal resolution, duration, and ratio values for each generation mode
- →Validate input assets against dimension, aspect, format, size, and count limits before submitting
- →Apply the aggregate caps: 12 input files, 64 MB body, 7000-character prompt, 7-day task retention
Why this lesson exists
Every failed H3 request costs you a round trip and, in a pipeline, an on-call ping. Nearly every failure at creation time is a constraint violation — and the constraints are fully documented, just scattered and (in most guides) incomplete. This lesson is the complete, verified rulebook. Bookmark it; the labs in the paid core assume it.
Output: resolution, duration, ratio
Resolution is 768P or 2K for generation. (Regeneration — the mastering step in the core track — currently supports only 2K as its target.)
Duration is an integer from 4 to 15 seconds inclusive. The enum literally lists 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 — no fractions, nothing shorter, nothing longer.
Ratio is where guides get sloppy, so here is the exact rule set.
The legal ratio enum has exactly seven values: adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16. Most circulating guides give a partial list — typically "16:9, 9:16, 4:3, 1:1" — and omit 21:9 and 3:4 entirely. If you rejected a cinematic 21:9 spot because a blog told you the API could not do it, this is why we verify.
The rule differs by mode:
| Mode | Ratio rule |
|---|---|
| Text-to-video (t2va) | Required. Cannot be adaptive. One of the six concrete values. |
| Image-to-video (i2va) | Always `adaptive`, derived from the input image. Passing another value is not an error — it is silently ignored. |
| Reference (r2va) | Optional. Defaults to `adaptive`; any of the six concrete values may be set explicitly. |
The i2va behavior deserves a second look because it fails silently: you can pass ratio: "1:1" with a widescreen first frame and get a widescreen video with no warning. If your product promises a specific output ratio, enforce it on the input image, not the request field.
Input assets: the master table
| Asset | Count | Dimensions / duration | Aspect ratio | Format | Size |
|---|---|---|---|---|---|
| First/last-frame images | 0, 1, or 2 (at most 1 first + 1 last) | 256-5760 px per side | 2:5 to 5:2 | JPG, JPEG, PNG, WEBP, HEIC, HEIF | up to 30 MB per file |
| Reference images | up to 9 | 256-5760 px per side | 2:5 to 5:2 | same image formats | up to 30 MB per file |
| Reference videos | up to 3 clips | 2-15 s per clip; 15 s total; 256-5760 px per side | 2:5 to 5:2 | container MP4 or MOV; codec H.264/AVC or H.265/HEVC; in-clip audio AAC or MP3 | up to 50 MB per file |
| Reference audio | up to 3 clips | 2-15 s per clip; 15 s total | — | WAV, MP3 | up to 15 MB per file |
Read the aspect column as a range: anything from 2:5 (very tall) to 5:2 (very wide), i.e. a width/height ratio in [0.4, 2.5]. A panoramic strip or a skyscraper crop fails before generation starts.
Guides list the supported video codecs (H.264, H.265) and stop there. The container is also constrained: reference clips must be MP4 (.mp4) or MOV (.mov). A perfectly encoded H.264 stream inside an .mkv or .avi fails validation even though the codec matches every list you have read.
Reference video frame rate must fall in [23.976, 60] fps — a documented constraint absent from every circulating write-up. A 20 fps screen recording or a 120 fps slow-motion phone clip fails on frame rate alone.
Two rules sit on top of the table. Reference audio can never be the sole input — it must accompany an image or a video. And the counts above live under an aggregate cap of 12 files total across all types in one request: nine reference images plus three clips is legal; try to add audio on top and you are over.
Size limits apply per asset, not in aggregate — the docs say so explicitly. Nine 30 MB images is legal on the per-file rule; what catches you instead is the request body cap of 64 MB, which is exactly why the docs strongly recommend URL input over Base64. Pass URLs and your body stays tiny regardless of asset weight.
The prompt and the request
The text prompt is required in every mode and caps at 7000 characters — roomy enough for the structured multi-shot prompts you will write in the core track, but a real limit for programmatically assembled prompts.
And a pleasant default worth knowing: with no image, video, or audio input at all, the request automatically becomes text-to-video. There is no mode flag to set — the content you include is the mode selection. (What happens when you mix content types incorrectly — specifically frame roles with reference roles — is a 400-level trap with its own correction in lesson h3-c1.)
One constraint on the far side: retention
Tasks are queryable and listable for 7 days. That number bounds more than your download window: the regeneration pipeline in the core track can reference a source task by ID only while that task still exists. If your workflow drafts at 768P this week and masters at 2K "sometime later," 7 days is the deadline hidden in that sentence.
Foundation complete
You now know what H3 is (h3-f1), what it costs and how it limits you (h3-f2), how to run the create-poll-collect loop (h3-f3), and every documented input rule (this lesson). That is a working practitioner's baseline. The paid core teaches the role system that unlocks image and reference modes, the camera and prompt grammar the model was actually trained on, native dialogue, Context-IR, the 2K pipeline, production operations, and the open weights — and the capstone certifies all of it.
Run the validator by hand
0 / 6 stepsYour verdicts: 1 rejected (duration must be an integer, 4-15); 2 accepted but the ratio is silently ignored — image-to-video output is always adaptive, derived from the input image; 3 rejected (container must be MP4 or MOV, even though H.264 is a supported codec); 4 rejected (reference images cap at 9); 5 rejected (reference audio cannot be the sole input — it must accompany an image or video); 6 accepted (21:9 is in the legal ratio enum, though most partial lists omit it).
Knowledge check
3 questionsPick an answer to see why it is right or wrong — including the wrong ones.
Which of these is the complete set of concrete ratio values a text-to-video request may use?
You send an image-to-video request (first-frame image attached) with ratio set to 1:1, but the image is 16:9. What happens?
Which of these reference-video inputs passes validation?