
Version prompt templates in your application, then save the rendered prompt inside each submitted Imagild request. Updating a shared template must not mutate a running job or reconstruct different retry parameters. A template version is application provenance; it is not a supported extra field in the generation JSON.
Key Takeaways
- Store template identity and hash separately from the exact API payload.
- Retries use the saved payload, not today's template renderer.
- A changed prompt or deliberately new candidate requires a newly approved operation.
Distinguish a template from the submitted instruction
A template might say, “Place the product on {{surface}} with soft side lighting.” The API receives the fully rendered instruction after the application supplies the variable.
If a job is retried tomorrow after the template changed, re-rendering it can produce different parameters under the original idempotency key. That can create a conflict instead of recovering the accepted task.
The API console defines a strict image body containing model, prompt, resolution, and an optional owned reference selector. Do not add template_version, template_hash, or your application's editorial metadata to that body.
Capture provenance and payload together
This native Node.js planning example creates a template reference and a separate request snapshot. It does not call the API or persist the record:
import { createHash } from "node:crypto";
const templateText =
"A blue ceramic vase on {{surface}}, with soft side lighting.";
const surface = "a pale stone plinth";
const prompt = templateText.replaceAll("{{surface}}", surface).trim();
if (!prompt || prompt.length > 4000) throw new Error("Invalid prompt");
const record = {
template: {
id: "catalog-vase",
version: "v3",
sha256: createHash("sha256").update(templateText, "utf8").digest("hex")
},
payload: {
model: "gpt-image-2.5",
prompt,
resolution: "1K"
}
};
console.log(record);
Node's crypto reference documents the hash operation. The template hash identifies that application's text; it is not Imagild's server request hash or proof of model-output reproducibility.
Persist the record with account ownership, approval, operation key, and eventual task ID before paid submission. Validate every required variable and reject unresolved placeholders.
Define how an update affects each state
| Existing state | Template update behavior |
|---|---|
| Unapproved draft | May offer a preview using the new version |
| Approved but not submitted | Re-review if rendered request or quote changes |
| Accepted task | Preserve its original payload and version |
| Lost acknowledgment | Recover with saved parameters and key |
| New intentional candidate | Create a new approved operation |
| Archived completed result | Keep original provenance; do not relabel it as the new version |
Changing metadata alone does not mean the creative output changed. Conversely, identical template labels do not establish identical rendered prompts if variables differ.
Keep a human-readable comparison of old and new instructions so the reviewer can approve a specific change instead of trusting a version number.
Bind references and model settings explicitly
A prompt template may refer to a selected source. Preserve the actual file_id or image_task_id in the request snapshot instead of rebuilding it from today's thumbnail order.
The reference attachment-order audit explains why a visible label can drift from its source. If a template changes source scope or model settings, treat that as a different reviewed request.
The resolution capability guide helps distinguish requested tier and task-mode requirements. Do not insert unsupported image aspect_ratio, seed, n, or size fields merely because another template system offers them.
Review version changes without claiming deterministic output
For a controlled comparison, hold the intended model, tier, source, and acceptance brief constant, then approve separate candidates. Record the template difference and evaluate actual outputs. A template hash does not guarantee the same image on another operation.
Current choices and 10/15/20-point image tiers appear in the model market. Active membership is required independently of points, and comparison generations consume separate approved budgets.
Versioning makes a request explainable after an edit or restart. Its practical value is accurate recovery and traceable decisions, not an untested promise that every template revision improves quality.
Related tasks
- After Reordering References, Does “Image 1” Still Point to the Right File?
- Why Can This Image Model Generate 4K but Not Edit My Reference at 4K?
Sources and scope
- Imagild API console: Strict request fields, idempotent same-parameter recovery and active membership.
- Imagild model market: Current canonical choices and resolution point schedule.
- Node.js createHash: SHA256 hash of exact UTF8 template text for local provenance.
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.