Kyvykkyys · Korut

Korujen try-on-API kaulakoruille, sormuksille, rannekoruille ja korvakoruille

Yhdellä lauseella

Phottan korujen try-on-API ottaa korukuvan, jewelry_type-tyypin (necklace, ring, bracelet tai earrings) sekä mallinuken ID:n ja palauttaa lähikuvan mallin päällä. POST, polling 3 sekunnin välein, lataus tilan ollessa completed.

  • 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

POST/api/v1/tryon/jewelry
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/jewelry \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
  "jewelry_type": "necklace",
  "mannequin_id": "mnk_j9k1l2",
  "background": "soft window light on dark velvet",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "Make the pendant 10% smaller."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
A necklace rendered on an AI model by the jewelry try-on API
Esimerkkitulos

Lyhyesti

Lyhyesti

Endpoint
POST /api/v1/tryon/jewelry
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/jewelry \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
  "jewelry_type": "necklace",
  "mannequin_id": "mnk_j9k1l2",
  "background": "soft window light on dark velvet",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "Make the pendant 10% smaller."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Completed

{
  "data": {
    "id": "jwl_a1b2c3",
    "status": "processing",
    "jewelry_type": "necklace",
    "mannequin_id": "mnk_j9k1l2",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-04-10T14:00:00Z"
  },
  "request_id": "req_jwl001"
}

Pyyntöparametrit

jewelry_image

Tyyppi: stringPakollinen

URL or base64 data URI of the jewelry product image.

jewelry_type

Tyyppi: stringPakollinen

Type of jewelry.

Arvot: necklaceearringsbraceletring
mannequin_id

Tyyppi: stringPakollinen

ID of the mannequin. Must be jewelry-compatible and have a matching close-up view for the given jewelry_type. Use GET /api/v1/mannequins?jewelry_type=necklace to find compatible mannequins.

background

Tyyppi: string

Optional. Pass a URL or base64 data URI to use a reference photo as the scene; pass any other string to use it as a free-form text description (e.g. "soft window light on dark velvet"). When omitted, the original mannequin backdrop is preserved.

resolution

Tyyppi: string

Output resolution. "2K" costs 5 credits per image; "4K" costs 6 credits per image. 4K is produced natively in a single generation — pick it upfront; the resolution cannot be changed after creation. 4K cannot be combined with aspect_ratio 1:1 (returns 400).

= 2K

Arvot: 2K4K
aspect_ratio

Tyyppi: string

Output aspect ratio. 1:1 is not available at 4K resolution — that combination returns 400.

= 3:4

Arvot: 3:41:14:39:1616:9
user_instruction

Tyyppi: string

Free-form refinement, e.g. "make the pendant 10% smaller", "keep the clasp visible at the back of the neck". Capped at 400 characters server-side; longer strings are silently truncated. Requests to change the jewelry's size, scale, or proportions are honored and take priority; any other instruction applies only where it does not conflict with reproducing the jewelry exactly from the reference image. Not a determinism or seed control.

Virheet

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.

Vaatevuo, hienosäädetty pienille ja voimakkaasti heijastaville tuotteille

Valitse lähikuvanukke, lähetä, pollaa, lataa.

  1. Vaihe 1

    Luo API-avain

    Sama vuo kuin vaatteille — ai.photta.app → Developers → Generate API key. Yksi avain toimii kaikissa endpointeissa; yksi credits-saldo kattaa kaikki toiminnot.

  2. Vaihe 2

    Valitse lähikuvanukke

    Listaa korunuket tai lataa omasi kutsulla `POST /api/v1/mannequins/jewelry` — Photta ylläpitää varta vasten rakennettua lähikuvanukkeiden valikoimaa, jonka ihon tekstuurit on optimoitu pienille metalleille ja kiville.

  3. Vaihe 3

    Lähetä korutyö POST-kutsulla

    Tee POST-kutsu kohteeseen `/api/v1/tryon/jewelry` parametreilla `jewelry_image`, `jewelry_type`, `mannequin_id` sekä valinnaisilla `background`, `resolution` ja `aspect_ratio`. Palvelu skaalaa asettelun automaattisesti korukategorian mukaan.

  4. Vaihe 4

    Pollaa, kunnes työ valmistuu

    Tee GET `/api/v1/tryon/jewelry/:id` 3 sekunnin välein. Vastauksen rakenne on identtinen vaatteiden kanssa — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. Vaihe 5

    Lataa ja tallenna pysyvästi

    Tiukka 1:1-rajaus toimii parhaiten PDP-pikkukuville; leveämmät kuvasuhteet toimitukselliseen sisältöön. Tallenna tavut itse CDN-suoralinkityksen sijaan.

Kysymykset, joita kehittäjät kysyvät ennen korujen try-on-toiminnon julkaisua

Mitä korutyyppejä tuetaan?

Neljää erillistä kategoriaa: necklace, ring, bracelet, earrings. Jokaisella kategorialla on oma valikoimansa varta vasten tehtyjä lähikuvanukkeja sekä kyseiselle muotokielelle optimoitu asetteluhierarkia. Sormukset ja korvakorut hyötyvät eniten 1:1-kuvasuhteesta; kaulakorut toimivat hyvin suhteessa 3:4.

Paljonko korujen try-on maksaa?

Sama kuin vaatteilla: 5 credits resoluutiolla 2K, 6 credits resoluutiolla 4K. Epäonnistuneet työt hyvitetään automaattisesti. Lähikuvanukkejen kirjastosta ei peritä lisämaksua.

Miten koru-endpoint eroaa vaatteista?

Sama autentikointi, sama pollauskäytäntö, sama vastauksen rakenne — erot ovat pyynnön bodyssa. Lähetät kentät `jewelry_type` ja `jewelry_image` kenttien `product_type` ja `product_images` sijaan, ja valitset nuket korukategorian mukaan suodatettuina. Kaikki muu (2K/4K, kuvasuhteet, credits) on jaettua.

Voinko ladata oman korumallini?

Kyllä — `POST /api/v1/mannequins/jewelry` hyväksyy mukautetun lähikuvaviitteen, `POST /api/v1/mannequins/jewelry/generate` luo uuden parametrien perusteella. Molemmat palauttavat ID:n, jonka syötät try-on-pyyntöön.

Miten se käsittelee heijastavia metalleja ja jalokiviä?

Lähikuvaputki sisältää metadataa peiliheijastuksista ja mikrogeometriasta. Kulta, hopea ja peilikiillotettu platina renderöityvät oikein ilman haamukuvia tai värivuotoja, joita yleiskäyttöiset try-on-putket tuottavat. Parhaan tuloksen saavuttamiseksi suositellaan erittäin selkeitä studiotaustoja.

Miten pollaan tulosta?

Tee GET `/api/v1/tryon/jewelry/:id` 3–5 sekunnin välein. Sama tilan elinkaari kuin vaatteilla: `processing` → `completed` tai `failed`. 1.5–4 minuutin ikkuna kattaa valtaosan töistä.

Liittyvät ominaisuudet

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

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.

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