
Validate the video ratio before submitting a generation: the current accepted values are 16:9, 9:16 and 3:4. Do not send a free-form ratio, a pixel-size string, or an image model's parameter set to the video endpoint. Choose the composition for the destination first, then verify that the selected video model advertises it.
Key takeaways
- Video
aspect_ratiois an allowlisted string, not arbitrary width and height. - A CSS layout ratio changes a player box; it does not change generated media.
- A ratio change creates a different generation and needs a new operation ID.
Match the shot to its destination
A landscape page hero may suit 16:9, while a full-height mobile placement may suit 9:16. A portrait-oriented composition may instead use 3:4. These are layout decisions for the particular deliverable, not promises about a platform's current upload rules.
Identify the protected content before generating: a face, a product label, the space needed for a hand gesture, or a doorway the camera will reveal. Choosing an orientation without considering those elements can create an expensive clip that your application immediately crops incorrectly.
Validate against the current model entry
The model hub displays supported ratios. An authenticated GET /models returns the model contract your application can use to populate its options. Use the selected model's list rather than one global list copied from a different API.
This application-side JavaScript example validates a current catalog entry. It does not submit a generation:
function chooseVideoRatio(models, selectedId, requestedRatio) {
const model = models.find(item =>
item.id === selectedId && item.kind === "video"
);
if (!model || !model.available) {
throw new Error("The selected video model is unavailable");
}
if (!model.ratios.includes(requestedRatio)) {
throw new Error("Choose one of the advertised video ratios");
}
return requestedRatio;
}
Also validate on your server. Client checks improve feedback, but the API remains authoritative if its current contract differs from cached options. Model-specific validation is a general pattern described in Runware's schema documentation; its supported values must not be assumed to be Imagild's values.
Keep generated geometry separate from presentation
A player can look tall because its container is tall. That does not prove that the saved video has the requested orientation. MDN's CSS aspect-ratio reference concerns the ratio of an element's box, not regeneration of a media file.
When a generated clip appears cropped, compare the downloaded file with your website player before paying to generate it again. Inspect whether the player uses a fill or cover behavior that hides edges. If the saved file is correct and only the card is wrong, repair the presentation layer. The video poster versus first-frame guide helps separate another player appearance issue from the underlying clip.
Correct a rejected request deliberately
A value such as 1:1, 1920x1080, or 9 / 16 is not one of the current accepted API strings. Translate a user-facing label into an exact supported value before constructing JSON. Do not silently coerce every unsupported choice to landscape: tell the user which compositions are available.
Use the API console for the request structure and preserve a failed validation message for diagnosis. If you change the ratio and submit a new creative operation, use a new idempotency key. An identical retry of an already submitted operation retains its original key and parameters.
Approve the file in its actual crop
After the task succeeds, download it with authentication. Review the opening, peak action and final frame at the intended placement. A correct ratio can still contain badly framed motion or an unreadable product detail; passing schema validation is only the first check.
For references with uncertain attachment scope, use the reference attachment audit. Accept the deliverable only when the correct source, ratio and visible composition agree, and keep the saved request next to the result so later layout changes do not erase that evidence.
Related tasks
- Why Does a Video Card Show a Black Image Before Playback?
- After Reordering References, Does “Image 1” Still Point to the Right File?
Sources and scope
- Imagild API integration guide: Actual request structure, references, task lifecycle, access conditions and retry behavior.
- Imagild model hub: Current video tiers, ratios, duration bounds and points.
- CSS aspect-ratio: CSS controls element geometry, distinct from the actual generated media file.
- Runware model schemas: Model-specific parameter discovery and validation as a general integration pattern; no Imagild supported-value claim.
Product instructions were checked against the current Imagild API contract and the public model catalog. Code, budgets and acceptance checks are illustrative; this article does not claim a new paid generation test, an uptime measurement, a search-volume study or a ranking of AI citations.
Prepared by Imagild Editorial, the company editorial team responsible for these guides. AI assisted research and drafting. This is documentation-based guidance with proposed examples, not a claim of hands-on testing or an independent product review. Report a correction.
Cover: Original Imagild product screenshot captured on 28 October 2026; model availability and prices may change. This image is not an API response or a performance benchmark.