---
title: "Replace the model in a commerce image"
method: POST
path: "/v2/tool/model-swap"
tags: ["edit-workflow"]
---

# Replace the model in a commerce image

`POST /v2/tool/model-swap`

Re-casts a fashion commerce image with the identity shown in one or
more ordered target-model references. The workflow uses the working
image for the product, pose, scene, lighting, framing, and camera, and
uses the target references only for identity, hair, skin tone, and body
proportions. Results are full-frame edits; exact pixel preservation is
not guaranteed.

The request is processed asynchronously. Poll
`GET /v1/generations/{generation_id}` with the returned `generation_id`
until the generation is completed or failed.

## Request body

- ModelSwapRequest — Provide exactly one of `source_asset_identifier` or multipart `source_image`, plus one to four ordered target-model references.
  - `source_asset_identifier` AssetIdentifier — An identifier for an ideogram asset.
    - `asset_type` 'ASSET' | 'CANVAS_ASSET' | 'LAYERED_ASSET' | 'RESPONSE' | 'UPLOAD', required
    - `asset_id` string, required
  - `source_image` string, binary — Raw working-image bytes. Supported formats and the 50 MB limit match the image upload API. Available only with `multipart/form-data`.
  - `model_asset_identifiers` AssetIdentifier[], required — Ordered target-model identity and angle references. These images supply only identity, hair, skin tone, and body proportions.
    - `asset_type` 'ASSET' | 'CANVAS_ASSET' | 'LAYERED_ASSET' | 'RESPONSE' | 'UPLOAD', required
    - `asset_id` string, required
  - `instruction` string — Optional identity details that are not visible in the target-model references. This cannot override the source roles described above.
  - `aspect_ratio` string — Output aspect ratio. When omitted, the closest supported ratio is derived from the working image.
  - `quality` 'LOW' | 'MEDIUM' | 'HIGH' — The quality tier for the image edit. Higher tiers may improve detail and take longer to complete.
  - `seed` integer — Optional seed for repeatable results.
  - `num_images` integer — Number of model-swap images to create.
  - `private` boolean — When true or omitted, the output is kept private to your account. Set to false to publish the output to the public feed. Enterprise accounts always generate privately.
  - `webhook_url` string, uri — 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 `200`

Model swap accepted for asynchronous processing.

- ModelSwapResponse — Acknowledgement that the workflow was accepted.
  - `generation_id` string, required — URL-safe base64 ID accepted by the generation polling endpoint.

## Other responses

- `400` — Invalid input provided.
- `401` — Unauthorized.
- `402` — Insufficient credits or quota.
- `403` — Not authorized to use model swap.
- `404` — An input asset was not found or is not readable.
- `422` — The instruction did not pass prompt safety checks.
- `429` — Too many requests.

---

[API](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ideogram/ideogram-openapi-3-0/revisions/3eb3216eed39/schema)