Kapabilitas · Perhiasan

API try-on perhiasan untuk kalung, cincin, gelang, dan anting

Ringkasan singkat

API try-on perhiasan Photta menerima foto perhiasan, jewelry_type (necklace, ring, bracelet, atau earrings), serta ID manekin, lalu mengembalikan foto close-up pada model. POST, lakukan polling setiap 3 detik, unduh ketika status completed.

  • Waktu umum: 1.5–4 min
  • Credits: 5 credits pada 2K · 6 credits pada 4K
  • Pemrosesan: async, polling
  • Batasan: 600 requests/min
  • Autentikasi: Bearer key

Setiap angka di halaman ini bersumber dari dokumentasi API Photta · diperiksa

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
Contoh output

Sekilas

Sekilas

Endpoint
POST /api/v1/tryon/jewelry
Autentikasi
API key Bearer
Pemrosesan
Asinkron — lakukan polling ke endpoint status
Waktu umum
1.5–4 min
Credits
5 credits pada 2K · 6 credits pada 4K
Rasio aspek
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Batas input
Hingga 10 MB per gambar; JPEG, PNG, WebP
Idempoten
Tidak

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

Parameter request

jewelry_image

Tipe: stringWajib

URL or base64 data URI of the jewelry product image.

jewelry_type

Tipe: stringWajib

Type of jewelry.

Nilai: necklaceearringsbraceletring
mannequin_id

Tipe: stringWajib

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

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

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

Nilai: 2K4K
aspect_ratio

Tipe: string

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

= 3:4

Nilai: 3:41:14:39:1616:9
user_instruction

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

Error

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.

Batasan

  • 600 request per menit per API key (Fixed window; batasannya sama di setiap paket)
  • Respons 429 menyertakan Retry-After: 30 detik
  • Hingga 10 MB per gambar
  • Format: JPEG, PNG, WebP
  • Batch konkuren per paket: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Hanya polling — API tidak mengirim webhook.

Alur apparel, disetel ulang untuk barang kecil yang sangat reflektif

Pilih manekin close-up, kirim, lakukan polling, unduh.

  1. Langkah 1

    Buat API key

    Alur yang sama seperti apparel — ai.photta.app → Developers → Generate API key. Satu key berlaku untuk setiap endpoint; satu saldo credits mencakup setiap capability.

  2. Langkah 2

    Pilih manekin close-up

    Daftar manekin perhiasan atau unggah milik Anda sendiri dengan `POST /api/v1/mannequins/jewelry` — Photta menyediakan set manekin close-up khusus dengan tekstur kulit yang disetel untuk logam dan batu permata kecil.

  3. Langkah 3

    POST job perhiasan

    POST ke `/api/v1/tryon/jewelry` dengan `jewelry_image`, `jewelry_type`, `mannequin_id` serta opsi opsional `background`, `resolution`, dan `aspect_ratio`. Layanan ini menyesuaikan penempatan skala secara otomatis untuk kategori perhiasan terkait.

  4. Langkah 4

    Lakukan polling hingga job selesai

    GET `/api/v1/tryon/jewelry/:id` setiap 3 detik. Bentuk response identik dengan apparel — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. Langkah 5

    Unduh dan simpan

    Tight-crop 1:1 bekerja paling baik untuk thumbnail PDP; aspect ratio yang lebih lebar cocok untuk editorial. Simpan bita sendiri daripada melakukan hot-linking ke CDN.

Pertanyaan yang diajukan developer sebelum merilis jewelry try-on

Tipe perhiasan apa saja yang didukung?

Empat kategori eksplisit: necklace, ring, bracelet, earrings. Setiap kategori memiliki set manekin close-up khusus serta heuristik penempatan yang disetel untuk bentuk tersebut. Cincin dan anting paling optimal dengan aspect ratio 1:1; kalung tampil pas pada 3:4.

Berapa biaya untuk satu jewelry try-on?

Sama seperti apparel: 5 credits pada 2K, 6 credits pada 4K. Job yang gagal akan di-refund secara otomatis. Tidak ada biaya tambahan untuk library manekin close-up.

Apa perbedaan endpoint jewelry dengan apparel?

Autentikasi sama, pola polling sama, bentuk response sama — perbedaannya terletak pada request body. Anda mengirimkan `jewelry_type` dan `jewelry_image`, bukan `product_type` dan `product_images`, serta memilih manekin yang difilter berdasarkan kategori perhiasan. Hal lainnya (2K/4K, aspect ratio, credits) sama persis.

Bisakah saya mengunggah model perhiasan saya sendiri?

Bisa — `POST /api/v1/mannequins/jewelry` menerima referensi close-up kustom, `POST /api/v1/mannequins/jewelry/generate` menghasilkan manekin baru berdasarkan opsi yang dipilih. Keduanya mengembalikan ID yang dapat Anda masukkan kembali ke dalam request try-on.

Bagaimana cara menangani logam reflektif dan batu permata?

Pipeline close-up mempertahankan metadata tentang specular highlight dan geometri mikro. Emas, perak, dan platinum polesan cermin ter-render dengan tepat tanpa efek ghosting atau chromatic smear yang biasanya muncul pada pipeline try-on serbaguna. Latar belakang studio yang sangat bersih disarankan untuk hasil terbaik.

Bagaimana cara melakukan polling untuk hasilnya?

GET `/api/v1/tryon/jewelry/:id` setiap 3 hingga 5 detik. Siklus status sama seperti apparel: `processing` → `completed` atau `failed`. Rentang waktu 1.5 hingga 4 menit mencakup sebagian besar job.

Capability terkait

Setiap angka di halaman ini bersumber dari dokumentasi API Photta · diperiksa

Coba API dalam lima menit

Buat Photta API key, tempel cuplikan cURL di atas, dan Anda akan mendapatkan gambar on-model pertama sebelum kopi selesai diseduh.

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