Capability · Mannequin generation

AI mannequin generation API for your own models

In one sentence

Photta’s mannequin generation API builds a photorealistic AI model from attributes you choose, returns a reusable mannequin id, and costs 4 credits. Two builders: one for apparel, one tuned for jewelry close-ups.

  • Typical time: 30-60s
  • Credits: 4 credits
  • Processing: async, polling
  • Limits: 600 requests/min
  • Authentication: Bearer key

Every figure on this page comes from the Photta API docs · checked

POST/api/v1/mannequins/generate
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/mannequins/generate \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "Female",
  "ethnicity": "east_asian_korean",
  "age": "late_20s",
  "skin_tone": "light_medium",
  "expression": "neutral",
  "hair_style": "long_straight",
  "hair_color": "black",
  "body_type": "slim",
  "height": "average"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

At a glance

At a glance

Endpoint
POST /api/v1/mannequins/generate
Authentication
Bearer API key
Processing
Asynchronous — poll the status endpoint
Typical time
30-60s
Credits
4 credits
Input limits
Up to 10 MB per image; JPEG, PNG, WebP
Idempotent
No

Request and response

Request

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/mannequins/generate \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "Female",
  "ethnicity": "east_asian_korean",
  "age": "late_20s",
  "skin_tone": "light_medium",
  "expression": "neutral",
  "hair_style": "long_straight",
  "hair_color": "black",
  "body_type": "slim",
  "height": "average"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Completed

{
  "data": {
    "id": "mmk_r4s5t6",
    "status": "processing",
    "category": "Female",
    "credits_used": 4,
    "created_at": "2026-04-10T14:00:00Z"
  },
  "request_id": "req_mnk002"
}

Request parameters

category

Type: stringRequired

Mannequin category. CASE-SENSITIVE — "female" returns 400. And note that OMITTING it does not: the field defaults to "Female" server-side, so a request with no category is accepted and charges 4 credits for an adult female model. Always send it explicitly.

Values: FemaleMaleGirlChildBoyChild
ethnicity

Type: string

Ethnic appearance. 25 values — read them from GET /api/v1/mannequins/generate/options, which is the authority. Not validated: an unrecognised value is accepted, charged, and fed into the prompt as written.

Values: east_asian_koreaneast_asian_chinesesoutheast_asiansouth_asiancentral_asiannordicwestern_europeaneastern_europeanmediterraneanbritish_irishafricanafrican_americannorth_africanmiddle_easternpersianturkishlatin_americanbraziliannative_americanpolynesianaustralian_aboriginalmixed_asian_europeanmixed_african_europeanmixed_latin_europeanmixed_other
age

Type: string

Age range. CATEGORY-DEPENDENT: the first six apply to Male/Female, the last five to BoyChild/GirlChild. Nothing enforces the pairing — age "40s" with category "GirlChild" is accepted and charged. See age_ranges in /options.

Values: early_20slate_20searly_30slate_30s40s50sbaby_1toddler_2_4young_5_7child_8_10preteen_11_13
skin_tone

Type: string

Skin tone.

Values: lightlight_mediummediummedium_darkdark
face_shape

Type: string

Face shape.

Values: ovalsquareroundheartoblongdiamond
eye_color

Type: string

Eye color.

Values: browndark_brownblackbluegreenhazelgrayamber
eye_shape

Type: string

Eye shape.

Values: almondroundmonolidhoodedupturneddownturned
expression

Type: string

Facial expression.

Values: neutralsoft_smilewarm_smileseriousconfidentfriendly
facial_hair

Type: string

Facial hair style (Male only).

Values: nonelight_stubblemedium_stubbleshort_beardfull_beardgoateemustache
makeup

Type: string

Makeup style (Female only).

Values: naturalminimalsoft_glamprofessionaleditorial
hair_style

Type: string

Hair style. Available options depend on category — use /options endpoint.

hair_color

Type: string

Hair color.

Values: blackdark_brownmedium_brownlight_brownauburnredstrawberry_blondeblondeplatinum_blondegraywhitesalt_pepper
hair_texture

Type: string

Hair texture.

Values: straightwavycurlycoilyafro
body_type

Type: string

Body type. Depends on category: Male slim/lean/athletic/average/muscular/broad, Female slim/petite/athletic/average/curvy/plus_size, BoyChild and GirlChild slim/average/athletic. Read body_types from /options.

height

Type: string

Height.

Values: shortaveragetall
glasses

Type: string

Glasses.

Values: noneeyeglassessunglasses
freckles

Type: string

Freckles.

Values: nonelightprominent
piercings

Type: string

Piercings.

Values: noneearnosemultiple

Errors

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred (500), or a check your request needs could not run right now (503, e.g. moderation_unavailable). Retry later with backoff.

Limits

  • 600 requests per minute per account (Fixed window; the limit is the same on every plan)
  • A 429 carries Retry-After: 30 seconds
  • Up to 10 MB per image
  • Formats: JPEG, PNG, WebP
  • Concurrent batches per plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Polling only — the API sends no webhooks.

Attributes in, a reusable model out

Read the options, choose attributes, submit, poll, then reuse the id.

  1. Step 1

    Generate an API key

    Mannequin generation uses the same credentials and the same credit balance as every other Photta capability.

  2. Step 2

    Read the option catalogue

    GET `/api/v1/mannequins/generate/options` returns every accepted value, including the `hair_style` and `body_type` lists that differ by category. Drive your form from it rather than hardcoding the enums.

  3. Step 3

    POST the mannequin

    POST `/api/v1/mannequins/generate` with `category` — `Female`, `Male`, `GirlChild` or `BoyChild` — plus any of the 17 optional attributes: ethnicity, age, skin tone, face and eye shape, expression, facial hair, makeup, hair, body type, height, glasses, freckles and piercings.

  4. Step 4

    Poll until the job completes

    GET `/api/v1/mannequins/generate/:id` every 3 seconds until `data.status` is `completed` or `failed`; typical completion is 30 to 60 seconds.

  5. Step 5

    Reuse the mannequin

    The completed body carries a `mannequin` object with its own id. Pass that id as `mannequin_id` on later try-on or eyewear jobs and every shot keeps the same face.

Questions developers ask before generating models

What is an AI mannequin?

A generated model whose appearance you specify rather than cast. It is returned as an id, so the same face, hair and body can wear every garment in a catalogue.

How much does a mannequin cost?

4 credits, for both the apparel builder and the jewelry builder. Reusing an existing mannequin in a later shoot costs nothing extra — you pay for the try-on, not for the model.

Which attributes can I set?

`category` is required. Everything else is optional: ethnicity, age, skin tone, face shape, eye colour and shape, expression, facial hair, makeup, hair style, colour and texture, body type, height, glasses, freckles and piercings. The options endpoint lists the accepted values.

What is the jewelry builder for?

POST `/api/v1/mannequins/jewelry/generate` builds a model tuned for close-up jewelry work: it takes `jewelry_type`, `shot_type`, `camera_angle`, `background` and `lighting` instead of the full-body attributes, so the neckline, ear or hand reads correctly at close range.

Can I reuse the same model across shoots?

Yes — that is the point of the endpoint. The generated mannequin id is accepted as `mannequin_id` by apparel try-on, jewelry try-on and the eyewear studio.

How do I poll for the result?

GET `/api/v1/mannequins/generate/:id` every 3 seconds until `data.status` is `completed` or `failed`. The jewelry builder polls its own status path.

Related capabilities

Every figure on this page comes from the Photta API docs · checked

Try the API in five minutes

Generate a Photta API key, paste the cURL snippet above, and you'll have your first on-model image before the coffee finishes brewing.

  • 30-60s
  • 4 credits
  • async, polling
  • 600 requests/min
  • Bearer key