Dispatch a model-generator workflow

POST

/v1/model-generator

curl --request POST \
  --url https://example.com/v1/model-generator \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "image_model": "example", "eval_enabled": true, "resolution": "example", "aspect_ratio": "example", "seed": 1, "on_technical_failure": "example", "generation_stage": "portrait", "display_name": "", "gender": "MALE", "ethnicity": "indian", "heritage": "himalayan_north", "body_type": "slim", "age_range": "18-22", "model_spec_public_id": "example", "portrait_image_public_id": "example", "metadata": {}, "pilot_brand": "example" }'

Authorizations

• sk_*

Parameters

Header Parameters

X-Shopify-Hmac-Sha256

Any of:

string

string

null

null

Request Body^required

Media typeapplication/json

ModelGeneratorRequest

POST /v1/model-generator — portrait identity or approved full-body carry.

object

image_model

Any of:

string

string

null

null

eval_enabled

Any of:

boolean

boolean

null

null

resolution

Any of:

string

string

null

null

aspect_ratio

Any of:

string

string

null

null

seed

Any of:

integer

integer

null

null

on_technical_failure

Any of:

string

string

null

null

generation_stage

ModelGenerationStage

Which half of the portrait-first journey a generation request is asking for.

portrait mints a fresh model spec from a casting profile. full_body carries an already-approved portrait into a full-length catalog base and accepts no casting fields, because the identity is already fixed.

string

default: portrait

Allowed values: portrait full_body

display_name

Display Name

Human-readable name for the catalog entry. Optional — when omitted, studio coins an evocative catalog name during generation.

string

""

gender

Any of:

UserCategory

UserCategory

User gender category.

string

Allowed values: MALE FEMALE

null

null

ethnicity

Any of:

ModelEthnicity

ModelEthnicity

The fixed, operator-facing casting-heritage groups for v1.

string

Allowed values: indian pakistani_bangladeshi sri_lankan_nepali east_asian southeast_asian middle_eastern central_asian north_african west_african east_african southern_african black_diaspora afro_caribbean northern_european southern_european eastern_european latin_american indigenous_american pacific_islander mixed_heritage

null

null

heritage

Any of:

IndianHeritage

IndianHeritage

The single nested level deliberately offered after selecting India.

string

Allowed values: himalayan_north punjabi_northwest gangetic_central western_coastal eastern_bengali south_indian

null

null

body_type

Any of:

ModelBodyType

ModelBodyType

Four neutral UI labels; prompt wording is gender-aware downstream.

string

Allowed values: slim athletic balanced fuller

null

null

age_range

Any of:

ModelAgeRange

ModelAgeRange

Adult-only catalog age bands requested for the Studio input surface.

string

Allowed values: 18-22 22-26 26-30 30-34 34-40

null

null

model_spec_public_id

Any of:

string

string

null

null

portrait_image_public_id

Any of:

string

string

null

null

metadata

Metadata

object

key

additional properties

any

pilot_brand

Any of:

string

string

null

null

Responses

202

Successful Response

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

string

null

null

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

{
  "status": "NOT_STARTED"
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Example^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}