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
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')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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."
},
)
data = res.json()["data"] # data["id"], data["status"]
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')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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."
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "jwl_a1b2c3",
"status": "completed",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"resolution": "2K",
"aspect_ratio": "3:4",
"output_url": "https://cdn.photta.app/generated/jwl_a1b2c3.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/jwl_a1b2c3-thumb.jpg",
"credits_used": 5,
"created_at": "2026-04-10T14:00:00Z",
"completed_at": "2026-04-10T14:01:10Z",
"duration_ms": 70000
},
"request_id": "req_jwl002"
}Pyyntöparametrit
jewelry_imageTyyppi: stringPakollinen
URL or base64 data URI of the jewelry product image.
jewelry_typeTyyppi: stringPakollinen
Type of jewelry.
Arvot:necklaceearringsbraceletringmannequin_idTyyppi: 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.
backgroundTyyppi: 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.
resolutionTyyppi: 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:2K4Kaspect_ratioTyyppi: string
Output aspect ratio. 1:1 is not available at 4K resolution — that combination returns 400.
= 3:4
Arvot:3:41:14:39:1616:9user_instructionTyyppi: 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
- 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. 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.
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.
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.
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.
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`.
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.
Sama endpoint ympäristöissä Node.js, Python ja cURL
Node.js
Korujen try-on-API ympäristössä Node.js
Kutsu Phottan ominaisuutta korujen try-on-API Node.js-taustajärjestelmästä natiivilla fetchillä. SDK:ta ei tarvita: tallenna avaimesi, lähetä työ, pollaa tulosta.
LuePython
Korujen try-on-API Pythonissa
Kutsu Phottan korujen try-on-API -ominaisuutta Pythonissa requests-kirjaston avulla. Kolmenkymmenen rivin kääre, async-yhteensopiva httpx:n kautta, toimii Djangossa, FastAPIssa ja Celeryssä.
LuecURL
Korujen try-on-API cURLillä
Kutsu Phottan korujen try-on-API-rajapintaa suoraan komentoriviltä cURLin avulla. Lähetä, pollaa, lataa — jokainen koodinpätkä toimii yhdessä jq:n kanssa skriptatuissa putkissa.
Lue
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
Ominaisuudet
Virtuaalinen try-on API vaatteille
REST API, joka asettaa vaatteet tekoälymallinukkejen päälle. Asynkroninen, 1.5–4 minuutin generointi, 5 credits resoluutiolla 2K, 6 resoluutiolla 4K. cURL-, Node.js- ja Python-esimerkit.
Katso endpointOminaisuudet
Ghost mannequin API näkymättömän mallinuken tuotekuviin
Tekoälypohjainen ghost mannequin -endpoint. Poista nukke vaatekuvasta ja säilytä sisäpuolen yksityiskohdat. 3D tai flat-lay, eräajo, 4 credits resoluutiolla 2K.
Katso endpointRakenna
Rakenna AI-tuotekuvauspalvelu
Perustajan opas Phottan virtuaalisen try-on API:n jälleenmyyntiin white-label-SaaS-palveluna: tenant-avaimet, eräajojen hajautus, credit-pohjainen laskutus ja todellinen SLA.
Katso endpointVertailu
Photta vs FASHN — Muodin AI-rajapinnat rinnakkain
Photta ja FASHN vertailussa: endpointit, credit-hinnoittelu, tilaustasot, samanaikaisuusrajat. Perustuu kummankin yrityksen omaan hinnoittelusivuun 2026-04-19. Ei keksittyjä lukuja.
Katso endpointVertailu
Photta vs Ayna — kehittäjä-API vai Shopify-lähtöinen studio
Photta vs Ayna -vertailu: kolme REST-endpointia vastaan Shopify-lähtöinen studio + API. Molemmilla on vahvuutensa. Tiedot kerätty kummankin sivustolta 2026-04-19.
Katso endpointPikaopas
Ensimmäinen Photta-kuva alle viidessä minuutissa.
Rekisteröidy, luo API-avain, suorita ensimmäinen cURL-kutsusi, tee pollingia valmistumiseen asti ja tallenna tulos. Viisi vaihetta, dokumentoitu alusta loppuun.
Katso endpointReferenssi
Photta API -virheet
Täydellinen luettelo Photta API -virhetyypeistä statuskoodeineen, virheen rungon rakenne ja tiedot siitä, mitkä virheet kannattaa yrittää uudelleen.
Katso endpointReferenssi
Photta API:n rate limitit
Photta API:n rate limit, sen aikaikkuna, Retry-After-otsake, pollausväli ja tilauskohtaiset rinnakkaisuusrajat, kaikki API-dokumentaatiosta luettuna.
Katso endpoint
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