Use a source image, a mask and one character reference to inpaint the same character into an existing scene. Try it on HiAPI with before/after examples, billing notes and API samples.
Provider: Ideogram
Category: image generation
Endpoint: /v1/tasks
Status: Available
Cost: See live page pricing
Use a source image, a mask and one character reference to inpaint the same character into an existing scene. Try it on HiAPI with before/after examples, billing notes and API samples.
Pricing
Standard Usage
Upload one clear image of the character (illustration or photo); generated output follows its aspect ratio
Black areas are repainted, white areas kept; must match the source aspect ratio
TURBO is fastest, BALANCED is the default, QUALITY has the finest detail; each tier is priced separately
AUTO, REALISTIC or FICTION (illustrated)
Expand the prompt with MagicPrompt
Ready for generation
Configure your parameters and click "Run" to see the output here.
Each case separates references, the edit instruction, and the complete result, with image zoom and prompt copy.
Source image (cabin)
Portrait illustrated character
Result2 reference images / 1024 × 768
Only the masked area is repainted: the character sleeps in the armchair while the rest of the cabin stays unchanged.
The explorer character curled up in the armchair asleep under a knitted blanket
Source image (cabin)Portrait illustrated character
Result2 reference images / 1024 × 768
A different mask places the same character waving by the window, keeping the original composition and light.
The explorer character standing by the window waving at the camera
Source image (cabin)
Landscape photo reference
Result2 reference images / 1024 × 768
Photo reference plus mask: the same person reads in the cabin, and the output keeps the 1024×768 source size.
The same man sitting in the armchair reading a hardcover book, relaxed, warm lamp light on his face
Choose an adjacent model by task, output tier, and reference-image needs.
Consistent character generation
Generate new scenes from one character reference when you have no source image.
Typography and layouts
Choose Ideogram V4 for poster lettering, logos and signage.
Reference editing
Compare Nano Banana 2.1 for prompt-led edits without a mask.
Use a source image, a mask and one character reference to inpaint the same character into an existing scene. Try it on HiAPI with before/after examples, billing notes and API samples.
The Playground and API use the same model ID: ideogram-v3-character/edit. Reference images provide subject, product, scene, or style facts, while the prompt assigns each role and limits the edit.
Choose inputs and output settings for your creative goal with Ideogram 3.0 Character Edit.
Each request returns one image; references, source images and masks are not charged separately. Failed tasks are not charged; see live pricing.
References provide visual facts; the prompt assigns their roles and limits the edit.
Match the source aspect ratio; on a white background paint the character area black, slightly larger than the silhouette.
Describe the character's action and props inside the mask; background, light and composition outside stay unchanged.
Compare source and result in Playground, then create asynchronous tasks with the same model ID.
Copy a minimal request below. See Docs for parameters, callbacks, task retrieval, and errors.
POST /v1/tasksideogram-v3-character/editcurl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v3-character/edit",
"input": {
"prompt": "The explorer character curled up in the armchair asleep under a knitted blanket",
"image_url": "https://static.hiapi.ai/gallery/2026/10/8e1328c02f8edd33.jpg",
"mask_url": "https://static.hiapi.ai/gallery/2026/10/0121b5b1d8af8697.png",
"reference_image_urls": [
"https://static.hiapi.ai/gallery/2026/10/12ccfec91203bec9.jpg"
],
"rendering_speed": "TURBO"
}
}'The create request immediately returns a taskId; image generation continues asynchronously.
MASK-BASED INPAINTING
Character Edit is for when the scene already exists and only the character is missing. Submit a source image, a mask with the same aspect ratio and one character reference; the model repaints only the black mask area with the referenced character while the background, light and composition outside the mask stay as they are.
The mask sets where the character appears and roughly how large; the prompt only needs to describe the action and props inside that area. Output keeps the source size, one image per request.
EXAMPLES AT A GLANCE
All three use the same cabin source and change only the mask and character reference; the prompt describes just the action inside the mask and can be copied.
4:3The explorer character curled up in the armchair asleep under a knitted blanket
4:3The explorer character standing by the window waving at the camera
4:3The same man sitting in the armchair reading a hardcover book, relaxed, warm lamp light on his face
MASKED EDITING
ideogram-v3-character/edit takes three inputs: a source image, a mask with the same aspect ratio and one character reference. The black mask area is repainted, white areas stay, and the output keeps the source size.
Match the source aspect ratio and on a white background paint the character area black, slightly larger than the silhouette.
Illustration or photo, exactly one image with a clear subject.
Say what the character does inside the mask, such as reading in the armchair or waving by the window.
BEFORE AND AFTER
Each set submits a source, a mask and one character reference. The black mask area is repainted with the character and the white area keeps the source; drag the slider to see shelves, lights, the rainy street and the cabin stay unchanged.
Bakery counter · mascot · mask + character reference
Rainy bus stop · picture-book hero · mask + character reference
Cabin armchair · illustrated character · mask + character referenceSAME SOURCE, DIFFERENT MASK
Keep the source and reference, and change the mask position and the action in the prompt: with the mask over the armchair and a sleeping prompt, the character sleeps in it; with the mask by the left window and a waving prompt, the character stands there waving. Furniture, light and composition outside the mask stay the same.
Keep an existing store or display shot and mask only the empty spot for the mascot.
When the background art is final, mask the spot and paint the hero in.
Swap masks on the same source to get the character in different spots and poses.
When the background is final and the character just needs a spot, local inpainting is more controllable than regenerating the whole image.
Mask an empty spot in an existing store or display photo and add the mascot without reshooting shelves or lights.
Example: bakery counter
When the background art is done, mask a bench or window and paint the hero in.
Example: rainy bus-stop bench
Swap masks on one source for versions with the character in different spots and poses.
Example: cabin armchair and window
These notes correspond to the inpainting examples on this page.
CHARACTER
One character reference plus a prompt places the character in any new scene.
IDEOGRAM V4
Compare it for titles, logos and signage.
Upload the source, mask and character reference separately in the Playground above. For integration, submit model ID ideogram-v3-character/edit through the HiAPI /v1/tasks endpoint, billed per image with no charge for failures.
The mask must match the source aspect ratio. Black areas are repainted and white areas are kept; a mask slightly larger than the silhouette looks more natural.
The output keeps the source size; a 1024×768 source returns 1024×768.
Yes. Paint that person into the mask and describe the new character's action; people and background outside the mask are kept.
An image with the same aspect ratio as the source, with the area to repaint in black on white; the examples on this page use PNG masks.
Slightly larger than the character silhouette. Too small cramps the pose; too large repaints more of the background.
Only what the character does inside the mask, such as sitting on the bench with an umbrella or waving by the window. There is no need to describe the background; everything outside the mask stays.
Yes. Keep the source and reference, and change the mask position and the action in the prompt; the cabin armchair and window versions on this page were made that way.
No. image_url, mask_url and reference_image_urls are all required; without a source image, use the Character generation model.
No. reference_image_urls must contain exactly one image; illustrations, mascots and photos all work.
Yes. The TURBO / BALANCED / QUALITY tiers and AUTO / REALISTIC / FICTION styles apply as well; each tier is priced per image, see live pricing.
Not yet. Character generation (ideogram-v3-character) and masked editing (ideogram-v3-character/edit) are available today.
Failed tasks are not charged. Save the taskId, query GET /v1/tasks/:id and download the WebP from output[].url when status is success; output[].url is temporary, so save results promptly.