
An Imagild image request rejects extra fields because its JSON schema is strict. Send only model, prompt, resolution, and optionally one of file_id or image_task_id. Copying a request from a different image API can introduce unsupported options even when the model name looks familiar.
Key Takeaways
- Remove unsupported fields deliberately; do not silently discard settings the user expects to work.
- Image requests do not accept
size,n,seed,response_format, oraspect_ratio.- Validate locally, then treat the server response as the authority for availability, ownership, membership, and billing.
Find the unsupported setting before changing the prompt
Consider a generic image form that submits this object:
{
"model": "gpt-image-2.5",
"prompt": "A ceramic cup on a walnut table",
"resolution": "1K",
"size": "1024x1024",
"n": 3
}
The prompt is not the problem. The request includes two fields the Imagild image endpoint does not expose. The corrected single-image request keeps the first three properties and omits size and n. If the user requested three images, your application must represent three separate operations, rather than pretending that deleting n satisfies their request.
The OpenAI image reference documents a separate vendor contract. Examples from it are useful for that API, but their parameters are not a compatibility promise for an Imagild routing ID.
Add a small preflight at your adapter boundary
This JavaScript check is intentionally limited to the request shape and common value mistakes. It does not replace the server's ownership checks or verify that a referenced task has completed.
function imagePreflight(input) {
if (!input || typeof input !== "object" || Array.isArray(input)) {
throw new Error("Expected one JSON object");
}
const allowed = new Set([
"model", "prompt", "resolution", "file_id", "image_task_id"
]);
const extra = Object.keys(input).filter(key => !allowed.has(key));
if (extra.length) throw new Error("Unsupported fields: " + extra.join(", "));
if (typeof input.prompt !== "string") throw new Error("Prompt must be text");
const prompt = input.prompt.trim();
if (!prompt || prompt.length > 4000) throw new Error("Prompt length invalid");
if (input.file_id && input.image_task_id) throw new Error("Choose one reference");
if ((input.file_id || input.image_task_id) && prompt.length < 20) {
throw new Error("Reference instructions need at least 20 characters");
}
if (input.resolution !== undefined &&
!["1K", "2K", "4K"].includes(input.resolution)) {
throw new Error("Unsupported resolution tier");
}
return { ...input, prompt };
}
Check the model against the current authenticated GET /models response separately. An empty or malformed reference value should also be corrected before submission; a nonempty string alone does not make it an owned, usable reference.
Schema-driven validation is a general integration pattern. Runware's schema guide explains validation against each model's declared inputs. It does not supply the schema for this endpoint.
Keep transport settings out of the JSON
Send the API key in Authorization: Bearer …, not in the request body. Send the operation's Idempotency-Key as a header. The image endpoint determines the task kind, so do not add kind: "image".
Use Content-Type: application/json and a single JSON object. The public contract is not a multipart image-generation request. Uploading an image is a separate POST /files action, after which its returned file_id can be used in JSON.
Test the adapter with saved request examples before connecting a paid submit button. One fixture should contain an unsupported field and show a useful local error; another should contain two reference selectors and require a source choice. A valid fixture should preserve the user's prompt, model, and resolution without adding hidden defaults from a different provider. This catches stale form state when a UI component is shared between video and image generation.
Open the API console for the exact endpoint examples and the model market for current choices. An active membership is still required even if local validation passes.
Retry only after identifying which operation exists
A validation error is different from an ambiguous network failure. If the request was rejected before acceptance, correct the input. If a task ID already exists, keep its history and inspect that task before creating a replacement. Reusing an accepted operation key with different parameters produces a conflict.
Record the response's error code and request ID without logging the secret key. Use the failed-job checks to choose a next action, and consult resolution capability by task mode when adapting a broader form. Good validation preserves user intent; it does not merely make an HTTP request pass.
Related tasks
- What Should You Check Before Retrying a Failed Image or Video Job?
- Why Can This Image Model Generate 4K but Not Edit My Reference at 4K?
Sources and scope
- Imagild API console: Current strict image request contract, headers and asynchronous submission.
- Imagild model market: Public image choices and supported resolution tiers.
- OpenAI image generation reference: OpenAI fields belong to OpenAI's separate vendor contract.
- Runware Model Schemas: Validate against the receiving model's declared schema rather than assuming universal parameters.
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.