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
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')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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."
},
)
data = res.json()["data"] # data["id"], data["status"]
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')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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."
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "jwl_a1b2c3",
"status": "completed",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"resolution": "2K",
"aspect_ratio": "3:4",
"output_url": "https://cdn.photta.app/generated/jwl_a1b2c3.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/jwl_a1b2c3-thumb.jpg",
"credits_used": 5,
"created_at": "2026-04-10T14:00:00Z",
"completed_at": "2026-04-10T14:01:10Z",
"duration_ms": 70000
},
"request_id": "req_jwl002"
}Request-Parameter
jewelry_imageTyp: stringErforderlich
URL or base64 data URI of the jewelry product image.
jewelry_typeTyp: stringErforderlich
Type of jewelry.
Werte:necklaceearringsbraceletringmannequin_idTyp: 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.
backgroundTyp: 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.
resolutionTyp: 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:2K4Kaspect_ratioTyp: string
Output aspect ratio. 1:1 is not available at 4K resolution — that combination returns 400.
= 3:4
Werte:3:41:14:39:1616:9user_instructionTyp: 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
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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.
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.
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.
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.
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`.
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.
Derselbe Endpoint in Node.js, Python und cURL
Node.js
Jewelry-Try-on-API in Node.js
Rufen Sie Phottas jewelry-Try-on-API von einem Node.js-Backend mit nativem fetch auf. Kein SDK erforderlich: Key speichern, Job absenden, Ergebnis pollen.
LesenPython
Jewelry-Try-on-API in Python
Rufen Sie Phottas jewelry-Try-on-API in Python mit der requests-Bibliothek auf. Dreißigzeiliger Wrapper, async-kompatibel über httpx, funktioniert in Django, FastAPI und Celery.
LesencURL
Jewelry-Try-on-API mit cURL
Rufen Sie Phottas jewelry-Try-on-API direkt über die Shell mit cURL auf. Übermitteln, pollen, herunterladen — jedes Snippet lässt sich für skriptbasierte Pipelines mit jq kombinieren.
Lesen
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
Funktionen
Virtuelle Try-on-API für Apparel
REST-API zur Platzierung von Bekleidung auf KI-Mannequins. Asynchron, 1.5–4 Minuten Generierungsdauer, 5 credits bei 2K, 6 bei 4K. Beispiele für cURL, Node.js und Python.
Zum EndpointFunktionen
Ghost-Mannequin-API für Hollow-Man-Produktfotos
KI-Ghost-Mannequin-Endpoint. Entfernt die Puppe aus einem Kleidungsfoto und bewahrt Innendetails. 3D oder Flat-Lay, Batch-Verarbeitung, 4 Credits bei 2K.
Zum EndpointBuild
Einen Service für KI-Produktfotografie aufbauen
Das Gründer-Playbook für den Weiterverkauf der Virtual-Try-on-API von Photta als White-Label-SaaS: Mandanten-Keys, Batch-Fanout, Abrechnung nach Credits, SLA-Realität.
Zum EndpointVergleich
Photta vs FASHN — Fashion-KI-APIs im direkten Vergleich
Photta und FASHN im Vergleich: Endpoints, Credit-Preise, Tarifstufen, Concurrency-Limits. Direkt bezogen von den Preisseiten beider Unternehmen am 2026-04-19. Keine erfundenen Zahlen.
Zum EndpointVergleich
Photta vs. Ayna — Entwickler-API oder Shopify-first-Studio
Photta vs. Ayna im Vergleich: drei REST-Endpoints vs. ein Shopify-fokussiertes Studio + API. Beide haben Stärken. Daten von den jeweiligen Websites vom 2026-04-19.
Zum EndpointSchnellstart
Erstes Photta-Bild in unter 5 Minuten.
Registrieren, API-Key generieren, ersten cURL-Aufruf ausführen, pollen bis zum Abschluss, Ergebnis persistieren. 5 Schritte, durchgängig dokumentiert.
Zum EndpointReferenz
Photta API-Fehler
Die vollständige Liste der Photta API-Fehlertypen samt Statuscodes, das Format des Error-Bodys und welche Fehler sich für einen Retry eignen.
Zum EndpointReferenz
Photta API Rate Limits
Das Photta API Rate Limit, sein Zeitfenster, der Retry-After-Header, das Polling-Intervall und die tarifbasierten Concurrency-Limits, alles direkt aus der API-Dokumentation.
Zum Endpoint
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