Functionaliteit · Sieraden

Sieraden try-on API voor kettingen, ringen, armbanden en oorbellen

In één zin

Photta's sieraden try-on API accepteert een sieradenfoto, een jewelry_type (ketting, ring, armband of oorbellen) en een mannequin-ID en levert een close-up foto op een model op. POST, poll elke 3 seconden, download zodra de status completed is.

  • Typische duur: 1.5–4 min
  • Credits: 5 credits bij 2K · 6 credits bij 4K
  • Verwerking: async, polling
  • Limieten: 600 requests/min
  • Authenticatie: Bearer key

Elk getal op deze pagina is afkomstig uit de Photta-API-documentatie · gecontroleerd

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
Voorbeelduitvoer

In één oogopslag

In één oogopslag

Endpoint
POST /api/v1/tryon/jewelry
Authenticatie
Bearer API key
Verwerking
Asynchroon — poll het status-endpoint
Typische duur
1.5–4 min
Credits
5 credits bij 2K · 6 credits bij 4K
Beeldverhoudingen
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Invoerlimieten
Tot 10 MB per afbeelding; JPEG, PNG, WebP
Idempotent
Nee

Request en response

Request

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"
}

Request-parameters

jewelry_image

Type: stringVereist

URL or base64 data URI of the jewelry product image.

jewelry_type

Type: stringVereist

Type of jewelry.

Waarden: necklaceearringsbraceletring
mannequin_id

Type: stringVereist

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

Type: 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

Type: 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

Waarden: 2K4K
aspect_ratio

Type: string

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

= 3:4

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

Type: 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.

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

Limieten

  • 600 verzoeken per minuut per API key (Vast venster; de limiet is identiek op elk abonnement)
  • Een 429 bevat Retry-After: 30 seconden
  • Tot 10 MB per afbeelding
  • Formaten: JPEG, PNG, WebP
  • Gelijktijdige batches per abonnement: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Uitsluitend polling — de API stuurt geen webhooks.

De kledingflow, opnieuw afgesteld voor kleine sterk reflecterende items

Kies een close-up mannequin, verzend, poll, download.

  1. Stap 1

    Genereer een API-sleutel

    Zelfde flow als kleding — ai.photta.app → Developers → Generate API key. Eén sleutel werkt op elk endpoint; één creditsaldo dekt elke functionaliteit.

  2. Stap 2

    Kies een close-up mannequin

    Vraag de sieradenmannequins op of upload uw eigen met `POST /api/v1/mannequins/jewelry` — Photta onderhoudt een speciaal gebouwde set close-up mannequins met huidtexturen die zijn afgestemd op piepklein metaal en steen.

  3. Stap 3

    POST de sieradenjob

    POST naar `/api/v1/tryon/jewelry` met `jewelry_image`, `jewelry_type`, `mannequin_id` en optioneel `background`, `resolution` en `aspect_ratio`. De service schaalt de plaatsing automatisch voor de sieradencategorie.

  4. Stap 4

    Poll totdat de job is voltooid

    GET `/api/v1/tryon/jewelry/:id` elke 3 seconden. Response-structuur is identiek aan kleding — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. Stap 5

    Download en bewaar

    Strak bijgesneden 1:1 werkt het best voor PDP-thumbnails; bredere beeldverhoudingen voor editorial. Sla de bytes zelf op in plaats van het hotlinken van het CDN.

Vragen die developers stellen voor het implementeren van sieraden-try-on

Welke sieradentypes worden ondersteund?

Vier expliciete categorieën: necklace, ring, bracelet, earrings. Elke categorie heeft zijn eigen set speciaal gebouwde close-up mannequins en een plaatsingsheuristiek afgestemd op die vormfactor. Ringen en oorbellen profiteren het meest van een 1:1-beeldverhouding; kettingen komen goed tot hun recht op 3:4.

Hoeveel kost een sieraden-try-on?

Hetzelfde als kleding: 5 credits bij 2K, 6 credits bij 4K. Mislukte jobs worden automatisch terugbetaald. Geen toeslag voor de bibliotheek met close-up mannequins.

Waarin verschilt het sieraden-endpoint van kleding?

Zelfde authenticatie, zelfde polling-patroon, zelfde response-structuur — de verschillen zitten in de request-body. U verstuurt `jewelry_type` en `jewelry_image` in plaats van `product_type` en `product_images`, en u kiest mannequins gefilterd op sieradencategorie. Al het andere (2K/4K, beeldverhoudingen, credits) wordt gedeeld.

Kan ik mijn eigen sieradenmodel uploaden?

Ja — `POST /api/v1/mannequins/jewelry` accepteert een aangepaste close-up referentie, `POST /api/v1/mannequins/jewelry/generate` genereert een nieuwe op basis van opties. Beide retourneren een ID die u weer invoert in de try-on-request.

Hoe gaat het om met reflecterende metalen en edelstenen?

De close-up pipeline bevat metadata over spiegelende reflecties en microgeometrie. Goud, zilver en spiegelgepolijst platina renderen correct zonder de ghosting of chromatische vegen die generieke try-on pipelines produceren. Ultrastrakke studio-achtergronden worden aanbevolen voor de beste resultaten.

Hoe poll ik voor het resultaat?

GET `/api/v1/tryon/jewelry/:id` elke 3 tot 5 seconden. Zelfde status-lifecycle als kleding: `processing` → `completed` of `failed`. Een venster van 1.5 tot 4 minuten dekt de overgrote meerderheid van de jobs.

Gerelateerde functionaliteiten

Elk getal op deze pagina is afkomstig uit de Photta-API-documentatie · gecontroleerd

Probeer de API in vijf minuten

Genereer een Photta API-sleutel, plak het bovenstaande cURL-fragment en je hebt je eerste afbeelding op een model voordat de koffie klaar is.

  • 1.5–4 min
  • 5 credits bij 2K · 6 credits bij 4K
  • async, polling
  • 600 requests/min
  • Bearer key