
For a first Imagild image request, submit one small 1K task with curl, keep the response in a file, and poll the returned task ID before downloading media. Use an account with active API membership and sufficient points: this is a real generation request costing 10 points at the current 1K rate, not a free connection test. Use GET /models first if you only need to check access.
Key Takeaways
- Keep your operation identifier unchanged when retrying the same request.
- Require HTTP 202 before reading
data.id; poll status separately from submission. - Download to a binary file only after
succeeded, then check its Content-Type.
Prepare a private working directory
The following example assumes a POSIX shell with curl and jq. The API key comes from your secret-loading process. Avoid putting its literal value in a shared script, shell recording, or support screenshot. OWASP's REST security guidance supports using headers rather than credential-bearing URLs.
Open the API console to create your key and review current membership. Set the base once:
umask 077
BASE='https://imagild.com/api/relay/v1'
OPERATION_ID='first-image-curl-20261028-0001'
printf '%s\n' "$OPERATION_ID" > operation-id.txt
Use a different operation identifier for an intentionally different image. For a retry of this exact example, reuse the saved identifier and unchanged JSON.
Submit and inspect acceptance
Create a request file so that editing a shell command cannot quietly change retry parameters:
cat > request.json <<'JSON'
{"model":"gpt-image-2.5","prompt":"A blue paper boat on calm water, seen from directly above","resolution":"1K"}
JSON
HTTP_STATUS=$(curl --silent --show-error \
--output accepted.json --dump-header accepted.headers \
--write-out '%{http_code}' \
"$BASE/images/generations" \
-H "Authorization: Bearer $IMAGILD_API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $OPERATION_ID" \
--data-binary @request.json)
test "$HTTP_STATUS" = '202' || exit 1
TASK_ID=$(jq -er '.data.id' accepted.json) || exit 1
printf '%s\n' "$TASK_ID" > task-id.txt
If the status is not 202, inspect the sanitized error and headers before doing anything else. A 401 is not fixed by changing the prompt. A membership-related 403 is not fixed by buying points alone. For a network interruption after submission, preserve the same operation identity rather than assuming nothing happened.
Poll with a bounded wait
The next loop uses a two-minute local waiting budget and checks the task about every five seconds. It requires a date utility supporting +%s. Each network transfer is limited to the remaining budget; that client choice is not a promised generation time. Keep the system clock stable while this shell example runs.
DONE=false
DEADLINE=$(( $(date +%s) + 120 ))
while :; do
REMAINING=$(( DEADLINE - $(date +%s) ))
[ "$REMAINING" -gt 0 ] || break
curl --silent --show-error --fail-with-body \
--connect-timeout 10 --max-time "$REMAINING" \
"$BASE/tasks/$TASK_ID" \
-H "Authorization: Bearer $IMAGILD_API_KEY" > task.json || exit 4
STATE=$(jq -er '.data.status' task.json) || exit 4
case "$STATE" in
succeeded) DONE=true; break ;;
failed|unknown) exit 2 ;;
esac
REMAINING=$(( DEADLINE - $(date +%s) ))
[ "$REMAINING" -gt 0 ] || break
PAUSE=5
[ "$REMAINING" -ge "$PAUSE" ] || PAUSE=$REMAINING
sleep "$PAUSE"
done
test "$DONE" = true || exit 3
If the wait ends, keep task-id.txt and resume reading that task later. Do not rerun submission under a fresh identifier just to get a faster result. A failed or unknown task needs the next action appropriate to that outcome; the failed-job guide explains why repeated generation is a poor diagnostic.
Download and verify the result
curl --silent --show-error --fail-with-body \
--dump-header result.headers --output result.bin \
"$BASE/tasks/$TASK_ID/content" \
-H "Authorization: Bearer $IMAGILD_API_KEY"
jq '.data.usage' task.json
Keep the generic filename until you have checked the response Content-Type and opened the file with an appropriate viewer. PNG, JPEG, and WebP are possible image formats; a chosen filename is not evidence of encoding.
Your acceptance check is now concrete: one saved operation, one task ID, succeeded, a consumed 10-point quote, and valid media bytes. Check the HTML download diagnostic if the file instead contains a page. Larger tiers remain available in the model hub: 2K is 15 points and 4K is 20, so change the resolution only for a deliberately new, separately budgeted operation.
Related tasks
- What Should You Check Before Retrying a Failed Image or Video Job?
- 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.
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.