
Use the Imagild media API to discover a model, submit one image or video task, save its task ID, poll for completion, and download the result with authentication. The base URL is https://imagild.com/api/relay/v1. API access requires active membership as well as a valid API key; successful generation uses the same account points as the website.
This guide maps the complete integration. It uses raw HTTP because an Imagild task response is asynchronous; a familiar-looking model name does not establish compatibility with another vendor's SDK. Begin in the API console, then confirm current choices in the model hub.
Key Takeaways
- Save an operation identifier before submitting, and retain the returned task ID; neither a page refresh nor a local timeout should create a second generation.
- All three public image choices use 10 points at 1K, 15 at 2K, and 20 at 4K; membership eligibility is separate from purchasing points.
- HTTP acceptance, generation success, billing state, and authenticated file delivery are different checkpoints.
Establish the account and secret boundary
Create the API key in the authenticated console. Keys can be issued for 30 or 90 days, and an account can hold up to five active keys. Save the displayed secret in your server's secret store; subsequent handoff documents should identify its environment and owner without copying its value.
A points balance alone does not grant API access. A valid key also stops being sufficient when the account's membership expires. Check these independently before investigating model parameters.
The OWASP REST Security Cheat Sheet explains why authorization belongs at each protected endpoint and why credentials should stay out of URLs. In an Imagild integration, keep the Bearer key on your backend. Your web interface can call that backend using your application's own user authentication.
For shell examples, set the following through your existing secret-loading process. The key below is a variable name, not a value to publish:
IMAGILD_BASE='https://imagild.com/api/relay/v1'
# IMAGILD_API_KEY is supplied by your secret store.
These examples assume a POSIX shell, curl, and jq. They illustrate the current request contract rather than a paid generation benchmark.
Discover the current catalog
Request the authenticated catalog before enabling a model in your own interface:
curl --silent --show-error --fail-with-body "$IMAGILD_BASE/models" \
-H "Authorization: Bearer $IMAGILD_API_KEY"
The response wraps the catalog in data.models. Current image routing IDs are gpt-image-2.5, nano-banana-pro, and nano-banana-2.1. Similar variants such as Flare and Sunburst are not additional public choices.
| Task | Current choices | Parameters to confirm |
|---|---|---|
| Image generation | The three image IDs above | resolution: 1K, 2K, or 4K |
| Video generation | MiniMax-H3 | 768P or 2K; integer 4–15 seconds |
| Video shape | Listed by the video catalog | 16:9, 9:16, or 3:4 |
Treat the live catalog as a contract check rather than proof of equivalent quality between models. A resolution label is a request and pricing tier; inspect the dimensions and content of the returned file before promising a delivery specification.
Choose the endpoint by operation
Append one relative route to the base URL. The file API and generation API have different bodies.
| Method and relative route | Purpose | Result |
|---|---|---|
GET /models | Read available media models | JSON catalog |
POST /files | Upload a reference photo | HTTP 201 with data.file_id |
POST /images/generations | Submit an image task | HTTP 202 with data.id |
POST /videos/generations | Submit a video task | HTTP 202 with data.id |
GET /tasks/{id} | Read task and usage state | JSON task record |
GET /tasks/{id}/content | Download a successful result | Authenticated media bytes |
Do not append another /v1 or use the website's locale path. A request to /en/model-api opens a page; it is not the generation endpoint.
Submit one image and preserve its identity
A text-only image task does not require an uploaded picture. Provide a model ID, prompt, and supported resolution. Generation requests also require an Idempotency-Key: an 8–128-character operation identifier using letters, digits, or ._:-.
Choose the identifier once, persist it with your application record, and reuse it only for the same logical request and identical parsed parameters.
OPERATION_ID='catalog-cover-20261028-0001'
curl --silent --show-error --dump-header accepted.headers \
--output accepted.json --write-out '%{http_code}\n' \
"$IMAGILD_BASE/images/generations" \
-H "Authorization: Bearer $IMAGILD_API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $OPERATION_ID" \
--data '{"model":"gpt-image-2.5","prompt":"A blue paper boat on calm water, viewed from above","resolution":"1K"}'
Check that the HTTP status is 202 before extracting data.id. Store that ID alongside the operation identifier, requested model, resolution, and your own customer or project reference. A 202 response means the task was accepted; it does not mean that an image already exists.
When the same idempotency key is submitted with changed parameters, expect a conflict rather than a free revision. A deliberately different generation needs a new identifier and its own budget.
Add a reference only when the task needs one
Upload an authorized photo with multipart field photo:
curl --silent --show-error --fail-with-body "$IMAGILD_BASE/files" \
-H "Authorization: Bearer $IMAGILD_API_KEY" \
-F 'photo=@reference.jpg'
Use the returned data.file_id in a generation body. Alternatively, set image_task_id to a completed image task owned by the same account. Supply one reference selector, not both. An arbitrary external image_url is not part of this contract.
For referenced image generation, the prompt must contain at least 20 characters. Describe the intended change and the details you want to retain. The API attaches the reference; it does not guarantee perfect identity, exact lettering, or unchanged product details. The existing reference-scope guide helps distinguish borrowing an object from borrowing an entire scene.
Create a separate video task from an approved image
A completed image task can become a video reference without asking your application to invent a public image URL. Submit a new video operation with its own idempotency key:
{
"model": "MiniMax-H3",
"prompt": "The blue paper boat drifts slowly on calm water; the overhead camera remains steady",
"seconds": 4,
"resolution": "768P",
"aspect_ratio": "16:9",
"context_ir": false,
"image_role": "first_frame",
"image_task_id": "COMPLETED_IMAGE_TASK_UUID"
}
Send that body to /videos/generations, not the image endpoint. The UUID is a slot for a real completed task ID, not a literal usable identifier.
The API exposes individual 4–15-second video tasks. It does not expose the website's video-recreation workflow, director controls, or a one-call long-film assembly service. Plan a multi-stage application around separately approved outputs rather than describing every website feature as an API endpoint.
Poll the task, not the generation route
Read the saved task ID with authentication:
curl --silent --show-error --fail-with-body \
"$IMAGILD_BASE/tasks/$TASK_ID" \
-H "Authorization: Bearer $IMAGILD_API_KEY"
Inspect data.status, data.usage.state, and any data.error. Successful delivery is identified by succeeded; a task error can appear inside an otherwise successful HTTP status response. Checking only whether curl reached the server is insufficient.
The task record supplies poll_after_seconds, currently five seconds. Give polling a deadline in your application. Reaching that deadline should stop waiting and retain the task record; it should not automatically submit a new generation.
Current per-account limits distinguish writes from reads: ten generation or upload writes and 120 reads per minute. Multiple keys on the same account do not create separate quota pools. On HTTP 429, respect Retry-After and reduce demand.
Download and verify the media
Only fetch content after successful completion. The returned output_url is a private route, not an anonymous CDN link. Your download still needs a valid key and active membership.
curl --silent --show-error --fail-with-body \
--dump-header result.headers --output result.bin \
"$IMAGILD_BASE/tasks/$TASK_ID/content" \
-H "Authorization: Bearer $IMAGILD_API_KEY"
Check the response Content-Type and inspect the saved file before naming or publishing it. Image responses can use different image formats; calling a file result.png does not establish its encoding. For a browser interface, deliver the approved media through an authorized application route rather than putting a secret in an image URL. See the HTML-instead-of-image diagnostic if a saved download is actually a web page.
Connect the quote to the outcome
Image rates match the website: 1K costs 10, 2K costs 15, and 4K costs 20 points. At 768P, H3 uses 15 points per generated second; at 2K it uses 30. Enabling context_ir adds five points per video task. A four-second 768P video therefore uses 60 points before any separately generated reference image.
Submitted tasks retain their saved quote. Observe whether points are reserved, consumed, or released; confirmed failed generation releases its reservation. An unknown upstream outcome requires reconciliation and must not be treated as an immediate refund or an invitation to create another operation.
This explicit point schedule and shared website/API wallet make budgeting inspectable. They do not establish a lowest-price ranking or measured uptime promise. Use the points and job planning guide with the current pricing page when estimating a real workload.
Validate a complete integration
Before broad rollout, verify that your application can discover models, reject unsupported parameters locally, preserve one operation identity, resume a saved task, download authenticated bytes, and explain its billing state. Strict JSON input means extra fields such as image n, seed, or response_format are not harmless additions.
Keep logs of operation ID, task ID, status, and sanitized error request_id. Exclude prompts containing private material and exclude credentials by default. Replicate's token-security guidance is a useful independent reference for storing secrets in environment configuration and replacing exposed tokens; the precise Imagild routes, eligibility rules, and point rates remain those documented above.
Related tasks
- Imagild Points, Resolution and Jobs: Plan a Creation Before You Spend
- Should an AI Reference Replace an Object or Bring in the Whole Scene?
- Why Does My Downloaded Image Open as a Web Page?
Sources and scope
- Imagild API console and integration guide: Product entry point and current API access, credential and task integration instructions; detailed facts also cross-checked against the 2026-10-28 repository contract.
- Imagild model hub: Current public media model choices and resolution-based point prices; not evidence of model equivalence, pixel quality or measured uptime.
- OWASP REST Security Cheat Sheet: General REST security principles: endpoint authorization, secure handling of credentials, input validation and response content-type checks. Does not define Imagild product behavior.
- Replicate API token security: General guidance for separating credentials, storing them through environment configuration and revoking exposed tokens. No Replicate platform features or guarantees are attributed to Imagild.
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.