Skip to content
Figur

Dispatch the converged garment × presets catalog-shot journey

POST
/v1/catalog-shots
curl --request POST \
  --url https://example.com/v1/catalog-shots \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "garment_image_asset_refs": [ "01JUPLOAD0000000000000000A" ], "product_title": "Emerald Silk Saree", "model_preset_id": "01MODELMODELMODELMODELMO00", "background_preset_id": "01BGBGBGBGBGBGBGBGBGBGBG00", "shot_preset_id": "01SHOTSHOTSHOTSHOTSHOTSH00" }'

Dispatch a catalog shot: compose one or more client-owned garment images onto a chosen model + background + shot preset in a single pass. Pass garment asset refs (from POST /v1/uploads) plus the three preset ids from GET /v1/presets (model/background/shot). Portrait is server-pinned; model + quality are optional (quality is gpt-image-family only). Returns 202 immediately with a job_id; poll GET /v1/jobs/{job_id} for the final render — its result artifact carries the signed image URL and echoes the four input refs in meta. Priced as a compose op; refunded automatically on any failure path.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
X-Shopify-Hmac-Sha256
Any of:
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
CatalogShotRequest

POST /v1/catalog-shots — the converged garment × presets journey (TRI-232).

A single flat request that pins the whole catalog shoot: the client-owned garment image asset refs (from POST /v1/uploads / the assets registry) + a product title + three preset ids (model / background / shot, from GET /v1/presets). The gateway derives ownership from the authenticated principal and forwards to studio’s internal catalog-shot dispatch — the caller never supplies client_id/tenant_id.

Portrait is server-pinned (studio fixes aspect_ratio 2:3, the canonical output shape); the only optional knobs are model (the image-generation model, forwarded as studio’s image_model) and quality (gpt-image output tier — a no-op for non-gpt models, which studio’s provider router silently drops).

object
garment_image_asset_refs
required
Garment Image Asset Refs

One or more client-owned product image asset refs (from POST /v1/uploads or the assets registry). Capped server-side at the generation model’s max input images.

Array<string>
>= 1 items
product_title
required
Product Title

Human-readable product title for the shot.

string
>= 1 characters <= 256 characters
model_preset_id
required
Model Preset Id

Model preset id (GET /v1/presets?kind=model).

string
>= 26 characters <= 26 characters
background_preset_id
required
Background Preset Id

Background preset id (GET /v1/presets?kind=background).

string
>= 26 characters <= 26 characters
shot_preset_id
required
Shot Preset Id

Shot preset id (GET /v1/presets?kind=shot).

string
>= 26 characters <= 26 characters
model
Any of:
string
quality
Any of:
string
Allowed values: medium high
Examples
Examplebasic

One garment onto a model + background + shot preset

{
  "garment_image_asset_refs": [
    "01JUPLOAD0000000000000000A"
  ],
  "product_title": "Emerald Silk Saree",
  "model_preset_id": "01MODELMODELMODELMODELMO00",
  "background_preset_id": "01BGBGBGBGBGBGBGBGBGBGBG00",
  "shot_preset_id": "01SHOTSHOTSHOTSHOTSHOTSH00"
}

Responses

Section titled “Responses”

202

Section titled “202”

Accepted — job queued. Poll /v1/jobs/{job_id} for the result.

Media typeapplication/json
WorkflowAcceptedResponse

Returned synchronously from any POST /v1/{name} (202).

object
request_id
required
Request Id

26-char ULID — correlates with the row in credit_operations.

string
job_id
required
Any of:
string
status
JobStatus

Studio’s job status at submit time. Almost always NOT_STARTED in this 202.

string
default: NOT_STARTED
Allowed values: NOT_STARTED SUCCESS FAILURE IN_PROGRESS
credits_cost
required
Credits Cost

Credits deducted from the calling client. Refunded automatically on any failure path.

integer
Example
{
  "request_id": "01JREQREQREQREQREQREQREQ00",
  "job_id": "01JOBJOBJOBJOBJOBJOBJOBJOB0",
  "status": "NOT_STARTED",
  "credits_cost": 10
}

402

Section titled “402”

Insufficient credit balance — the request cost exceeds the client’s balance. No job created.

Media typeapplication/json
Example
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Account balance is below the cost of this request.",
    "request_id": "01JREQREQREQREQREQREQREQ00"
  }
}

422

Section titled “422”

Request body failed validation (missing/invalid fields). No credits charged.

Media typeapplication/json
Example
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body or parameters failed validation.",
    "request_id": "01JREQREQREQREQREQREQREQ00"
  }
}

429

Section titled “429”

Per-credential rate limit exceeded. Retry after a short backoff.

Media typeapplication/json
Example
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded; try again shortly.",
    "request_id": "01JREQREQREQREQREQREQREQ00"
  }
}