edit-workflow

Product Material Change

Changed on

Re-renders the masked regions of the product photo in the materials shown by the reference images — matching each one's color, texture, pattern scale, and orientation — while preserving the product's silhouette, construction, seams, and shading, and keeping every region outside the masks 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 masks marking the regions to re-material, and the material reference images as raw bytes (image, masks, and materials) via multipart/form-data — up to 4 masks; a single-region edit is a one-item list. Every 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. Send either one material, which every mask takes, or exactly one material per mask, paired by position.

post/v2/tool/material-swap

Request

  • Base URL: https://api.ideogram.ai
  • URL: https://api.ideogram.ai/v2/tool/material-swap
  • Auth: API key in header Api-Key

Query parameters

dry_runboolean

When true, the request is validated and priced but not run: nothing is generated, stored, or billed, and no safety review is performed. The response is a PriceQuote object instead of the usual response for this endpoint. Send exactly the request you would send to generate, so the quote reflects the same options.

Response

Material swap accepted for asynchronous processing.

generation_idstring required

URL-safe base64 ID accepted by the generation polling endpoint.

Changes

  • 52511913bd75Revision changes
    • breaking

      removed the enum value HIGH of the request property

    • breaking

      removed the enum value LOW of the request property

    • breaking

      removed the enum value MEDIUM of the request property

    • breaking

      the response's body type changed from no type to object for status

    • breaking

      the response's body type changed from no type to object for status

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • info

      added the new optional query request parameter dry_run

    • info

      added the new high enum value to the request property

    • info

      added the new low enum value to the request property

    • info

      added the new medium enum value to the request property

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • de120c38c7a2Revision changes
    • warning

      deleted the header request parameter Api-Key

    • info

      the endpoint scheme security ApiKeyAuth was added to the API