Blog

Guide

Ideogram V3 Character Edit Integration Guide: How to Prepare Source Images, Masks, and Character Reference Images

The three types of image input each have their own role: submit local edits according to the contract fields and self-check character consistency and boundaries item by item

Nov 18, 2026
Blog cover image: on a deep dark green background, two sets of wide, flat bands interweave into a technical woven plaid, with brass-colored vertical accents interspersed, geometrically restrained.
On this page

What each of the three image inputs is for

Before integrating ideogram-v3-character/edit, first separate the responsibilities of the three image fields; every preparation step that follows will then become clear.

  • Source image image_url: determines "what picture to change." It provides the original composition, background, and subject position, and is the foundation of the entire editing operation.
  • Mask mask_url: determines "where to change." It only delineates the area that needs to be redrawn; content outside that area should be preserved.
  • Character reference image reference_image_urls: determines "what the character looks like." It provides the character's appearance features so that the redrawn result aligns with the reference character.

Do not confuse the boundaries of the three: the source image is not the character reference image, and the character reference image cannot replace the source image; the mask is a spatial constraint, not a content description. Handing character features to the reference image, writing the picture content into prompt, and handing the modification scope to the mask is the split that minimizes errors. Once they are mixed up (for example, uploading only a character image without enabling the mask, or using the mask to "hint" at the character's appearance), you lose the basis for judgment when troubleshooting.

At the contract level, the source image and mask are string URL fields, while the character reference image is an array field; the different types also hint at different uses: the first two are a one-to-one spatial pairing, while the latter is an independent source of character description.

The three types of input are not stacked in parallel: the source image, mask, and character reference image each govern different regions of the output frame; the diagram uses three converging lines to express this division of labor.

Preparation points for the source image and mask

Both image_url and mask_url are required fields, in URI format, and must start with http:// or https:// (contract pattern ^https?://), with a minimum length of 1.

Aspect ratios must match

The only hard geometric constraint the contract imposes on the two is: the mask must maintain the same aspect ratio as the source image. This is a precondition, not a suggestion; the safest approach when preparing assets is to first output the mask at the source image's dimensions locally, then upload them together, rather than expecting the server to align them for you.

Mask semantics: only delineate the redraw area

The mask marks the locations where redrawing is "allowed." Therefore:

  • Do not let parts that need to be preserved fall inside the mask area;
  • The subject that needs to change (e.g., changing outfit or pose) should fall completely inside the mask, avoiding cut-off edges;
  • Do not make the mask too fragmented; scattered small patches make it difficult for the model to understand the editing intent.

URL availability

Both fields are remote URLs; before submitting, be sure to confirm that the link can be accessed anonymously, has no broken redirects, and requires no login authentication. For the mask, it is recommended to use an image with a transparent channel or clear black-and-white contrast, to avoid boundary ambiguity caused by semi-transparent gradients.

Specifications and limits of the character reference image

reference_image_urls is a required array field, and the contract gives explicit constraints: minItems: 1, maxItems: 1, i.e., exactly one image is required. Passing two or zero will both be judged as invalid input; this runs counter to the intuition of many "multi-image reference" setups and is an easy pitfall during integration.

Format and size

  • Supported formats: JPEG, PNG, WebP;
  • Maximum 10 MB per image.

Image selection advice

The role of the character reference image is to provide stable character features, so:

  1. Choose a clear, frontal or near-frontal image with an unobstructed face;
  2. Avoid strong backlighting, heavy filters, and group photos (the model cannot determine whom to align with);
  3. Full-body and half-body each have trade-offs: use half-body or closer when clothing details are needed, and full-body when the overall look is needed;
  4. Do not use an image that already has a complex background to "hint" at the scene — leave the scene to the prompt description.

Although the array form holds only one element, it must still be submitted as an array, e.g., wrapping a single URL as one item rather than placing a string directly.

How to combine required and optional fields

There are four required fields in total: prompt, image_url, mask_url, reference_image_urls. Optional adjustment fields include expand_prompt, style, seed, rendering_speed.

prompt describes the new scene, not an editing instruction

The contract's definition of prompt is key: "describe the scene in which the reference character is located, i.e., the picture content to be generated by this edit," with a length of 1–5000 characters. That is, do not write operation instructions like "change her clothes to a red coat," but write picture descriptions like "she stands on a street after the rain, wearing a red coat, with neon lights reflected on the wet ground." The editing scope is handled by the mask, while prompt handles the picture content itself.

expand_prompt is enabled by default

expand_prompt is a boolean switch, defaulting to true; when enabled, MagicPrompt automatically expands the prompt. This means the short description you submit will be processed once more by the model. During the troubleshooting stage, it is recommended to keep the default first, and decide whether to turn it off only after clarifying the difference between the long description and the expanded result.

style and seed

  • The style enum is AUTO, REALISTIC, FICTION, defaulting to AUTO. Use REALISTIC for realistic characters, FICTION for stylized illustrations, and stay at AUTO when unsure.
  • seed is an integer ranging from 0 to 2147483647, used to reproduce the generation results of the same prompt. When comparing "same input, different parameters," fixing the seed eliminates randomness interference.

Choosing the rendering_speed level

rendering_speed is a string enum, defaulting to BALANCED, with three levels:

  • TURBO: fastest output, suitable for quickly validating mask scope and whether the character matches during the draft stage;
  • BALANCED: default level, a compromise between speed and detail, the starting point for daily integration;
  • QUALITY: richest detail, suitable for the finalization round before the final output.

The selection approach is to switch by stage rather than fix it once and for all: first use TURBO to confirm that the geometry and character direction are fine, then use BALANCED or QUALITY to converge on details. This way, repeated debugging will not consume time on high-quality rendering.

It should be emphasized: the three levels differ in billing basis (billed by output level); for specific prices, please refer to the site's pricing panel, and this article does not go into numbers. When troubleshooting image input issues, fixing to the default level first can reduce one variable.

The three levels are like changes in density of the same weave: the higher the weave, the denser and more detailed, and the slower it is.

Pre-submission self-check list

Checking item by item against the contract can block most failures before submission:

  • prompt is non-empty and no more than 5000 characters, and the content is a scene description rather than an editing instruction;
  • image_url is an anonymously accessible link starting with http:// or https://;
  • mask_url is similarly accessible and has the same aspect ratio as the source image;
  • reference_image_urls is an array with a length of exactly 1;
  • The reference image format is JPEG/PNG/WebP and the size does not exceed 10 MB;
  • Optional field spellings and enum values are correct (style and rendering_speed use the uppercase values listed in the contract);
  • If seed is set, confirm it is an integer from 0–2147483647;
  • If expand_prompt is disabled, confirm that the prompt itself is sufficiently complete.

This list is also the first stop for troubleshooting: if any item is not satisfied, fix the input first rather than repeatedly adjusting the description.

Troubleshooting character deviation and boundary issues

When the generated result is not as expected, first categorize the problem, then make targeted adjustments; this is more effective than resubmitting the entire image.

Type 1: character does not look alike

This manifests as facial features, hairstyle, and body shape deviating from the reference image. Adjustment directions:

  • Replace the reference image: a clearer frontal image, better lighting, a single subject;
  • Check whether the reference image is cropped or over-compressed;
  • Add character descriptions (clothing, posture, age temperament) in prompt so that text and image corroborate each other;
  • Reduce scene complexity to prevent background elements from competing with character details.

Type 2: boundaries are blurred

This manifests as content outside the mask being unexpectedly changed, or seams and ghosting appearing at the mask edges. Adjustment directions:

  • First confirm that the aspect ratios of the source image and mask are strictly identical;
  • Check whether the mask also encloses parts that need to be preserved;
  • Make the subject fall completely inside the mask to avoid cutting edges;
  • Switch to cleaner mask edges to reduce semi-transparent transitions.

Do not adjust the two types of problems together: change the reference image and description for character issues, and change the mask and geometry for boundary issues. Change only one variable at a time to determine which one takes effect.

From example to integration

Putting the contract requirements above into a process gives four steps: prepare a source image and mask with the same aspect ratio, choose a compliant character reference image, describe the new picture with a scene-based prompt, and check the fields against the list before submitting.

The integration entry point is on the model page; field definitions and enum values are subject to the page, and you can compare them item by item against the list in this article: Ideogram V3 Character Edit model page. Only when the assets are prepared correctly does subsequent tuning make sense.

Related articles

View all articles →

Start building with persistent AI artifacts

Get your API key and call image, video and audio models through one task-based API.

Read the API docs