Product Material Change
Re-renders the masked region of the product photo in the material shown
by the reference image — matching its color, texture, pattern scale,
and orientation — while preserving the product's silhouette,
construction, seams, and shading, and keeping every region outside the
mask unchanged.
The request is processed asynchronously. Poll
`GET /v1/generations/{generation_id}` with the returned `generation_id`
until the generation is completed or failed.
Supply the product photo, the mask marking the region to re-material,
and the material reference image as raw bytes (`image`, `mask`, and
`material`) via `multipart/form-data`. The mask must have the same
pixel dimensions as the product photo. White pixels mark the region to
change; black pixels are preserved. Alpha-only masks are also
supported: opaque pixels mark the region to change and transparent
pixels are preserved.
Authentication
Api-Keystring
API key for access control. Use in the header with the name “Api-Key”
Request
The product photo, the mask marking the region to change, and the material reference image.
image
The product photo to edit (max size 25MB), as raw bytes; only JPEG, PNG, and WEBP formats are supported.
mask
The mask marking the region of the product photo to change (max
size 25MB), as raw bytes; only JPEG, PNG, and WEBP formats are
supported. The mask must have the same pixel dimensions as the
product photo. White pixels mark the region to change; black pixels
are preserved. Alpha-only masks are also supported: opaque pixels
mark the region to change and transparent pixels are preserved.
material
The material reference image (max size 25MB), as raw bytes; only JPEG, PNG, and WEBP formats are supported. Only its material — color, texture, pattern scale, and orientation — is applied to the masked region.
aspect_ratio
The aspect ratio of the generated image. Defaults to the aspect
ratio of the product photo when omitted, which preserves the
original framing exactly. When a different ratio is requested, the
scene is extended to fill the new shape rather than cropped, so
part of the frame is newly generated. Supported values are `1:1`,
`3:4`, `4:3`, `16:9`, and `9:16`.
quality
The quality tier for the image edit. Higher tiers may improve detail
and take longer to complete.
Allowed values:
webhook_url
HTTPS URL that Ideogram delivers the generated result to. Ideogram sends a
JSON POST to this URL once all images for the request have finished
generating. The body mirrors the synchronous generate response:
`request_id`, `created`, and a `data` array
containing every generated image (`url`, `prompt`, `resolution`, `seed`,
`is_image_safe`). Each delivery is signed with Ed25519 and verifiable
against the public keys at `https://api.ideogram.ai/v1/.well-known/jwks.json`. Must be HTTPS;
private and loopback hosts and the cloud metadata service are rejected.
Response
Material swap accepted for asynchronous processing.
generation_id
URL-safe base64 ID accepted by the generation polling endpoint.
Errors
400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
429
Too Many Requests Error