Funksjon · Smykker

API for smykke-try-on for halskjeder, ringer, armbånd og øredobber

I én setning

Phottas smykke-try-on-API tar et smykkebilde, en jewelry_type (halskjede, ring, armbånd eller øredobber) og en utstillingsdukke-ID, og returnerer et nærbilde på modell. POST, poll hvert 3. sekund, last ned når status er completed.

  • Typisk tidsbruk: 1.5–4 min
  • Credits: 5 credits ved 2K · 6 credits ved 4K
  • Prosessering: asynkron, polling
  • Grenser: 600 forespørsler/min
  • Autentisering: Bearer-nøkkel

Hvert tall på denne siden er hentet fra dokumentasjonen for Photta-API-et · verifisert

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
Eksempel på respons

Kort oppsummert

Kort oppsummert

Endepunkt
POST /api/v1/tryon/jewelry
Autentisering
Bearer API-nøkkel
Prosessering
Asynkron – poll status-endepunktet
Typisk tidsbruk
1.5–4 min
Credits
5 credits ved 2K · 6 credits ved 4K
Bildeformater
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Inndatagrenser
Opptil 10 MB per bilde; JPEG, PNG, WebP
Idempotent
Nei

Forespørsel og respons

Forespørsel

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

Forespørselsparametere

jewelry_image

Type: stringPåkrevd

URL or base64 data URI of the jewelry product image.

jewelry_type

Type: stringPåkrevd

Type of jewelry.

Verdier: necklaceearringsbraceletring
mannequin_id

Type: stringPåkrevd

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

Verdier: 2K4K
aspect_ratio

Type: string

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

= 3:4

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

Feil

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.

Grenser

  • 600 forespørsler per minutt per API-nøkkel (Fast tidsvindu; grensen er lik for alle abonnementer)
  • En 429 inneholder Retry-After: 30 sekunder
  • Opptil 10 MB per bilde
  • Formater: JPEG, PNG, WebP
  • Samtidige batcher per abonnement: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Kun polling – API-et sender ikke webhooks.

Klesflyten, finjustert for små, svært reflekterende gjenstander

Velg en nærbildemannekeng, send inn, poll, last ned.

  1. Trinn 1

    Generer en API-nøkkel

    Samme flyt som for klær — ai.photta.app → Developers → Generate API key. Én nøkkel fungerer på tvers av alle endepunkter; én credit-saldo dekker alle kapabiliteter.

  2. Trinn 2

    Velg en nærbildemannekeng

    List ut smykkemannekengene eller last opp din egen med `POST /api/v1/mannequins/jewelry` — Photta vedlikeholder et spesialtilpasset sett med nærbildemannekenger med hudteksturer optimalisert for små metall- og steindetaljer.

  3. Trinn 3

    POST smykkejobben

    POST til `/api/v1/tryon/jewelry` med `jewelry_image`, `jewelry_type`, `mannequin_id` og valgfrie `background`, `resolution` og `aspect_ratio`. Tjenesten autoskalerer plasseringen tilpasset smykkekategorien.

  4. Trinn 4

    Poll til jobben er fullført

    GET `/api/v1/tryon/jewelry/:id` hvert 3. sekund. Responsen har identisk struktur som for klær — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. Trinn 5

    Last ned og lagre

    Tett beskjæring i 1:1 fungerer best for PDP-miniatyrbilder; bredere sideforhold for redaksjonelt innhold. Lagre bytene selv fremfor å hotlenke til CDN-et.

Spørsmål utviklere stiller før de lanserer try-on for smykker

Hvilke smykketyper støttes?

Fire eksplisitte kategorier: necklace, ring, bracelet, earrings. Hver kategori har sitt eget sett med spesialbygde nærbildemannekenger og en plasseringsheuristikk tilpasset formfaktoren. Ringer og øredobber drar mest nytte av 1:1-sideforhold; halskjeder fungerer godt i 3:4.

Hvor mye koster en smykke-try-on?

Samme som for klær: 5 credits i 2K, 6 credits i 4K. Feilede jobber refunderes automatisk. Ingen ekstra kostnad for biblioteket med nærbildemannekenger.

Hvordan skiller smykke-endepunktet seg fra klær?

Samme autentisering, samme pollingmønster, samme responsstruktur — forskjellene ligger i forespørselskroppen. Du sender `jewelry_type` og `jewelry_image` i stedet for `product_type` og `product_images`, og du velger mannekenger filtrert etter smykkekategori. Alt annet (2K/4K, sideforhold, credits) er felles.

Kan jeg laste opp min egen smykkemodell?

Ja — `POST /api/v1/mannequins/jewelry` godtar en egendefinert nærbildereferanse, `POST /api/v1/mannequins/jewelry/generate` genererer en ny basert på alternativer. Begge returnerer en ID du sender tilbake i try-on-forespørselen.

Hvordan håndteres reflekterende metaller og edelstener?

Nærbildepipelinen inneholder metadata om speilende høylys og mikrogeometri. Gull, sølv og speilblankt platina gjengis korrekt uten ghosting eller kromatisk utsmøring som oppstår i generiske try-on-pipelines. Helt rene studiobakgrunner anbefales for best resultat.

Hvordan poller jeg etter resultatet?

GET `/api/v1/tryon/jewelry/:id` hvert 3. til 5. sekund. Samme statuslivssyklus som for klær: `processing` → `completed` eller `failed`. Et vindu på 1,5 til 4 minutter dekker de aller fleste jobber.

Relaterte kapabiliteter

Hvert tall på denne siden er hentet fra dokumentasjonen for Photta-API-et · verifisert

Prøv API-et på fem minutter

Generer en Photta API-nøkkel, lim inn cURL-kodesnutten ovenfor, og du har ditt første bilde på modell før kaffen er ferdig traktet.

  • 1.5–4 min
  • 5 credits ved 2K · 6 credits ved 4K
  • asynkron, polling
  • 600 forespørsler/min
  • Bearer-nøkkel