Sign in
latestOpenAPI 3.0.22026-08-21134292561.4 KB

898026c78d68

edit-workflow

Dress a person in one or more garments

Generates a photorealistic image of the person in the supplied photo wearing the supplied garments, preserving their face, body, and background.

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 person as either an AssetIdentifier reference (person_asset_identifier) or the raw image bytes directly (person_image, multipart requests only), and likewise the garments as either garment_asset_identifiers or garment_images. For each of the two sources, provide exactly one of the two forms; supplying both, or neither, is rejected with a 400.

post/v2/workflow/virtual-try-on

Request body

person_imagestring binary

Photo of the person to dress (max size 25MB), as raw bytes; only JPEG, PNG, and WEBP formats are supported. Multipart requests only. Provide exactly one of person_asset_identifier or person_image.

garment_imagesstring[]

Photos of the clothing items to put on the person (max 7, max size 25MB per image), as raw bytes; only JPEG, PNG, and WEBP formats are supported. Multipart requests only. Provide exactly one of garment_asset_identifiers or garment_images.

aspect_ratiostring

The aspect ratio of the generated image. Defaults to the aspect ratio of the person's photo when omitted. Supported values are 1:1, 3:4, 4:3, 16:9, and 9:16.

instructionstring

Free-text art direction, for example which garments to name, how to pose the person, and what background to place them in. The person's identity and each garment's exact appearance are always preserved, whatever this says. When omitted, the person keeps the pose and background from their photo.

privateboolean

If true, the user is requesting private generation. If omitted, this defaults to the user's plan entitlement. Enterprise generations are always private.

webhook_urlstring 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.

Example request

{
  "person_asset_identifier": {
    "asset_type": "RESPONSE",
    "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
  },
  "garment_asset_identifiers": [
    {
      "asset_type": "RESPONSE",
      "asset_id": "7uS_VESkRI6O3-sVgHQp_A"
    }
  ],
  "webhook_url": "https://api.example.com/webhooks/ideogram"
}

Response

Try-on accepted for asynchronous processing.

generation_idstring required

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

Example response

{
  "generation_id": "generation_id"
}