Kyvykkyys · Vaatteet

Virtuaalinen try-on API vaatteille

Yhdellä lauseella

Phottan virtuaalinen try-on API ottaa vastaan tasokuvatun vaatekuvan, mallinukke-ID:n sekä asento-ID:n ja palauttaa 2K- tai 4K-mallikuvan. Tee POST työstä, tee polling 3–5 sekunnin välein ja lataa tulos, kun tila on completed.

Hanki API-avain Lue dokumentaatio

Tyypillinen kesto: 1.5–4 min
Credits: 5 credits resoluutiolla 2K · 6 credits resoluutiolla 4K
Käsittely: asynkroninen, polling
Rajoitukset: 600 pyyntöä/min
Autentikointi: Bearer-avain

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu 2026-09-10

POST/api/v1/tryon/apparel

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/tryon/apparel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_type": "top",
    "product_images": [
      "https://cdn.yourstore.com/products/shirt-front.jpg"
    ],
    "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
    "product_category": "t_shirt",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "body_size": "M",
    "expression": "neutral",
    "user_instruction": "Keep the collar pattern crisp and centered."
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/tryon/apparel",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_type": "top",
      "product_images": [
        "https://cdn.yourstore.com/products/shirt-front.jpg"
      ],
      "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
      "product_category": "t_shirt",
      "mannequin_id": "mnk_f3a9b1",
      "pose_id": "pose_c2d4e5",
      "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
      "lock_background": True,
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "body_size": "M",
      "expression": "neutral",
      "user_instruction": "Keep the collar pattern crisp and centered."
    },
)
data = res.json()["data"]  # data["id"], data["status"]

A garment rendered on an AI model by the apparel try-on API — Esimerkkitulos

Lyhyesti

Endpoint: POST /api/v1/tryon/apparel
Autentikointi: Bearer-API-avain
Käsittely: Asynkroninen — tee polling-kyselyitä status-endpointiin
Tyypillinen kesto: 1.5–4 min
Credits: 5 credits resoluutiolla 2K · 6 credits resoluutiolla 4K
Kuvasuhteet: 3:4 · 1:1 · 4:3 · 9:16 · 16:9
Syöterajoitukset: Enintään 10 MB per kuva; JPEG, PNG, WebP
Idempotentti: Ei

Pyyntö ja vastaus

Pyyntö

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/tryon/apparel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_type": "top",
    "product_images": [
      "https://cdn.yourstore.com/products/shirt-front.jpg"
    ],
    "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
    "product_category": "t_shirt",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "body_size": "M",
    "expression": "neutral",
    "user_instruction": "Keep the collar pattern crisp and centered."
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/tryon/apparel",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_type": "top",
      "product_images": [
        "https://cdn.yourstore.com/products/shirt-front.jpg"
      ],
      "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
      "product_category": "t_shirt",
      "mannequin_id": "mnk_f3a9b1",
      "pose_id": "pose_c2d4e5",
      "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
      "lock_background": True,
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "body_size": "M",
      "expression": "neutral",
      "user_instruction": "Keep the collar pattern crisp and centered."
    },
)
data = res.json()["data"]  # data["id"], data["status"]

202 Accepted / Completed

{
  "data": {
    "id": "try_abc123",
    "status": "processing",
    "product_type": "top",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-04-10T12:00:00Z"
  },
  "request_id": "req_xyz789"
}

{
  "data": {
    "id": "try_abc123",
    "status": "completed",
    "product_type": "top",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "output_url": "https://cdn.photta.app/generated/try_abc123.jpg",
    "thumbnail_url": "https://cdn.photta.app/generated/try_abc123-thumb.jpg",
    "credits_used": 5,
    "created_at": "2026-04-10T12:00:00Z",
    "completed_at": "2026-04-10T12:01:15Z",
    "duration_ms": 75000
  },
  "request_id": "req_abc001"
}

Pyyntöparametrit

KenttäKuvaus

product_type

Tyyppi: stringPakollinen

Type of garment.

topbottomtop_and_bottomone_piece

product_images

Tyyppi: array[string]Pakollinen

Array of image URLs or base64 data URIs. The first entry is the FRONT image and is required. Not used when product_type is "top_and_bottom".

product_back_image

Tyyppi: string

Optional URL or base64 data URI for the BACK of the garment. When supplied, the pipeline auto-switches to the back image whenever the selected pose is back-facing (Back / BackCloseUp). Not used when product_type is "top_and_bottom".

top_image

Tyyppi: string

Front image of the top garment. Required when product_type is "top_and_bottom".

top_back_image

Tyyppi: string

Optional back image of the top garment. Auto-selected on back-facing poses when present.

bottom_image

Tyyppi: string

Front image of the bottom garment. Required when product_type is "top_and_bottom".

bottom_back_image

Tyyppi: string

Optional back image of the bottom garment. Auto-selected on back-facing poses when present.

mannequin_id

Tyyppi: stringPakollinen

ID of the mannequin to wear the garment. Use GET /api/v1/mannequins to list available options.

pose_id

Tyyppi: stringPakollinen

ID of the pose. Use GET /api/v1/poses to list available options. The pose dictates the framing of the output — what's in frame, whether the face/feet are visible, full body vs half body, etc.

background

Tyyppi: string

Optional URL or base64 data URI to a background photo. Anything that is not a URL or data: URI is rejected with HTTP 400. When omitted, an editorial neutral backdrop is used.

lock_background

Tyyppi: boolean

When true, the supplied background image is reproduced faithfully (locked) instead of being treated as loose inspiration. Requires the background field — returns 400 if set without a background. Echoed back in the response object.

= false

resolution

Tyyppi: string

Output resolution. 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

2K4K

aspect_ratio

Tyyppi: string

Output aspect ratio. 1:1 cannot be combined with resolution 4K — that combination returns 400.

= 3:4

3:41:14:39:1616:9

body_size

Tyyppi: string

Body size of the mannequin.

= M

XSSMLXLXXL

expression

Tyyppi: string

Facial expression.

= neutral

neutralhappyserioussmiling

footwear_url

Tyyppi: string

URL or base64 of a custom footwear image. The pipeline always stages the footwear when supplied; the prompt's pose-authority block decides whether to render it (poses that don't show feet drop it cleanly).

user_instruction

Tyyppi: string

Free-form refinement, e.g. "preserve the seam pattern across the shoulder", "keep the collar contrast strong". Capped at 500 characters server-side; longer strings are silently truncated. Useful for brand-specific details that need an extra nudge.

product_category

Tyyppi: string

Optional silhouette anchor for the garment (e.g. "t_shirt", "jeans", "blazer", "midi_dress"). Helps disambiguate the structure of the garment when the silhouette is ambiguous from the photo alone. Used for product_type "top", "bottom", and "one_piece".

top_category

Tyyppi: string

Silhouette anchor for the top half. Only valid when product_type is "top_and_bottom".

bottom_category

Tyyppi: string

Silhouette anchor for the bottom half. Only valid when product_type is "top_and_bottom".

length

Tyyppi: string

Garment length key for product_type "top", "bottom", or "one_piece". List available values with GET /api/v1/garment-attributes?type=length&garment_type={product_type}.

fit

Tyyppi: string

Garment fit key for product_type "top", "bottom", or "one_piece". List available values with GET /api/v1/garment-attributes?type=fit&garment_type={product_type}.

top_length

Tyyppi: string

Top length key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=length&garment_type=top.

top_fit

Tyyppi: string

Top fit key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=fit&garment_type=top.

bottom_length

Tyyppi: string

Bottom length key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=length&garment_type=bottom.

bottom_fit

Tyyppi: string

Bottom fit key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=fit&garment_type=bottom.

Virheet

TilaTyyppiMerkitys

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. Retry later.

Rajoitukset

600 pyyntöä minuutissa per API-avain (Kiinteä aikaikkuna; rajoitus on sama kaikissa tilauksissa)
Vastaus 429 sisältää otsakkeen Retry-After: 30 sekuntia
Enintään 10 MB per kuva
Formaatit: JPEG, PNG, WebP
Rinnakkaiset eräajot per tilaus: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
Vain polling — API ei lähetä webhookeja.

Viisi vaihetta, yksi tuotekuva

Valitse mallinukke, lähetä työ, tee pollingia valmistumiseen asti, lataa tulos.

Vaihe 1
Luo API-avain
Rekisteröidy osoitteessa ai.photta.app, avaa Developers-välilehti ja klikkaa Generate API key. Live-avaimet alkavat tunnisteella `photta_live_`. Aseta avain muuttujaan `PHOTTA_API_KEY` — älä koskaan commitoi sitä.
Vaihe 2
Valitse mallinukke ja asento
GET `/api/v1/mannequins` listaa saatavilla olevat vaihtoehdot. GET `/api/v1/poses` määrittää rajauksen. Molemmat ID:t viedään try-on-pyyntöön.
Vaihe 3
Tee POST try-on-työlle
Lähetä POST-pyyntö polkuun `/api/v1/tryon/apparel` kentillä `product_type`, `product_images`, `mannequin_id`, `pose_id` sekä valinnaisilla kentillä `resolution` ja `aspect_ratio`. API palauttaa 202 Accepted ja generointi-ID:n.
Vaihe 4
Tee pollingia, kunnes työ valmistuu
GET `/api/v1/tryon/apparel/:id` 3 sekunnin välein. Kun `data.status` muuttuu tilaan `completed`, payload sisältää kentät `output_url` ja `thumbnail_url`. Aseta yläraja, jotta jumiutunut työ ei jätä pyyntöä roikkumaan.
Vaihe 5
Lataa ja tallenna pysyvästi
Nouda tavut osoitteesta `output_url` ja tallenna ne omaan objektitallennukseesi. CDN-URL on vakaa, mutta tuotteesi ei pitäisi riippua siitä renderöinnissä.

Sama endpoint kielillä Node.js, Python ja cURL

Kysymyksiä, joita kehittäjät kysyvät ennen vaatteiden try-on-ominaisuuden julkaisua

Mikä on Phottan virtuaalinen try-on-API?

REST-endpoint, joka ottaa flat-lay-tuotekuvan sekä mallinuken ID:n ja palauttaa fotorealistisen kuvan mallin päällä. Sama putki kuin Phottan kuluttajasovelluksessa. Neljä tuotetyyppiä tuettuina: top, bottom, top+bottom, one-piece.

Paljonko kutsu maksaa?

5 credits 2K-tuloksesta, 6 credits 4K-tuloksesta. Krediitit sisältyvät tilaukseesi ja niitä voi ladata lisää. Epäonnistuneet generoinnit eivät kuluta krediittejä — ne hyvitetään.

Kauanko generointi kestää?

Tyypillinen valmistumisaika on 1.5–4 minuuttia alusta loppuun mitattuna. POST-pyyntö palauttaa generointi-ID:n alle sekunnissa; GPU-työ tapahtuu taustalla pollingin aikana.

Mitä tuotetyyppejä tuetaan?

Neljää: `top`, `bottom`, `top_and_bottom`, `one_piece`. Kukin odottaa erilaista `product_images`-rakennetta — esimerkiksi `top_and_bottom` vaatii sekä `top_image`- että `bottom_image`-URL-osoitteet.

Voinko käyttää omaa mallinukkea?

Kyllä. Lataa mallinuken kuva kutsulla `POST /api/v1/mannequins` tai luo uusi tekoälymallinukke kutsulla `POST /api/v1/mannequins/generate`. Palautettu ID kytketään suoraan try-on-pyyntöön.

Miten teen pollingia tuloksen saamiseksi?

GET `/api/v1/tryon/apparel/:id` 3–5 sekunnin välein, kunnes `data.status` on `completed` tai `failed`. Aseta yrityksille yläraja — 120 × 3s kattaa dokumentoidun aikaikkunan reilusti.

Liittyvät kyvykkyydet

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu 2026-09-10

Kokeile APIa viidessä minuutissa

Luo Photta-API-avain, liitä yllä oleva cURL-koodinpätkä, ja sinulla on ensimmäinen mallikuva ennen kuin kahvi ehtii tippua.

Luo tili ja hanki API-avain Lue dokumentaatio

1.5–4 min
5 credits resoluutiolla 2K · 6 credits resoluutiolla 4K
asynkroninen, polling
600 pyyntöä/min
Bearer-avain

Virtuaalinen try-on API vaatteille

Lyhyesti

Pyyntö ja vastaus

Pyyntöparametrit

Virheet

Viisi vaihetta, yksi tuotekuva

Luo API-avain

Valitse mallinukke ja asento

Tee POST try-on-työlle

Tee pollingia, kunnes työ valmistuu

Lataa ja tallenna pysyvästi

Sama endpoint kielillä Node.js, Python ja cURL

Kysymyksiä, joita kehittäjät kysyvät ennen vaatteiden try-on-ominaisuuden julkaisua

Liittyvät kyvykkyydet

Kokeile APIa viidessä minuutissa