
Use a text prompt with POST /videos/generations, save the returned task ID, and wait for data.status to become succeeded before downloading the clip. The current model ID is MiniMax-H3; each request describes a 4–15 second clip rather than an entire film.
Key takeaways
- Choose an advertised duration, resolution and aspect ratio before sending a paid request.
- HTTP 202 means the request was accepted; it does not mean a playable video exists yet.
- Keep the same operation identity when retrying the same submission, and authenticate the result download.
Define one shot the model can complete
Start with a short visual event: a paper boat passes a stone, a cup releases steam, or a camera reveals a doorway. Describe the subject, action and camera behavior in ordinary language. Keep unrelated events for another clip. This is a planning technique, not a guarantee that every generated movement will match the brief.
Read the current model hub before hard-coding options. The published video contract currently offers 768P or 2K, ratios 16:9, 9:16 or 3:4, and integer durations from 4 through 15 seconds. Image resolution values such as 4K are not valid video values.
Send an explicit first request
This Bash example requires a server-side IMAGILD_API_KEY belonging to an active member. Replace the operation ID for a genuinely new generation. Retain it, together with the exact request, if this particular submission needs a retry.
curl 'https://imagild.com/api/relay/v1/videos/generations' \
-H "Authorization: Bearer $IMAGILD_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: boat-shot-operation-0001' \
-d '{"model":"MiniMax-H3","prompt":"A blue paper boat drifts past a mossy stone on calm water. The camera tracks gently beside it.","seconds":4,"resolution":"768P","aspect_ratio":"16:9","context_ir":false}'
Do not add image_task_id when no image is involved. This request uses text alone. Do not add a caller-defined price, seed, webhook URL or synchronous response format: those are not accepted fields in this API.
Treat acceptance and completion separately
A successful submission returns HTTP 202 and a task in the data envelope. Persist data.id in your application's record for this shot. As MDN explains for HTTP 202, acceptance does not establish eventual completion.
Query GET /tasks/{id} with the same Bearer authentication, normally every five seconds. Render an honest pending state in your application. Only enable the download action after data.status is succeeded and output_url is present. A response can be HTTP 200 while its task is failed, so testing only the HTTP status is insufficient.
Understand the budget before retrying
At current rates, four seconds at 768P costs 60 points; the same duration at 2K costs 120. Setting context_ir to true adds five points to that task. These are generation costs, not promises about the finished clip's usable duration.
The API uses the same account points wallet as the website. Active membership is a separate requirement: purchasing a points pack or receiving welcome points does not, by itself, unlock API access. Check the API console and points plans for current access and pricing information.
If the HTTP request fails ambiguously, retry the identical operation with its original Idempotency-Key. If a task reports unknown, preserve the task and seek reconciliation instead of creating another paid generation. For general diagnosis, use the failed-job next-action guide.
Accept the delivered clip, not just the response
Download GET /tasks/{id}/content using authentication. Open the saved file and check its duration, orientation, complete playback and requested action. Review audio as well as the first frame; a thumbnail cannot establish that a clip is ready.
Pass the shot only when it communicates the intended event at its delivery size. If movement is wrong, revise the brief as a new operation rather than repeatedly resubmitting unchanged instructions. The already-moving first-frame guide helps distinguish a prompt problem from a clip that simply needs a different edit point.
Related tasks
- What Should You Check Before Retrying a Failed Image or Video Job?
- How Can My AI Clip Start in Motion Instead of Spending Seconds Accelerating?
Sources and scope
- Imagild API integration guide: Actual asynchronous request fields, reference selectors, access conditions, retries and result download.
- Imagild model hub: Current H3 model ID, duration, resolution, ratios and displayed points.
- HTTP 202 Accepted: General meaning of acceptance versus eventual completion; not a guarantee of Imagild task success.
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.