Funktion · Schmuck

Jewelry-Try-on-API für Halsketten, Ringe, Armbänder und Ohrringe

In aller Kürze

Die Jewelry-Try-on-API von Photta nimmt ein Schmuckfoto, einen jewelry_type (Halskette, Ring, Armband oder Ohrringe) und eine Mannequin-ID entgegen und liefert ein Nahaufnahme-Foto am Model. POST senden, alle 3 Sekunden pollen, herunterladen, sobald der Status completed ist.

  • Typische Dauer: 1.5–4 min
  • Credits: 5 Credits bei 2K · 6 Credits bei 4K
  • Verarbeitung: asynchron, Polling
  • Limits: 600 Anfragen/Min.
  • Authentifizierung: Bearer-Key

Jeder Zahlenwert auf dieser Seite stammt aus der Photta-API-Dokumentation · geprüft

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
Beispielausgabe

Auf einen Blick

Auf einen Blick

Endpoint
POST /api/v1/tryon/jewelry
Authentifizierung
Bearer-API-Schlüssel
Verarbeitung
Asynchron — Polling über den Status-Endpoint
Typische Dauer
1.5–4 min
Credits
5 Credits bei 2K · 6 Credits bei 4K
Seitenverhältnisse
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Eingabelimits
Bis zu 10 MB pro Bild; JPEG, PNG, WebP
Idempotent
Nein

Request und 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 / Abgeschlossen

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

jewelry_image

Typ: stringErforderlich

URL or base64 data URI of the jewelry product image.

jewelry_type

Typ: stringErforderlich

Type of jewelry.

Werte: necklaceearringsbraceletring
mannequin_id

Typ: stringErforderlich

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

Werte: 2K4K
aspect_ratio

Typ: string

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

= 3:4

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

Fehler

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.

Limits

  • 600 Anfragen pro Minute pro API-Schlüssel (Festes Zeitfenster; das Limit ist in jedem Tarif identisch)
  • Ein 429 enthält Retry-After: 30 Sekunden
  • Bis zu 10 MB pro Bild
  • Formate: JPEG, PNG, WebP
  • Gleichzeitige Batches pro Tarif: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Nur Polling — die API sendet keine Webhooks.

Der Apparel-Flow, feinabgestimmt auf kleine, stark reflektierende Objekte

Close-up-Mannequin wählen, absenden, pollen, herunterladen.

  1. Schritt 1

    API-Key generieren

    Gleicher Flow wie bei Apparel — ai.photta.app → Developers → Generate API key. Ein Key funktioniert für jeden Endpoint; ein Credit-Guthaben deckt jede Funktion ab.

  2. Schritt 2

    Close-up-Mannequin wählen

    Schmuck-Mannequins abrufen oder eigene per `POST /api/v1/mannequins/jewelry` hochladen — Photta bietet ein eigens entwickeltes Set an Close-up-Mannequins mit Hauttexturen, die für winzige Metalle und Steine optimiert sind.

  3. Schritt 3

    Schmuck-Job per POST absenden

    POST an `/api/v1/tryon/jewelry` mit `jewelry_image`, `jewelry_type`, `mannequin_id` sowie optional `background`, `resolution` und `aspect_ratio`. Der Dienst skaliert die Platzierung für die Schmuckkategorie automatisch.

  4. Schritt 4

    Pollen, bis der Job abgeschlossen ist

    GET `/api/v1/tryon/jewelry/:id` alle 3 Sekunden. Die Response-Struktur ist identisch mit Apparel — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. Schritt 5

    Herunterladen und persistieren

    Ein enger 1:1-Beschnitt eignet sich am besten für PDP-Thumbnails; breitere Seitenverhältnisse für Editorial-Inhalte. Speichern Sie die Bytes selbst, anstatt das CDN per Hotlinking einzubinden.

Fragen, die Entwickler vor dem Rollout von Schmuck-Try-on stellen

Welche Schmucktypen werden unterstützt?

Vier explizite Kategorien: necklace, ring, bracelet, earrings. Jede Kategorie verfügt über ein eigenes Set an speziell abgestimmten Close-up-Mannequins und eine auf diesen Formfaktor optimierte Platzierungsheuristik. Ringe und Ohrringe profitieren am meisten vom Seitenverhältnis 1:1; Halsketten wirken bei 3:4 optimal.

Wie viel kostet ein Schmuck-Try-on?

Gleich wie Apparel: 5 Credits bei 2K, 6 Credits bei 4K. Fehlgeschlagene Jobs werden automatisch erstattet. Kein Aufpreis für die Close-up-Mannequin-Bibliothek.

Wie unterscheidet sich der Schmuck-Endpoint von Apparel?

Gleiche Authentifizierung, gleiches Polling-Muster, gleiche Response-Struktur — die Unterschiede liegen im Request-Body. Sie übergeben `jewelry_type` und `jewelry_image` statt `product_type` und `product_images` und wählen Mannequins gefiltert nach Schmuckkategorie aus. Alles andere (2K/4K, Seitenverhältnisse, Credits) wird geteilt.

Kann ich mein eigenes Schmuck-Model hochladen?

Ja — `POST /api/v1/mannequins/jewelry` akzeptiert eine eigene Close-up-Referenz, `POST /api/v1/mannequins/jewelry/generate` erzeugt eine neue basierend auf Optionen. Beide liefern eine ID zurück, die Sie in den Try-on-Request einbinden.

Wie werden reflektierende Metalle und Edelsteine gehandhabt?

Die Close-up-Pipeline verarbeitet Metadaten zu Glanzlichtern und Mikrogeometrie. Gold, Silber und spiegelpoliertes Platin werden korrekt gerendert – ohne Ghosting oder chromatische Schlieren, wie sie bei universellen Try-on-Pipelines auftreten. Für optimale Ergebnisse werden ultra-saubere Studiohintergründe empfohlen.

Wie polle ich das Ergebnis?

GET `/api/v1/tryon/jewelry/:id` alle 3 bis 5 Sekunden. Identischer Status-Lebenszyklus wie bei Apparel: `processing` → `completed` oder `failed`. Ein Zeitfenster von 1.5 bis 4 Minuten deckt die überwiegende Mehrheit der Jobs ab.

Verwandte Funktionen

Jeder Zahlenwert auf dieser Seite stammt aus der Photta-API-Dokumentation · geprüft

Testen Sie die API in fünf Minuten

Generieren Sie einen Photta-API-Schlüssel, fügen Sie das obige cURL-Snippet ein, und Sie erhalten Ihr erstes Bild am Model, noch bevor der Kaffee fertig gebrüht ist.

  • 1.5–4 min
  • 5 Credits bei 2K · 6 Credits bei 4K
  • asynchron, Polling
  • 600 Anfragen/Min.
  • Bearer-Key