Förmåga · Smycken

API för smyckes-try-on för halsband, ringar, armband och örhängen

I en mening

Phottas API för smyckes-try-on tar ett smyckesfoto, en jewelry_type (halsband, ring, armband eller örhängen) och ett provdocke-ID och returnerar ett närbildsfoto på modell. Gör POST, polla var 3:e sekund, ladda ned när status är completed.

  • Typisk tid: 1.5–4 min
  • Credits: 5 credits vid 2K · 6 credits vid 4K
  • Bearbetning: asynkron, polling
  • Gränser: 600 requests/min
  • Autentisering: Bearer-nyckel

Varje siffra på den här sidan kommer från Photter API-dokumentationen · kontrollerad

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
Exempelutdata

I korthet

I korthet

Endpoint
POST /api/v1/tryon/jewelry
Autentisering
Bearer API-nyckel
Bearbetning
Asynkron — polla status-endpointen
Typisk tid
1.5–4 min
Credits
5 credits vid 2K · 6 credits vid 4K
Bildförhållanden
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Indatagränser
Upp till 10 MB per bild; JPEG, PNG, WebP
Idempotent
Nej

Request och 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-parametrar

jewelry_image

Typ: stringObligatorisk

URL or base64 data URI of the jewelry product image.

jewelry_type

Typ: stringObligatorisk

Type of jewelry.

Värden: necklaceearringsbraceletring
mannequin_id

Typ: stringObligatorisk

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

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

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

Värden: 2K4K
aspect_ratio

Typ: string

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

= 3:4

Värden: 3:41:14:39:1616:9
user_instruction

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

Fel

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.

Gränser

  • 600 anrop per minut per API-nyckel (Fast fönster; gränsen är densamma på alla planer)
  • En 429 innehåller Retry-After: 30 sekunder
  • Upp till 10 MB per bild
  • Format: JPEG, PNG, WebP
  • Samtidiga batcher per plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Endast polling — API:et skickar inga webhooks.

Klädflödet, finjusterat för små högreflekterande föremål

Välj en närbildsdocka, skicka, polla, ladda ner.

  1. Steg 1

    Generera en API-nyckel

    Samma flöde som för kläder — ai.photta.app → Developers → Generate API key. En nyckel fungerar för alla endpoints; ett credits-saldo täcker varje funktion.

  2. Steg 2

    Välj en närbildsdocka

    Lista smyckesdockorna eller ladda upp din egen med `POST /api/v1/mannequins/jewelry` — Photta tillhandahåller en specialbyggd uppsättning närbildsdockor med hudtexturer anpassade för små metaller och stenar.

  3. Steg 3

    POST:a smyckesjobbet

    Gör en POST till `/api/v1/tryon/jewelry` med `jewelry_image`, `jewelry_type`, `mannequin_id` och valfria `background`, `resolution` och `aspect_ratio`. Tjänsten autoskalar placeringen efter smyckeskategorin.

  4. Steg 4

    Polla tills jobbet slutförs

    Gör en GET till `/api/v1/tryon/jewelry/:id` var 3:e sekund. Svarsstrukturen är identisk med kläder — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. Steg 5

    Ladda ner och spara

    Tät beskärning 1:1 fungerar bäst för PDP-miniatyrer; bredare bildformat för redaktionellt innehåll. Lagra byten själv istället för att direktlänka från CDN:et.

Frågor utvecklare ställer innan de driftsätter smyckes-try-on

Vilka smyckestyper stöds?

Fyra explicita kategorier: halsband, ring, armband, örhängen. Varje kategori har sin egen uppsättning specialbyggda närbildsdockor och en placeringsheuristik anpassad för just den formfaktorn. Ringar och örhängen drar störst nytta av bildformatet 1:1; halsband gör sig bra i 3:4.

Hur mycket kostar en smyckes-try-on?

Samma som kläder: 5 credits i 2K, 6 credits i 4K. Misslyckade jobb återbetalas automatiskt. Inga extra avgifter för biblioteket med närbildsdockor.

Hur skiljer sig smyckes-endpointen från kläder?

Samma autentisering, samma polling-mönster, samma svarsstruktur — skillnaderna ligger i request-bodyn. Du skickar `jewelry_type` och `jewelry_image` istället för `product_type` och `product_images`, och du väljer dockor filtrerade på smyckeskategori. Allt annat (2K/4K, bildformat, credits) delas.

Kan jag ladda upp min egen smyckesmodell?

Ja — `POST /api/v1/mannequins/jewelry` accepterar en anpassad närbildsreferens, `POST /api/v1/mannequins/jewelry/generate` skapar en ny utifrån parametrar. Båda returnerar ett ID som du skickar tillbaka in i try-on-anropet.

Hur hanterar den reflekterande metaller och ädelstenar?

Närbildspipelinen hanterar metadata om speglingar och mikrogeometri. Guld, silver och spegelblankt platina renderas korrekt utan den ghosting eller kromatiska utsmetning som generella try-on-pipelines ger upphov till. Extremt rena studiobakgrunder rekommenderas för bästa resultat.

Hur pollar jag efter resultatet?

Gör en GET till `/api/v1/tryon/jewelry/:id` var 3:e till 5:e sekund. Samma statuslivscykel som för kläder: `processing` → `completed` eller `failed`. Ett tidsfönster på 1.5 till 4 minuter täcker den absoluta majoriteten av jobben.

Relaterade funktioner

Varje siffra på den här sidan kommer från Photter API-dokumentationen · kontrollerad

Testa API:et på fem minuter

Generera en Photta API-nyckel, klistra in cURL-kodfragmentet ovan, och du har din första bild på en modell innan kaffet har bryggts klart.

  • 1.5–4 min
  • 5 credits vid 2K · 6 credits vid 4K
  • asynkron, polling
  • 600 requests/min
  • Bearer-nyckel