Capacidad · Joyas

API de try-on de joyas para collares, anillos, pulseras y pendientes

En una frase

La API de try-on de joyas de Photta toma una foto de la joya, un jewelry_type (necklace, ring, bracelet o earrings) y un ID de maniquí, y devuelve una foto en primer plano sobre modelo. Haz POST, sondea cada 3 segundos y descarga cuando el estado sea completed.

Obtener una API key Leer la documentación

Tiempo típico: 1.5–4 min
Credits: 5 credits a 2K · 6 credits a 4K
Procesamiento: asíncrono, polling
Límites: 600 requests/min
Autenticación: Bearer key

Cada cifra de esta página proviene de la documentación de la API de Photta · verificado 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 — Salida de ejemplo

De un vistazo

Endpoint: POST /api/v1/tryon/jewelry
Autenticación: Bearer API key
Procesamiento: Asíncrono — realiza polling al endpoint de estado
Tiempo típico: 1.5–4 min
Credits: 5 credits a 2K · 6 credits a 4K
Relaciones de aspecto: 3:4 · 1:1 · 4:3 · 9:16 · 16:9
Límites de entrada: Hasta 10 MB por imagen; JPEG, PNG, WebP
Idempotente: No

Petición y respuesta

Petición

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 / Completado

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

Parámetros de la petición

CampoDescripción

jewelry_image

Tipo: stringObligatorio

URL or base64 data URI of the jewelry product image.

jewelry_type

Tipo: stringObligatorio

Type of jewelry.

necklaceearringsbraceletring

mannequin_id

Tipo: stringObligatorio

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

Tipo: 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

Tipo: 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

Tipo: 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

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

Errores

EstadoTipoSignificado

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.

Límites

600 solicitudes por minuto por API key (Ventana fija; el límite es el mismo en todos los planes)
Un 429 incluye Retry-After: 30 segundos
Hasta 10 MB por imagen
Formatos: JPEG, PNG, WebP
Lotes simultáneos por plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
Solo polling — la API no envía webhooks.

El flujo de ropa, recalibrado para artículos pequeños y altamente reflectantes

Elige un maniquí en primer plano, envía la petición, haz polling y descarga.

Paso 1
Genera una API key
El mismo flujo que para ropa — ai.photta.app → Developers → Generate API key. Una sola clave funciona en todos los endpoints; un único saldo de credits cubre cada funcionalidad.
Paso 2
Elige un maniquí en primer plano
Lista los maniquíes de joyería o sube el tuyo con `POST /api/v1/mannequins/jewelry` — Photta mantiene un conjunto específico de maniquíes en primer plano con texturas de piel ajustadas para metales y piedras de tamaño reducido.
Paso 3
Envía el trabajo de joyería con POST
Haz POST a `/api/v1/tryon/jewelry` con `jewelry_image`, `jewelry_type`, `mannequin_id` y los parámetros opcionales `background`, `resolution` y `aspect_ratio`. El servicio escala automáticamente la posición según la categoría de joyería.
Paso 4
Haz polling hasta que el trabajo se complete
Haz GET a `/api/v1/tryon/jewelry/:id` cada 3 segundos. La estructura de la respuesta es idéntica a la de ropa — `data.status`, `data.output_url`, `data.thumbnail_url`.
Paso 5
Descarga y persiste
Un recorte ajustado 1:1 funciona mejor para miniaturas de PDP; relaciones de aspecto más amplias para editorial. Almacena los bytes localmente en lugar de hacer hot-linking a la CDN.

El mismo endpoint en Node.js, Python y cURL

Preguntas que se hacen los desarrolladores antes de implementar try-on para joyería

¿Qué tipos de joyería son compatibles?

Cuatro categorías explícitas: collar, anillo, pulsera, pendientes. Cada categoría cuenta con su propio conjunto específico de maniquíes en primer plano y una heurística de colocación optimizada para ese factor de forma. Los anillos y pendientes se benefician más del formato 1:1; los collares lucen bien en 3:4.

¿Cuánto cuesta un try-on de joyería?

Lo mismo que para ropa: 5 credits a 2K, 6 credits a 4K. Los trabajos fallidos se reembolsan automáticamente. Sin recargo adicional por la biblioteca de maniquíes en primer plano.

¿En qué se diferencia el endpoint de joyería del de ropa?

Misma autenticación, mismo patrón de polling, misma estructura de respuesta — las diferencias están en el cuerpo de la petición. Envías `jewelry_type` y `jewelry_image` en lugar de `product_type` y `product_images`, y seleccionas maniquíes filtrados por categoría de joyería. Todo lo demás (2K/4K, relaciones de aspecto, credits) se comparte.

¿Puedo subir mi propio modelo de joyería?

Sí — `POST /api/v1/mannequins/jewelry` acepta una referencia personalizada en primer plano; `POST /api/v1/mannequins/jewelry/generate` genera una nueva a partir de opciones. Ambas devuelven un ID que luego introduces en la petición de try-on.

¿Cómo gestiona los metales reflectantes y las piedras preciosas?

El pipeline de primeros planos procesa metadatos sobre reflejos especulares y microgeometría. El oro, la plata y el platino pulido a espejo se renderizan correctamente sin las imágenes fantasma o el desenfoque cromático producidos por pipelines de try-on de propósito general. Se recomiendan fondos de estudio ultra limpios para obtener los mejores resultados.

¿Cómo hago el polling para obtener el resultado?

Haz GET a `/api/v1/tryon/jewelry/:id` cada 3 a 5 segundos. Mismo ciclo de vida de estados que para ropa: `processing` → `completed` o `failed`. Una ventana de 1.5 a 4 minutos cubre la gran mayoría de los trabajos.

Funcionalidades relacionadas

Cada cifra de esta página proviene de la documentación de la API de Photta · verificado 2026-09-10

Prueba la API en cinco minutos

Genera una API key de Photta, pega el snippet de cURL de arriba y tendrás tu primera imagen con modelo antes de que termine de prepararse el café.

Crear una cuenta y obtener una API key Leer la documentación

1.5–4 min
5 credits a 2K · 6 credits a 4K
asíncrono, polling
600 requests/min
Bearer key

API de try-on de joyas para collares, anillos, pulseras y pendientes

De un vistazo

Petición y respuesta

Parámetros de la petición

Errores

El flujo de ropa, recalibrado para artículos pequeños y altamente reflectantes

Genera una API key

Elige un maniquí en primer plano

Envía el trabajo de joyería con POST

Haz polling hasta que el trabajo se complete

Descarga y persiste

El mismo endpoint en Node.js, Python y cURL

Preguntas que se hacen los desarrolladores antes de implementar try-on para joyería

Funcionalidades relacionadas

Prueba la API en cinco minutos