Skip to main content
POST
Try an outfit on a person
Start with num_images: 1; omitting it also creates one output. See request settings. Track jobs and versions.

Authorizations

Authorization
string
header
required

Create an API key in Studio → account menu → API Keys. Keep it on your server.

Body

application/json
person_image_id
string<uuid>

Uploaded person image. Supply this or person_image_url.

person_image_url
string<uri>

Direct URL of a person photo.

person_version_id
string<uuid>

Optional source version belonging to person_image_id.

outfit_asset_id
string<uuid>

Reusable outfit asset. Supply an outfit asset, image, or URL.

outfit_image_id
string<uuid>

Uploaded garment image.

outfit_image_url
string<uri>

Direct garment photo URL.

outfit_asset_ids
string<uuid>[]

Multiple garment assets; supported models only.

Maximum array length: 3

Resource ID.

outfit_image_ids
string<uuid>[]

Multiple garment uploads; supported models only.

Maximum array length: 3

Resource ID.

outfit_image_urls
string<uri>[]

Multiple garment URLs; supported models only.

Maximum array length: 3
model
string

Use nano-banana-2 for this example. Other model availability and multi-outfit support vary.

Example:

"nano-banana-2"

resolution
enum<string>
default:standard

Output quality. Send explicitly. Pixel dimensions depend on the image model.

Available options:
standard,
high
Example:

"standard"

num_images
integer
default:1

Number of outputs. Defaults to 1. Account limits still apply.

Required range: 1 <= x <= 8
Example:

1

prompt
string

Optional styling instructions.

speed
string

Processing option. fast is used in the example; accepted values depend on the model.

Example:

"fast"

create_version
boolean
default:false

false returns an array of new jobs. true links a version to the person image and returns that parent image.

asset_ids
string[]

Additional reusable reference asset IDs. Supported types depend on the operation.

aspect_ratio
string

Optional model-dependent output ratio.

style
string

Optional style directions.

seed
integer

Optional seed; it does not guarantee identical results.

cf_turnstile_response
string

Embedded storefront metadata. Omit for standard Studio integrations.

shopify_product_id
string

Embedded storefront metadata. Omit for standard Studio integrations.

shopify_customer_id
string

Embedded storefront metadata. Omit for standard Studio integrations.

shopify_product_handle
string

Embedded storefront metadata. Omit for standard Studio integrations.

shopify_product_title
string

Embedded storefront metadata. Omit for standard Studio integrations.

customer_email
string

Embedded storefront metadata. Omit for standard Studio integrations.

Response

By default returns an array of pending jobs. With create_version=true, returns the person image with a newly linked version; track that version’s source_image_id.

id
string<uuid>
required

Resource ID.

status
enum<string>
required

Job state. Only completed has a finished result.

Available options:
pending,
generating,
completed,
failed,
policy_blocked,
nsfw_filtered
path
string | null

Result URL. Can be null while the job is pending.

watermarked_path
string | null
width_px
integer | null
height_px
integer | null
size_bytes
integer | null
extension
string | null
is_generated
boolean
for_training
boolean

Whether the upload is a reusable asset reference.

task
string | null

Operation that created this job.

type
string | null
created_timestamp
string<date-time>
finish_timestamp
string<date-time> | null
fail_reason
string | null

Human-readable failure detail.

failure_code
enum<string> | null

Machine-readable failure category, when available.

Available options:
input_rejected,
provider_unavailable,
queue_timeout,
policy_blocked
asset_ids
string<uuid>[] | null

Linked reusable assets.

Resource ID.

versions
object[]

Related versions. May be omitted or empty. Never infer a new version is completed from the parent status.