Upscale Image Workflow

Upscale Image Workflow

Ideogram exposes one tool for raising an image's resolution: upscale_image. This skill orchestrates a single call to that tool — resolve which image, confirm the settings, run it, save the output's identifiers. It takes exactly one call per invocation: no multi-step pipeline, no multi-tool surface. It's the thinnest skill in the repo.

This is an orchestration workflow around one MCP call, not a prompt-composition skill — there's no composition-spec-format.md/panel-anatomy.md-style reference here.

Before you start

Read references/upscale-settings.md before running step 1 or step 2 of the workflow below. It covers the identifier-resolution rule (upscale_image requires exactly one of image_response_id or image_upload_id — never both, never neither) and the settings guide for every optional parameter.

Workflow

1. Resolve the target image

Determine exactly one identifier to pass. Either:

• image_response_id — from this session's generate_image/remix_image/edit_image/

reframe_image/remove_background calls' structured_content.response_ids, from get_recent_generations's per-item response_id, or from get_images_by_collection_id's per-asset response_id/image_id.

• image_upload_id — from upload_image, for a local file the user points to that hasn't

been uploaded yet. Call upload_image first rather than inventing an ID: per upload_image's own description, run its returned instructions curl command in the sandbox and read the real id back from the curl response.

If more than one candidate image is plausibly "that image" (e.g. several renders made earlier this session with nothing distinguishing which one the user means), ask which one — don't guess. Never pass both identifiers or neither. See references/upscale-settings.md for the full identifier-resolution rule.

2. Confirm settings

State the resolved settings before calling:

• upscale_factor — the user's stated value if given (that counts as confirmed, no need

to re-ask), or the tool's own X2 default, stated plainly rather than blocked on a confirmation question.

• upscale_details_weight — only set if the user asked for more/less added detail;

otherwise omit for the backend default.

• prompt — only set if the user wants to steer what detail gets added; otherwise omit —

the backend auto-describes the image when none is supplied, per the tool's own description.

• collection_id — only if the user asked to save directly into an existing collection.

If so, follow collections-management's find-or-create pattern from collection-patterns.md to resolve which collection_id to pass, rather than inventing one.

• private — omit unless the user explicitly asks to publish to the public Ideogram feed.

Per the tool's own description, paid accounts default to private and free/Basic accounts default to public, and enterprise generations are always private regardless — state that as the only asserted fact about the default, since it's the tool's own documented behavior.

3. Run the upscale

Call upscale_image with the resolved identifier and settings. Per the tool's own STRICT instruction: if the call fails, surface the failure to the user verbatim and stop. Never fall back to generate_image, remix_image, or any other tool as a substitute for a failed upscale.

The immediate response is asynchronous, not a completed result: it returns status: "running", a request_id, and a plural response_ids array — there is no singular response_id yet at this point. Call mcp__ideogram__get_generation_status with that request_id, polling until it returns status: "done". Only then does a singular response_id (matching response_ids[0]) become available. Do not proceed to "Save the output" until polling reaches status: "done".

4. Save the output

Persist the response's identifiers (whatever the live response actually contains — at minimum expect the singular response_id obtained by polling to status: "done" in step 3, matching every other Ideogram generation tool in this toolkit), the resolved upscale_factor, and the source image's identifier to the project's existing output location — the same place brand-identity-sheet, character-model-sheet, moodboard-generator, or collections-management already save to for this project. If a collection_id was passed in step 2, note that the upscaled image was also filed there. The exact response field name(s) beyond response_id (e.g. whether there's a downloadable URL) are read from the live response the first time it's called, not asserted in advance — per references/upscale-settings.md's confirmed-vs-unverified split.

Error handling

• Ambiguous target image (multiple plausible candidates, none clearly "that image") → ask

the user which one, don't guess.

• Local file not yet uploaded → call upload_image first; never fabricate an

image_upload_id.

• Both image_response_id and image_upload_id resolved, or neither → resolve to exactly

one before calling; the tool takes exactly one and the skill must not pass an invalid combination.

• upscale_image call fails → surface the failure verbatim per the tool's own STRICT

instruction; never retry silently with different settings and never fall back to a different generation tool pretending it's an upscale.

• Immediate upscale_image response only shows status: "running" with a plural

response_ids array → this is expected, not a failure; poll mcp__ideogram__get_generation_status with the returned request_id until status: "done" before treating the upscale as complete or saving the output.

• Response shape differs from what was assumed (e.g. missing an expected identifier field)

→ report what the response actually contains rather than asserting a field exists that wasn't observed.

Save what you made

After a successful upscale, save the real identifiers (per step 4 of the Workflow above) to the project's existing output location rather than leaving them only in the conversation, per the toolkit's "No Context Lost" habit.

Reference files

• references/upscale-settings.md — the identifier-resolution rule and the settings

guide for every optional upscale_image parameter, plus the confirmed-vs-unverified split for this tool's response shape. Read before running step 1 or step 2.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: devkindhq
• Source: devkindhq/ideogram-ai-toolkit
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.