Fonctionnalité · Bijoux

API de try-on de bijoux pour colliers, bagues, bracelets et boucles d'oreilles

En une phrase

L'API de try-on de bijoux de Photta prend une photo de bijou, un jewelry_type (collier, bague, bracelet ou boucles d'oreilles) et un mannequin ID, puis renvoie une photo en gros plan portée sur modèle. POST, polling toutes les 3 secondes, téléchargement dès que le statut est completed.

Obtenir une clé API Consulter la documentation

Délai typique: 1.5–4 min
Crédits: 5 crédits en 2K · 6 crédits en 4K
Traitement: asynchrone, polling
Limites: 600 requêtes/min
Authentification: Clé Bearer

Chaque chiffre sur cette page provient de la documentation de l'API Photta · vérifié 2026-09-10

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')

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.status

import 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"]

A necklace rendered on an AI model by the jewelry try-on API — Exemple de sortie

En un coup d'œil

Endpoint: POST /api/v1/tryon/jewelry
Authentification: Clé API Bearer
Traitement: Asynchrone — interrogez l'endpoint de statut par polling
Délai typique: 1.5–4 min
Crédits: 5 crédits en 2K · 6 crédits en 4K
Rapports d'aspect: 3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limites d'entrée: Jusqu'à 10 Mo par image ; JPEG, PNG, WebP
Idempotent: Non

Requête et réponse

Requête

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.status

import 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 / Terminé

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

Paramètres de requête

ChampDescription

jewelry_image

Type: stringRequis

URL or base64 data URI of the jewelry product image.

jewelry_type

Type: stringRequis

Type of jewelry.

necklaceearringsbraceletring

mannequin_id

Type: stringRequis

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

2K4K

aspect_ratio

Type: string

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

= 3:4

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.

Erreurs

StatutTypeSignification

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.

Limites

600 requêtes par minute par clé API (Fenêtre fixe ; la limite est identique sur tous les forfaits)
Une 429 renvoie Retry-After: 30 secondes
Jusqu'à 10 Mo par image
Formats: JPEG, PNG, WebP
Lots simultanés par forfait: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
Polling uniquement — l'API n'envoie aucun webhook.

Le flux apparel, réajusté pour les petits articles hautement réfléchissants

Choisissez un mannequin gros plan, soumettez, effectuez le polling, téléchargez.

Étape 1
Générer une clé d'API
Même flux qu'apparel — ai.photta.app → Développeurs → Générer une clé d'API. Une seule clé fonctionne sur tous les endpoints ; un seul solde de credits couvre chaque fonctionnalité.
Étape 2
Choisir un mannequin gros plan
Listez les mannequins bijoux ou importez le vôtre avec `POST /api/v1/mannequins/jewelry` — Photta propose un ensemble dédié de mannequins en gros plan avec des textures de peau optimisées pour les métaux et pierres de petite taille.
Étape 3
Créer le job de bijou en POST
Envoyez un POST à `/api/v1/tryon/jewelry` avec `jewelry_image`, `jewelry_type`, `mannequin_id` et, en option, `background`, `resolution` et `aspect_ratio`. Le service adapte automatiquement le positionnement pour la catégorie de bijou.
Étape 4
Effectuer le polling jusqu'à la fin du job
Effectuez un GET sur `/api/v1/tryon/jewelry/:id` toutes les 3 secondes. La structure de réponse est identique à apparel — `data.status`, `data.output_url`, `data.thumbnail_url`.
Étape 5
Télécharger et persister
Un recadrage serré en 1:1 fonctionne le mieux pour les vignettes PDP ; des formats d'image plus larges pour l'éditorial. Stockez les octets chez vous plutôt que d'utiliser le CDN en lien direct.

Même endpoint en Node.js, Python et cURL

Questions des développeurs avant d'intégrer le try-on de bijoux

Quels types de bijoux sont pris en charge ?

Quatre catégories explicites : collier, bague, bracelet, boucles d'oreilles. Chaque catégorie dispose de son propre ensemble de mannequins gros plan dédiés et d'une heuristique de positionnement adaptée à ce format. Les bagues et les boucles d'oreilles tirent le meilleur parti du ratio 1:1 ; les colliers rendent bien en 3:4.

Combien coûte un try-on de bijou ?

Identique à apparel : 5 credits en 2K, 6 credits en 4K. Les jobs en échec sont automatiquement remboursés. Pas de supplément pour la bibliothèque de mannequins gros plan.

En quoi l'endpoint bijoux diffère-t-il d'apparel ?

Même authentification, même logique de polling, même structure de réponse — les différences résident dans le corps de la requête. Vous envoyez `jewelry_type` et `jewelry_image` au lieu de `product_type` et `product_images`, et vous choisissez des mannequins filtrés par catégorie de bijou. Tout le reste (2K/4K, ratios d'aspect, credits) est partagé.

Puis-je importer mon propre mannequin de bijou ?

Oui — `POST /api/v1/mannequins/jewelry` accepte une référence gros plan personnalisée, `POST /api/v1/mannequins/jewelry/generate` en génère une nouvelle selon des options. Les deux renvoient un identifiant à réinjecter dans la requête de try-on.

Comment gère-t-il les métaux réfléchissants et les pierres précieuses ?

Le pipeline gros plan intègre des métadonnées sur les reflets spéculaires et la micro-géométrie. L'or, l'argent et le platine poli miroir sont rendus avec précision, sans le ghosting ni le flou chromatique générés par les pipelines de try-on généralistes. Des fonds studio ultra-propres sont recommandés pour des résultats optimaux.

Comment récupérer le résultat par polling ?

GET `/api/v1/tryon/jewelry/:id` toutes les 3 à 5 secondes. Même cycle de vie de statut qu'apparel : `processing` → `completed` ou `failed`. Une fenêtre de 1.5 à 4 minutes couvre la grande majorité des jobs.

Fonctionnalités associées

Chaque chiffre sur cette page provient de la documentation de l'API Photta · vérifié 2026-09-10

Testez l'API en cinq minutes

Générez une clé d'API Photta, collez le snippet cURL ci-dessus, et vous obtiendrez votre première photo portée sur modèle avant même que le café ait fini de couler.

Créer un compte et obtenir une clé API Consulter la documentation

1.5–4 min
5 crédits en 2K · 6 crédits en 4K
asynchrone, polling
600 requêtes/min
Clé Bearer

API de try-on de bijoux pour colliers, bagues, bracelets et boucles d'oreilles

En un coup d'œil

Requête et réponse

Paramètres de requête

Erreurs

Le flux apparel, réajusté pour les petits articles hautement réfléchissants

Générer une clé d'API

Choisir un mannequin gros plan

Créer le job de bijou en POST

Effectuer le polling jusqu'à la fin du job

Télécharger et persister

Même endpoint en Node.js, Python et cURL

Questions des développeurs avant d'intégrer le try-on de bijoux

Fonctionnalités associées

Testez l'API en cinq minutes