
Choose first_frame when the reference defines the intended opening composition. Choose reference_image when the photo is visual guidance for the shot rather than the opening arrangement you are asking to animate. In either case, inspect the result: choosing a role does not guarantee identity, exact geometry or continuity.
Key takeaways
image_roledescribes how an attached image should contribute to the video request.- The supported values are
first_frameandreference_image; the default isfirst_frame. - A deliberate comparison uses separate task IDs and budgets, not two requests disguised as retries.
Start with the creative decision
Ask whether the first visible moment must resemble an approved still. A photo of a person beside a window can define an opening scene: the person then turns and the camera moves closer. That is a reasonable brief for first_frame.
A different brief may use the person and outfit as guidance while asking for a newly composed scene. reference_image expresses that reference intent. It does not promise that every detail survives or that a change of scene will be physically consistent. Use the reference-scope decision guide to separate borrowing a subject from preserving the entire photographed setting.
Change the role without confusing the reference selector
The source selector and the role are different fields. file_id chooses an uploaded, owned image. image_task_id chooses a completed, owned image-generation task. Send one selector, then specify its role.
These fragments illustrate an intentional role comparison using the same uploaded asset. Add the other required video fields when constructing each request:
[
{"file_id":"RETURNED_FILE_ID","image_role":"first_frame"},
{"file_id":"RETURNED_FILE_ID","image_role":"reference_image"}
]
The array is a planning comparison, not a valid bulk-generation payload. Submit each complete video request separately. Do not send arbitrary role strings, an external image_url, or both selectors. The API integration guide is the product contract to follow; another provider's parameter names are not interchangeable.
Describe the action that follows the picture
For an opening-frame brief, describe what changes from that initial view. Keep the requested movement compatible with the visible pose and space. A camera move through an obstructing wall is a different problem from a valid image attachment.
For a reference-image brief, identify the visible traits that matter and describe the target scene. Avoid contradictory directions such as demanding both an identical original background and an entirely different location. The positive video prompt guide helps turn broad exclusions into visible actions.
These are creative review methods, not claims about a measured advantage for one role. Provider outputs can vary between requests, even when much of the input remains the same.
Budget a comparison as two generations
At current rates, two four-second 768P clips cost 120 points with enhancement disabled. A previously generated image retains its own original cost. If you change the role to create the second clip, use a new Idempotency-Key, because the parameters and intended operation have changed.
By contrast, retrying the same role and identical body after a network interruption uses its original key. Keep role, prompt, source selector and task ID together in your application record. The model hub shows the current video options and rates, while active membership remains a separate access condition.
Evaluate the opening and the full motion
Review each accepted result against a small scorecard: opening composition, preserved subject traits, requested action, camera behavior and visible artifacts. Pause later in the clip as well as at the start. Record concrete differences rather than declaring a role universally better after one pair of outputs.
As model-specific schema documentation illustrates in another API, input capabilities belong to a particular model contract; it does not document these Imagild roles. If the reference cannot be resolved, repair ownership or source availability before making another creative comparison. If it resolves but the motion is wrong, revise the shot brief as a new operation and review that new result independently.
Related tasks
- Should an AI Reference Replace an Object or Bring in the Whole Scene?
- Why Does Adding “Do Not” Make My AI Video Less Predictable?
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.
- Runware model schemas: General importance of model-specific input contracts, not Imagild role semantics.
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.