Garment recolor

Start a new job

POST
/garment-recolor

Recolor one named (or auto-detected) garment consistently across a set of images. Each input image yields num_variations outputs. The recolor target is a reference pattern/colour image, a colour/text instruction, or both (at least one required). Only the chosen garment is changed; everything else in the image is preserved, and the recolor stays consistent across the whole set. The render tier (1K/2K/4K) bills per output by tier.

Authorization

token_auth
headerAuthorizationBearer <token>

Token-based authentication using access tokens.

Request Body

application/json
  1. body
ai_retouch?Ai Retouch

auto: once the AI reviewer has checked the outputs, the AI retoucher fixes what it flagged on each image, once, without being asked. Each fixed image costs the AI retouch price, charged only when an image is fixed. Enterprise only for now, and not with review_config (images in a review round are retouched from the review screen); otherwise ignored. quality_summary.settled on GET /jobs//results, or the job_quality notification, tells when it is done.

Default"off"
Value in"off""auto"
project_id*Project Id

Project key where images are stored.

images*array<string>

UUIDs of uploaded images, each containing the garment to recolor.

Items1 <= items <= 10
garment_label?|

Optional garment to recolor, e.g. 't-shirt', 'jacket', 'hat'. Name up to two garments to recolor together, separated by a comma, '+', '&' or 'and' (e.g. 'top, shorts' for a bikini or an activewear set). When empty, the most-probable clothing item is detected automatically.

Defaultnull
reference_image?|

Optional UUID of ONE pattern/colour reference image to recolor toward.

Defaultnull
reference_text?|

Optional textual colour/pattern reference, e.g. a hex code '#2E5A3B' or a colour name. An alternative to reference_image when the user has no swatch.

Defaultnull
instruction?|

Optional free-form recolor instruction, e.g. 'make it forest green'. At least one of reference_image / reference_text / instruction must be provided.

Defaultnull
num_variations?Num Variations

Variations per input image (1-8). Output shape is len(images) x num_variations.

Default1
model?Model

Generation engine (auto | nano_banana_2 | nano_banana_pro | seedream | gpt_image).

Default"auto"
processing_size?|

Processing quality: low | medium | high, or the px tier 1024 | 2048 | 4096 (default 2048 = medium). The size the garment area is generated at before it is fitted back into the image; outputs keep the input's dimensions. Drives credit cost (3 / 5 / 10 credits per output); higher quality takes longer.

Default2048
format?Format

Output file format (png | jpg). Default png: lossless, so pixels outside the recolored garment stay byte-identical to the input. jpg gives smaller files.

Default"png"
Value in"png""jpg"
post_process?Post Process

Enable a finishing pass that keeps the recolored garment tones consistent across the set.

Defaulttrue
use_anchor?|

Keep the recolored garment visually consistent across the whole set. Only applies when the job produces more than one output. Defaults on (None -> enabled) to preserve prior behaviour.

Defaultnull
add_ai_watermark?Add Ai Watermark

Bake an 'AI-generated' disclosure mark into each output (irreversible).

Defaultfalse
review_config?|

Optional review configuration. If provided, creates a review pipeline for this job. Fields: requires_review (bool), default_reviewer_type (str), default_retouch_method (str), auto_approve_threshold (float).

Defaultnull
post_process_only?Post Process Only

Skip generation and only shift the detected garment's colour to target_hex with image processing (admin only; ignored for other users).

Defaultfalse
target_hex?|

Target colour as '#RRGGBB'. Required when post_process_only is set.

Defaultnull

Response Body

Successful Response

application/json
  1. response
job_id*Job Id

The ID of the created garment recolor job.

status*Status

The initial status of the job.

message*Message

A message indicating the job creation status.

total_outputs*Total Outputs

Number of outputs the job will produce (images x variations).

curl -X POST "https://example.com/garment-recolor" \  -H "Content-Type: application/json" \  -d '{    "project_id": "string",    "images": [      "string"    ]  }'
{  "job_id": "string",  "status": "string",  "message": "string",  "total_outputs": 0}