Funzionalità · Gioielli

API try-on per gioielli per collane, anelli, bracciali e orecchini

In sintesi

L'API di try-on per gioielli di Photta riceve una foto del gioiello, un jewelry_type (collana, anello, bracciale o orecchini) e un mannequin ID, restituendo una foto del modello in primo piano. POST, polling ogni 3 secondi, download quando lo stato è completed.

Ottieni una chiave APILeggi la documentazione
  • Tempo tipico: 1.5–4 min
  • Credits: 5 credits a 2K · 6 credits a 4K
  • Elaborazione: asincrono, polling
  • Limiti: 600 richieste/min
  • Autenticazione: Chiave Bearer

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato

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
Esempio di output

Panoramica

Panoramica

Endpoint
POST /api/v1/tryon/jewelry
Autenticazione
API key Bearer
Elaborazione
Asincrona — effettua il polling dell'endpoint di stato
Tempo tipico
1.5–4 min
Credits
5 credits a 2K · 6 credits a 4K
Rapporti d'aspetto
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limiti di input
Fino a 10 MB per immagine; JPEG, PNG, WebP
Idempotente
No

Richiesta e risposta

Richiesta

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 / Completato

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

Parametri della richiesta

jewelry_image

Tipo: stringObbligatorio

URL or base64 data URI of the jewelry product image.

jewelry_type

Tipo: stringObbligatorio

Type of jewelry.

Valori: necklaceearringsbraceletring
mannequin_id

Tipo: stringObbligatorio

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

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

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

Valori: 2K4K
aspect_ratio

Tipo: string

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

= 3:4

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

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

Errori

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.

Limiti

  • 600 richieste al minuto per API key (Finestra fissa; il limite è lo stesso per ogni piano)
  • Un 429 restituisce Retry-After: 30 secondi
  • Fino a 10 MB per immagine
  • Formati: JPEG, PNG, WebP
  • Batch simultanei per piano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Solo polling — l'API non invia webhook.

Il flusso dell'abbigliamento, ricalibrato per articoli piccoli e altamente riflettenti

Scegli un manichino in primo piano, invia, effettua il polling, scarica.

  1. Passaggio 1

    Genera una chiave API

    Stesso flusso dell'abbigliamento — ai.photta.app → Developers → Generate API key. Una sola chiave funziona su ogni endpoint; un unico saldo di credits copre tutte le capability.

  2. Passaggio 2

    Scegli un manichino in primo piano

    Elenca i manichini per gioielli o carica i tuoi con `POST /api/v1/mannequins/jewelry` — Photta gestisce un set dedicato di manichini in primo piano con texture della pelle ottimizzate per metalli e pietre di piccole dimensioni.

  3. Passaggio 3

    Invia il job di gioielleria tramite POST

    Invia una richiesta POST a `/api/v1/tryon/jewelry` con `jewelry_image`, `jewelry_type`, `mannequin_id` e i parametri opzionali `background`, `resolution` e `aspect_ratio`. Il servizio ridimensiona automaticamente il posizionamento per la categoria del gioiello.

  4. Passaggio 4

    Effettua il polling fino al completamento del job

    Esegui una GET `/api/v1/tryon/jewelry/:id` ogni 3 secondi. La struttura della risposta è identica a quella dell'abbigliamento — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. Passaggio 5

    Scarica e salva in locale

    Il ritaglio stretto 1:1 funziona al meglio per le miniature delle PDP; formati più ampi per gli scatti editoriali. Salva direttamente i byte invece di fare hot-linking al CDN.

Lo stesso endpoint in Node.js, Python e cURL

Domande che gli sviluppatori si pongono prima di lanciare il try-on per gioielli

Quali tipologie di gioielli sono supportate?

Quattro categorie esplicite: necklace, ring, bracelet, earrings. Ciascuna categoria ha il proprio set dedicato di manichini in primo piano e un'euristica di posizionamento ottimizzata per quel form factor. Anelli e orecchini rendono al meglio nel formato 1:1; le collane sono ottimali in 3:4.

Quanto costa un try-on di gioielleria?

Uguale all'abbigliamento: 5 credits a 2K, 6 credits a 4K. I job falliti vengono rimborsati automaticamente. Nessun sovrapprezzo per la libreria di manichini in primo piano.

In cosa differisce l'endpoint per i gioielli da quello per l'abbigliamento?

Stessa autenticazione, stesso pattern di polling, stessa struttura di risposta — le differenze sono nel body della richiesta. Invii `jewelry_type` e `jewelry_image` al posto di `product_type` e `product_images`, e selezioni manichini filtrati per categoria di gioiello. Tutto il resto (2K/4K, aspect ratio, credits) è condiviso.

Posso caricare il mio modello di gioielleria personalizzato?

Sì — `POST /api/v1/mannequins/jewelry` accetta un riferimento in primo piano personalizzato, `POST /api/v1/mannequins/jewelry/generate` ne genera uno nuovo a partire dai parametri. Entrambi restituiscono un ID da reinserire nella richiesta di try-on.

Come vengono gestiti i metalli riflettenti e le pietre preziose?

La pipeline per primi piani include metadati sui riflessi speculari e sulla micro-geometria. Oro, argento e platino lucidato a specchio vengono renderizzati correttamente senza l'effetto ghosting o le sbavature cromatiche prodotte dalle pipeline di try-on generiche. Per risultati ottimali si raccomandano sfondi da studio ultra-puliti.

Come effettuo il polling per ottenere il risultato?

Esegui una GET `/api/v1/tryon/jewelry/:id` ogni 3-5 secondi. Stesso ciclo di vita dello status dell'abbigliamento: `processing` → `completed` o `failed`. Una finestra compresa tra 1.5 e 4 minuti copre la stragrande maggioranza dei job.

Capability correlate

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato

Prova l'API in 5 minuti

Genera una chiave API di Photta, incolla lo snippet cURL qui sopra e otterrai la tua prima immagine con modello prima ancora che il caffè sia pronto.

Crea un account e ottieni una chiave APILeggi la documentazione
  • 1.5–4 min
  • 5 credits a 2K · 6 credits a 4K
  • asincrono, polling
  • 600 richieste/min
  • Chiave Bearer