Możliwość · Biżuteria

API try-on biżuterii dla naszyjników, pierścionków, bransoletek i kolczyków

W jednym zdaniu

API try-on biżuterii od Photta przyjmuje zdjęcie biżuterii, parametr jewelry_type (naszyjnik, pierścionek, bransoletka lub kolczyki) oraz identyfikator manekina i zwraca zdjęcie w zbliżeniu na modelu. Wyślij POST, odpytuj co 3 sekundy, pobierz, gdy status to completed.

  • Typowy czas: 1.5–4 min
  • Credits: 5 credits w 2K · 6 credits w 4K
  • Przetwarzanie: asynchroniczne, polling
  • Limity: 600 requests/min
  • Uwierzytelnianie: Klucz Bearer

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono

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
Przykładowy wynik

W skrócie

W skrócie

Endpoint
POST /api/v1/tryon/jewelry
Uwierzytelnianie
Klucz API Bearer
Przetwarzanie
Asynchroniczne — odpytuj endpoint statusu
Typowy czas
1.5–4 min
Credits
5 credits w 2K · 6 credits w 4K
Proporcje obrazu
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limity wejściowe
Do 10 MB na obraz; JPEG, PNG, WebP
Idempotentne
Nie

Żądanie i odpowiedź

Żądanie

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

Parametry żądania

jewelry_image

Typ: stringWymagane

URL or base64 data URI of the jewelry product image.

jewelry_type

Typ: stringWymagane

Type of jewelry.

Wartości: necklaceearringsbraceletring
mannequin_id

Typ: stringWymagane

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

Wartości: 2K4K
aspect_ratio

Typ: string

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

= 3:4

Wartości: 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.

Błędy

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.

Limity

  • 600 żądań na minutę na klucz API (Stałe okno czasowe; limit jest taki sam w każdym planie)
  • Odpowiedź 429 zawiera nagłówek Retry-After: 30 s
  • Do 10 MB na obraz
  • Formaty: JPEG, PNG, WebP
  • Jednoczesne zadania wsadowe w zależności od planu: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Tylko polling — API nie wysyła webhooków.

Przepływ apparel, dostrojony do małych, silnie odbijających światło obiektów

Wybierz manekina close-up, wyślij żądanie, wykonaj polling, pobierz wynik.

  1. Krok 1

    Wygeneruj klucz API

    Taki sam przepływ jak w apparel — ai.photta.app → Developers → Generate API key. Jeden klucz działa we wszystkich endpointach; jedno saldo credits pokrywa wszystkie capabilities.

  2. Krok 2

    Wybierz manekina close-up

    Pobierz listę manekinów biżuterii lub prześlij własnego za pomocą `POST /api/v1/mannequins/jewelry` — Photta utrzymuje dedykowany zestaw manekinów close-up z teksturami skóry dostrojonymi do drobnych metali i kamieni.

  3. Krok 3

    Wyślij zadanie biżuterii metodą POST

    Wyślij żądanie POST do `/api/v1/tryon/jewelry` z polami `jewelry_image`, `jewelry_type`, `mannequin_id` oraz opcjonalnymi `background`, `resolution` i `aspect_ratio`. Usługa automatycznie skaluje rozmieszczenie dla danej kategorii biżuterii.

  4. Krok 4

    Wykonuj polling do momentu zakończenia zadania

    Wysyłaj GET `/api/v1/tryon/jewelry/:id` co 3 sekundy. Struktura odpowiedzi jest identyczna jak w apparel — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. Krok 5

    Pobierz i zapisz

    Ścisłe kadrowanie 1:1 sprawdza się najlepiej dla miniatur na PDP; szersze proporcje boków dla materiałów redakcyjnych. Zapisuj bajty u siebie zamiast bezpośredniego linkowania do CDN.

Pytania, które programiści zadają przed wdrożeniem try-on biżuterii

Jakie typy biżuterii są obsługiwane?

Cztery jawne kategorie: necklace, ring, bracelet, earrings. Każda kategoria posiada własny zestaw dedykowanych manekinów close-up oraz heurystykę rozmieszczenia dostrojoną do danego formatu. Pierścionki i kolczyki zyskują najwięcej na proporcjach 1:1; naszyjniki prezentują się dobrze w 3:4.

Ile kosztuje try-on biżuterii?

Tyle samo co apparel: 5 credits w 2K, 6 credits w 4K. Nieudane zadania są automatycznie refundowane. Brak dodatkowych opłat za bibliotekę manekinów close-up.

Czym endpoint biżuterii różni się od apparel?

To samo uwierzytelnianie, ten sam wzorzec pollingu, taka sama struktura odpowiedzi — różnice tkwią w treści żądania. Przesyłasz `jewelry_type` i `jewelry_image` zamiast `product_type` i `product_images`, oraz wybierasz manekiny przefiltrowane według kategorii biżuterii. Cała reszta (2K/4K, proporcje boków, credits) jest współdzielona.

Czy mogę przesłać własny model biżuterii?

Tak — `POST /api/v1/mannequins/jewelry` przyjmuje własny materiał referencyjny close-up, a `POST /api/v1/mannequins/jewelry/generate` generuje nowy na podstawie parametrów. Oba zwracają ID, które przekazujesz do żądania try-on.

Jak radzi sobie z refleksyjnymi metalami i kamieniami szlachetnymi?

Pipeline close-up przetwarza metadane dotyczące odblasków zwierciadlanych i mikrogeometrii. Złoto, srebro i polerowana na lustro platyna renderują się poprawnie, bez powidoków czy rozmyć chromatycznych generowanych przez uniwersalne pipeline'y try-on. W celu uzyskania najlepszych rezultatów zalecane są nieskazitelnie czyste tła studyjne.

Jak odpytywać o wynik (polling)?

Wysyłaj GET `/api/v1/tryon/jewelry/:id` co 3 do 5 sekund. Taki sam cykl życia statusu jak w apparel: `processing` → `completed` lub `failed`. Okno od 1.5 do 4 minut pokrywa zdecydowaną większość zadań.

Powiązane capabilities

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono

Wypróbuj API w 5 minut

Wygeneruj klucz Photta API, wklej powyższy snippet cURL, a otrzymasz swoje pierwsze zdjęcie na modelu, zanim zaparzy się kawa.

  • 1.5–4 min
  • 5 credits w 2K · 6 credits w 4K
  • asynchroniczne, polling
  • 600 requests/min
  • Klucz Bearer