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
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')const res = await fetch("https://api.photta.app/api/v1/mannequins/generate", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/mannequins/generate",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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')const res = await fetch("https://api.photta.app/api/v1/mannequins/generate", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/mannequins/generate",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "mmk_r4s5t6",
"status": "completed",
"mannequin": {
"id": "mnk_v7w8x9",
"name": "Generated Mannequin",
"gender": "female",
"thumbnail_url": "https://cdn.photta.app/mannequins/mnk_v7w8x9-thumb.jpg"
},
"credits_used": 4,
"created_at": "2026-04-10T14:00:00Z",
"completed_at": "2026-04-10T14:00:42Z",
"duration_ms": 42000
},
"request_id": "req_mnk003"
}Request parameters
categoryType: 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:FemaleMaleGirlChildBoyChildethnicityType: 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_otherageType: 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_13skin_toneType: string
Skin tone.
Values:lightlight_mediummediummedium_darkdarkface_shapeType: string
Face shape.
Values:ovalsquareroundheartoblongdiamondeye_colorType: string
Eye color.
Values:browndark_brownblackbluegreenhazelgrayambereye_shapeType: string
Eye shape.
Values:almondroundmonolidhoodedupturneddownturnedexpressionType: string
Facial expression.
Values:neutralsoft_smilewarm_smileseriousconfidentfriendlyfacial_hairType: string
Facial hair style (Male only).
Values:nonelight_stubblemedium_stubbleshort_beardfull_beardgoateemustachemakeupType: string
Makeup style (Female only).
Values:naturalminimalsoft_glamprofessionaleditorialhair_styleType: string
Hair style. Available options depend on category — use /options endpoint.
hair_colorType: string
Hair color.
Values:blackdark_brownmedium_brownlight_brownauburnredstrawberry_blondeblondeplatinum_blondegraywhitesalt_pepperhair_textureType: string
Hair texture.
Values:straightwavycurlycoilyafrobody_typeType: 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.
heightType: string
Height.
Values:shortaveragetallglassesType: string
Glasses.
Values:noneeyeglassessunglassesfrecklesType: string
Freckles.
Values:nonelightprominentpiercingsType: string
Piercings.
Values:noneearnosemultiple
Errors
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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.
Step 1
Generate an API key
Mannequin generation uses the same credentials and the same credit balance as every other Photta capability.
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.
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.
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.
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.
The same endpoint in Node.js, Python and cURL
Node.js
AI mannequin generation API in Node.js
Call Photta's aI mannequin generation API from a Node.js backend with native fetch. No SDK required: store your key, submit the job, poll for the result.
ReadPython
AI mannequin generation API in Python
Call Photta's aI mannequin generation API in Python with the requests library. Thirty-line wrapper, async-friendly via httpx, works in Django, FastAPI and Celery.
ReadcURL
AI mannequin generation API with cURL
Call Photta's aI mannequin generation API directly from the shell with cURL. Submit, poll, download — every snippet pairs with jq for scripted pipelines.
Read
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
Capabilities
Virtual try-on API for apparel
REST API that places apparel on AI mannequins. Asynchronous, 1.5–4 minute generation, 5 credits at 2K, 6 at 4K. cURL, Node.js and Python examples.
See the endpointCapabilities
Jewelry try-on API for necklaces, rings, bracelets and earrings
Place necklaces, rings, bracelets and earrings on AI models via REST. 5 credits at 2K, close-up mannequins built-in, reflection-aware rendering from the Photta docs.
See the endpointBuild
Build a virtual try-on feature for your app
End-to-end recipe for shipping a virtual try-on feature with the Photta API: upload, submit, poll from a worker, render the result. TypeScript + server-only patterns.
See the endpointCompare
Photta vs Fitroom — pick the right fit for fashion APIs
Photta and Fitroom compared on endpoints, credit cost per call, pricing model and integration surface. Pulled from each site on 2026-04-19. No made-up numbers.
See the endpointQuickstart
First Photta image in under five minutes.
Sign up, generate an API key, run your first cURL call, poll until it completes, persist the result. Five steps, documented end-to-end.
See the endpointReference
Photta API errors
The full list of Photta API error types with their status codes, the shape of an error body, and which failures are worth retrying.
See the endpointReference
Photta API rate limits
The Photta API rate limit, its window, the Retry-After header, the polling interval and the per-plan concurrency caps, all read from the API documentation.
See the endpoint
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