
Submit paid media work from a Next.js server boundary that authenticates your user, persists a stable operation and returns a local operation ID. Let a durable worker submit the saved request to Imagild and reconcile its task later. Do not hold the browser's request open until an image or video finishes.
The Imagild API console describes asynchronous generation: acceptance returns HTTP 202 with data.id. Your own operation ID exists earlier and remains useful even if a provider response is lost.
Key Takeaways
- Keep the Imagild Bearer key on the server and outside public environment variables.
- Persist approved intent and an outbox event before returning acceptance to your browser.
- Treat your application operation and the eventual Imagild task as separate identifiers.
Use the current Route Handler convention
This guidance was checked against the installed Next.js 16.3.0 documentation. Next.js Route Handlers use route.js or route.ts beneath the App Router and the Web Request/Response APIs.
The small example below belongs to your application, for example app/api/media-operations/route.js. The imported function is an application helper you must implement; it is not an Imagild SDK.
import { acceptApprovedOperation } from "@/lib/your-operation-store";
export async function POST(request) {
const operation = await acceptApprovedOperation(request);
return Response.json(
{ operation_id: operation.id },
{ status: 202, headers: { "Cache-Control": "private, no-store" } }
);
}
That helper must authenticate the caller, apply your CSRF policy where applicable, validate an allowlisted request, verify ownership and spending approval, and atomically persist both operation and durable outbox event. Do not implement it as a memory-only array followed by an unawaited promise.
Freeze the provider request before the worker runs
Store the chosen model, prompt and resolution beside a server-generated idempotency key. For a text-only image, the eventual provider request contains:
{
"model": "gpt-image-2.5",
"prompt": "A blue ceramic cup on a pale wooden table in soft window light",
"resolution": "1K"
}
The worker sends that JSON to POST /images/generations on the base URL https://imagild.com/api/relay/v1 with Bearer authentication, JSON content type and the saved Idempotency-Key. No kind, local customer ID, callback URL or quoted price belongs in that body.
At current rates this 1K generation uses 10 points; 2K and 4K use 15 and 20. Active membership is required separately. Populate model choices from the current model hub, and confirm spending before creating the operation.
Keep secrets and ownership at the boundary
Next.js environment-variable guidance explains that NEXT_PUBLIC_ values can be included in browser bundles. Your API key should use a server-only variable such as IMAGILD_API_KEY, injected through deployment secrets.
Do not accept an arbitrary provider task ID from a browser and read it with a shared account credential. Resolve the local operation under the signed-in user's permissions, then use its saved task ID.
This follows OWASP's endpoint authorization guidance. A server-side key protects the credential; application authorization still protects your individual customers.
Return early without losing the job
A worker commits the returned data.id, then schedules bounded status reads. Your browser reads the local operation endpoint to see queued, running, review or completed information derived from actual observations.
If a submission response is lost, recover the same operation with its unchanged key and body. If a known task is merely waiting, read that task rather than posting again. The failed-job guide explains why uncertainty is different from confirmed failure.
Test your route with an authenticated fixture, an unauthorized caller and a duplicated form submission. Restart the worker after its outbox row is committed and verify that the same operation resumes. Keep the points planning guide available in the spending confirmation. Passing this test establishes your boundary behavior, not a deployment-time or generation-speed guarantee.
Related tasks
- What Should You Check Before Retrying a Failed Image or Video Job?
- Imagild Points, Resolution and Jobs: Plan a Creation Before You Spend
Sources and scope
- Imagild API console: Active-member access, supported media request fields, idempotency, asynchronous task records and authenticated downloads; checked against the 2026-10-28 relay contract.
- Next.js Route Handlers: App Router route.js/route.ts convention, Web Request/Response handlers and version-aware route caching; also read from installed Next.js 16.3.0 documentation.
- Next.js environment variables: NEXT_PUBLIC_ variables can enter browser bundles; private API keys belong in server configuration.
- OWASP REST Security Cheat Sheet: Endpoint authorization and server-side credential handling; individual application-customer ownership remains the integrator's responsibility.
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.