Ideogram 4.5 Edit API
POST Base URL:
https://api.hiapi.ai /v1/tasks Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).
Model summary
| Model name | ideogram-v4.5/image-to-image |
|---|---|
| Type | Image editing (image-to-image) |
| Endpoint | POST /v1/tasks |
| Pricing | See HiAPI Pricing |
Ideogram 4.5 Edit changes a primary source image with natural-language instructions, with optional references, masks, and edit precision controls.
Production guidance
Production guidance
- For production, pass callback.url at the top level so HiAPI can notify your service when the task reaches a terminal state.
- GET /v1/tasks/:id is useful for local debugging, low-volume jobs, or reconciliation after a missed callback.
- Both success and fail are terminal states; deduplicate handling by taskId.
Best suited for
Focused edits with preservation
State the requested change and the subject, text, composition, and lighting that must remain.
promptimage_urlMulti-reference composites
Add up to 4 reference images and assign each image a role in the prompt.
reference_image_urlspromptMask and precision controls
Use mask_url to define the editable area and choose regular or high precision as needed.
mask_urledit_precisionRequest parameters
model string required Fixed value ideogram-v4.5/image-to-image.
input object required Business parameters for Ideogram 4.5 image editing.
prompt string required Describe what to change and what must remain unchanged. Length: 1–10,000 characters.
image_url string required Public URL of the primary source image to edit.
reference_image_urls string[] optional Optional array of reference image URLs, up to 4. When mask_url is set, use at most 3.
mask_url string optional Optional mask image URL. Black areas may be edited and white areas are preserved; match the source dimensions.
edit_precision enum optional Edit precision. high places more emphasis on restoring unchanged pixels; quality=very_low is unavailable with high.
quality enum optional Output quality tier. regular accepts all four values; high accepts low, medium, and high.
image_size enum optional Output size preset. Editing uses auto when omitted.
num_images integer optional Number of images to generate in one task, from 1 to 8.
seed integer optional Optional random seed that can help reproduce a result with the same input.
callback object optional Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.
url string required Required when callback is set; HTTPS URL that receives terminal task notifications.
when enum optional Callback trigger timing. Use final.
Example requests
Prompt edit: winter poster
Regular + very_low; only the palette and background change, text and layout stay.
Request body
{
"model": "ideogram-v4.5/image-to-image",
"input": {
"prompt": "Turn this festival poster into a winter edition: icy blue and silver palette, snowy mountains replacing the sunset, keep all text and layout the same",
"image_url": "https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385709978-062553a94718311d-t2.png",
"edit_precision": "regular",
"quality": "very_low",
"image_size": "auto",
"num_images": 1
}
}Precise Edit logo text
edit_precision=high changes only the text and restores other pixels; size must be auto.
Request body
{
"model": "ideogram-v4.5/image-to-image",
"input": {
"prompt": "Change the logo text from \"Ember & Oak\" to \"Maple & Co\", keep the same serif lettering style, emblem, tagline, colors and layout exactly unchanged",
"image_url": "https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385709528-9ea916b16cbb5255-t1.png",
"edit_precision": "high",
"quality": "low",
"image_size": "auto",
"num_images": 1
}
}Reference restyle
One reference image supplies the palette and packaging style.
Request body
{
"model": "ideogram-v4.5/image-to-image",
"input": {
"prompt": "Restyle this coffee logo using the jade green and gold color scheme and premium packaging style of the reference image, keep the text \"Ember & Oak\" readable",
"image_url": "https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385709528-9ea916b16cbb5255-t1.png",
"reference_image_urls": [
"https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385710363-67646b28c0cefc08-t3.png"
],
"edit_precision": "regular",
"quality": "very_low",
"image_size": "auto",
"num_images": 1
}
}Mask inpainting
Black areas are repainted and white areas kept; size must be auto with a mask.
Request body
{
"model": "ideogram-v4.5/image-to-image",
"input": {
"prompt": "The woman wears an emerald green wool trench coat instead of the red coat",
"image_url": "https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385710761-72fd4b52d2d96338-t4.png",
"mask_url": "https://dev-static.hiapi.ai/model-onboarding/ideogram-v4.5/20261019/2026/10/19/1792385384980-4d8619ba40031f9b-e3-mask.png",
"edit_precision": "regular",
"quality": "very_low",
"image_size": "auto",
"num_images": 1
}
}Getting the result
- The response returns a taskId immediately.
- In production, prefer callback.url for terminal notifications; poll GET /v1/tasks/:id for local debugging.
- When status=success, download the image from output[].url.
- When status=fail, fix the request from the returned error.
FAQ
What does image editing require?
prompt and image_url are required. Add references, a mask, edit precision, and quality when needed.
What is the difference between regular and high precision?
regular supports all four quality values. high places more emphasis on unchanged pixels and does not allow very_low.
How does the mask work?
Black areas may be edited and white areas are preserved. Match the mask dimensions to the source image.
How many references can I provide?
Up to 4 normally, or up to 3 when mask_url is present.