Capability · Jewelry

Jewelry try-on API for necklaces, rings, bracelets and earrings

In one sentence

Photta's jewelry try-on API takes a jewelry photo, a jewelry_type (necklace, ring, bracelet or earrings) and a mannequin ID and returns a close-up on-model photo. POST, poll every 3 seconds, download when status is completed.

Get an API key Read the docs

Typical time: 1.5–4 min
Credits: 5 credits at 2K · 6 credits at 4K
Processing: async, polling
Limits: 600 requests/min
Authentication: Bearer key

Every figure on this page comes from the Photta API docs · checked 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 — Example output

At a glance

Endpoint: POST /api/v1/tryon/jewelry
Authentication: Bearer API key
Processing: Asynchronous — poll the status endpoint
Typical time: 1.5–4 min
Credits: 5 credits at 2K · 6 credits at 4K
Aspect ratios: 3:4 · 1:1 · 4:3 · 9:16 · 16:9
Input limits: Up to 10 MB per image; JPEG, PNG, WebP
Idempotent: No

Request and 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.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 / 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"
}

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

FieldDescription

jewelry_image

Type: stringRequired

URL or base64 data URI of the jewelry product image.

jewelry_type

Type: stringRequired

Type of jewelry.

necklaceearringsbraceletring

mannequin_id

Type: stringRequired

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.

Errors

StatusTypeMeaning

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 requests per minute per API key (Fixed window; the limit is the same on every plan)
A 429 carries Retry-After: 30 seconds
Up to 10 MB per image
Formats: JPEG, PNG, WebP
Concurrent batches per plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
Polling only — the API sends no webhooks.

The apparel flow, retuned for small highly-reflective items

Pick a close-up mannequin, submit, poll, download.

Step 1
Generate an API key
Same flow as apparel — ai.photta.app → Developers → Generate API key. One key works across every endpoint; one credit balance covers every capability.
Step 2
Pick a close-up mannequin
List the jewelry mannequins or upload your own with `POST /api/v1/mannequins/jewelry` — Photta maintains a purpose-built set of close-up mannequins with skin textures tuned for tiny metal and stone.
Step 3
POST the jewelry job
POST to `/api/v1/tryon/jewelry` with `jewelry_image`, `jewelry_type`, `mannequin_id` and optional `background`, `resolution` and `aspect_ratio`. The service auto-scales placement for the jewelry category.
Step 4
Poll until the job completes
GET `/api/v1/tryon/jewelry/:id` every 3 seconds. Response shape is identical to apparel — `data.status`, `data.output_url`, `data.thumbnail_url`.
Step 5
Download and persist
Tight-crop 1:1 works best for PDP thumbnails; wider aspect ratios for editorial. Store the bytes yourself rather than hot-linking the CDN.

Same endpoint in Node.js, Python and cURL

Questions developers ask before shipping jewelry try-on

What jewelry types are supported?

Four explicit categories: necklace, ring, bracelet, earrings. Each category has its own set of purpose-built close-up mannequins and a placement heuristic tuned to that form factor. Rings and earrings benefit most from 1:1 aspect ratio; necklaces read well at 3:4.

How much does a jewelry try-on cost?

Same as apparel: 5 credits at 2K, 6 credits at 4K. Failed jobs refund automatically. No surcharge for the close-up mannequin library.

How is the jewelry endpoint different from apparel?

Same authentication, same polling pattern, same response shape — the differences are in the request body. You send `jewelry_type` and `jewelry_image` instead of `product_type` and `product_images`, and you pick mannequins filtered by jewelry category. Everything else (2K/4K, aspect ratios, credits) is shared.

Can I upload my own jewelry model?

Yes — `POST /api/v1/mannequins/jewelry` accepts a custom close-up reference, `POST /api/v1/mannequins/jewelry/generate` produces a new one from options. Both return an ID you feed back into the try-on request.

How does it handle reflective metals and gemstones?

The close-up pipeline carries metadata about specular highlights and micro-geometry. Gold, silver and mirror-polished platinum render correctly without the ghosting or chromatic smear that general-purpose try-on pipelines produce. Ultra-clean studio backgrounds are recommended for best results.

How do I poll for the result?

GET `/api/v1/tryon/jewelry/:id` every 3 to 5 seconds. Same status lifecycle as apparel: `processing` → `completed` or `failed`. A 1.5 to 4 minute window covers the vast majority of jobs.

Related capabilities

Every figure on this page comes from the Photta API docs · checked 2026-09-10

Try the API in five minutes

Generate a Photta API key, paste the cURL snippet above, and you'll have your first on-model image before the coffee finishes brewing.

Create an account and get an API key Read the docs

1.5–4 min
5 credits at 2K · 6 credits at 4K
async, polling
600 requests/min
Bearer key

Jewelry try-on API for necklaces, rings, bracelets and earrings

At a glance

Request and response

Request parameters

Errors

The apparel flow, retuned for small highly-reflective items

Generate an API key

Pick a close-up mannequin

POST the jewelry job

Poll until the job completes

Download and persist

Same endpoint in Node.js, Python and cURL

Questions developers ask before shipping jewelry try-on

Related capabilities

Try the API in five minutes