
An Imagild image request with a reference needs a prompt of at least 20 characters after leading and trailing whitespace is trimmed. The rule applies when you supply either file_id or image_task_id. A valid photo and a short instruction such as “make it blue” are therefore insufficient, even though text-only generation accepts a shorter nonempty prompt.
Key Takeaways
- Reference-image prompts must contain 20–4,000 characters after trimming.
- Supply a meaningful edit instruction, not padding added only to pass a counter.
- Check reference selection, ownership, and source availability separately from prompt length.
Diagnose the failing condition
A request can fail for more than one independent reason. Use this preflight table before changing the model or buying more points:
| Check | Valid condition | Common mistake |
|---|---|---|
| Prompt type | String | Form submits an object or null |
| Trimmed length | 20–4,000 with a reference | Spaces conceal a short instruction |
| Reference choice | One selector | Both IDs remain in hidden form state |
| Uploaded source | Owned usable upload | A filename is sent instead of returned ID |
| Generated source | Completed owned image task | A pending task or video ID is sent |
| JSON fields | Supported image fields only | A copied strength, mask, or seed option |
The API console is the receiving contract. Model schema validation is not unique to one platform: Runware's schema documentation also separates declared inputs and rules between fields. Use that principle without copying its parameter names into an Imagild request.
Validate the edited prompt that will actually be sent
The counter next to an input should inspect the same text your backend submits. This small JavaScript function handles the trimmed-length rule and prevents two reference selectors from surviving a UI switch:
function checkReferencePrompt(payload) {
if (payload.file_id && payload.image_task_id) {
throw new Error("Select an upload OR a generated image");
}
if (typeof payload.prompt !== "string") {
throw new Error("Write edit instructions as text");
}
const prompt = payload.prompt.trim();
const hasReference = Boolean(payload.file_id || payload.image_task_id);
const minimum = hasReference ? 20 : 1;
if (prompt.length < minimum || prompt.length > 4000) {
throw new Error("Prompt length is outside the allowed range");
}
return { ...payload, prompt };
}
This is a prompt check, not a complete schema validator. The server still validates selector syntax, ownership, model availability, and the rest of the request. Use ordinary descriptive text rather than relying on emoji or combining characters to reach a visual counter's threshold.
Turn a short command into a reviewable instruction
“Make it blue” leaves both scope and preservation unclear. A better product-edit brief is:
Change only the mug's outer surface to matte cobalt blue.
Keep its handle shape, camera angle, table, and soft side lighting.
For a portrait with a text panel, provide the requested visible text explicitly:
Keep the portrait and plain background.
Replace the panel text with:
Name: Maya Chen
Role: Product Designer
Location: London
These are instructions to request and review, not guarantees that a model will render every character correctly. Compare the actual output with the intended wording before publishing. If the visible text must be exact, retain a separate layout or typesetting step in your production plan.
The reference scope guide helps distinguish a local edit from replacing an entire scene. For transparent source assets, inspect the preview using the character reference background guide.
Correct the input without losing the operation trail
If local validation fails before any request is sent, explain the missing information beside the prompt. Do not start a paid generation with automatically invented details.
If the server rejected the submission, preserve its error and request ID while correcting the form. If an earlier task was already accepted, inspect it before creating a different operation. A changed accepted request cannot reuse the same idempotency key.
Current image pricing remains explicit: 1K uses 10 points, 2K uses 15, and 4K uses 20; verify the model market. Active membership is required for API access. Prompt validation, sufficient points, and access eligibility are separate checks, and each should produce a specific user-facing next action.
Related tasks
- Should an AI Reference Replace an Object or Bring in the Whole Scene?
- Should My AI Character Reference Have a Transparent or Solid Background?
Sources and scope
- Imagild API console: Image reference prompt contract, accepted selectors and access requirement.
- Imagild model market: Current 1K/2K/4K points.
- Runware Model Schemas: Field and cross-field validation is driven by the receiving API schema.
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.