Tính năng · Trang sức

API try-on trang sức dành cho dây chuyền, nhẫn, vòng tay và hoa tai

Tóm tắt trong một câu

API try-on trang sức của Photta nhận ảnh trang sức, jewelry_type (necklace, ring, bracelet hoặc earrings) và mannequin ID rồi trả về ảnh cận cảnh đeo trên người mẫu. POST, polling mỗi 3 giây, tải về khi status là completed.

  • Thời gian điển hình: 1.5–4 min
  • Credits: 5 credits ở 2K · 6 credits ở 4K
  • Xử lý: async, polling
  • Giới hạn: 600 requests/min
  • Xác thực: Bearer key

Mọi số liệu trên trang này đều lấy từ tài liệu Photta API · đã kiểm tra

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
Kết quả mẫu

Tổng quan nhanh

Tổng quan nhanh

Endpoint
POST /api/v1/tryon/jewelry
Xác thực
Bearer API key
Xử lý
Bất đồng bộ — polling status endpoint
Thời gian điển hình
1.5–4 min
Credits
5 credits ở 2K · 6 credits ở 4K
Tỷ lệ khung hình
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Giới hạn đầu vào
Tối đa 10 MB mỗi ảnh; JPEG, PNG, WebP
Idempotent
Không

Request và 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"
}

Tham số request

jewelry_image

Kiểu: stringBắt buộc

URL or base64 data URI of the jewelry product image.

jewelry_type

Kiểu: stringBắt buộc

Type of jewelry.

Giá trị: necklaceearringsbraceletring
mannequin_id

Kiểu: stringBắt buộc

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

Kiểu: 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

Kiểu: 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

Giá trị: 2K4K
aspect_ratio

Kiểu: string

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

= 3:4

Giá trị: 3:41:14:39:1616:9
user_instruction

Kiểu: 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.

Lỗi

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.

Giới hạn

  • 600 request mỗi phút trên mỗi API key (Fixed window; giới hạn như nhau trên mọi gói)
  • Mã 429 kèm header Retry-After: 30 giây
  • Tối đa 10 MB mỗi ảnh
  • Định dạng: JPEG, PNG, WebP
  • Batch đồng thời theo từng gói: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Chỉ hỗ trợ polling — API không gửi webhook.

Quy trình xử lý trang phục, được tinh chỉnh cho các vật phẩm nhỏ có độ phản chiếu cao

Chọn một mannequin cận cảnh, gửi request, poll và tải xuống.

  1. Bước 1

    Tạo một API key

    Quy trình tương tự như trang phục — ai.photta.app → Developers → Generate API key. Một key hoạt động trên mọi endpoint; một số dư credits áp dụng cho mọi tính năng.

  2. Bước 2

    Chọn một mannequin cận cảnh

    Liệt kê danh sách mannequin trang sức hoặc tải lên mannequin của riêng bạn bằng `POST /api/v1/mannequins/jewelry` — Photta duy trì một bộ mannequin cận cảnh chuyên dụng với kết cấu da được tinh chỉnh cho kim loại và đá quý kích thước nhỏ.

  3. Bước 3

    POST job trang sức

    POST tới `/api/v1/tryon/jewelry` cùng với `jewelry_image`, `jewelry_type`, `mannequin_id` và các trường tuỳ chọn `background`, `resolution` cùng `aspect_ratio`. Dịch vụ sẽ tự động căn chỉnh tỷ lệ và vị trí đặt cho từng danh mục trang sức.

  4. Bước 4

    Poll cho đến khi job hoàn thành

    GET `/api/v1/tryon/jewelry/:id` mỗi 3 giây. Cấu trúc response giống hệt trang phục — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. Bước 5

    Tải xuống và lưu trữ lâu dài

    Tỷ lệ 1:1 crop sát phù hợp nhất cho thumbnail trang PDP; tỷ lệ khung hình rộng hơn dành cho ảnh editorial. Hãy tự lưu trữ các byte ảnh thay vì hot-link trực tiếp từ CDN.

Các câu hỏi lập trình viên thường đặt trước khi triển khai try-on trang sức

Hỗ trợ những loại trang sức nào?

Bốn danh mục rõ ràng: necklace, ring, bracelet, earrings. Mỗi danh mục có một bộ mannequin cận cảnh chuyên dụng riêng và thuật toán định vị được tinh chỉnh theo form factor đó. Nhẫn và hoa tai đạt hiệu quả cao nhất với tỷ lệ khung hình 1:1; dây chuyền hiển thị tốt ở tỷ lệ 3:4.

Chi phí cho mỗi lượt try-on trang sức là bao nhiêu?

Tương tự trang phục: 5 credits ở 2K, 6 credits ở 4K. Các job lỗi sẽ tự động được hoàn credits. Không tính thêm phụ phí cho thư viện mannequin cận cảnh.

Endpoint trang sức khác gì so với trang phục?

Cùng phương thức xác thực, cùng cơ chế polling, cùng cấu trúc response — điểm khác biệt nằm ở request body. Bạn gửi `jewelry_type` và `jewelry_image` thay vì `product_type` và `product_images`, đồng thời chọn các mannequin được lọc theo danh mục trang sức. Mọi thứ khác (2K/4K, tỷ lệ khung hình, credits) đều dùng chung.

Tôi có thể tải lên người mẫu trang sức của riêng mình không?

Có — `POST /api/v1/mannequins/jewelry` nhận ảnh tham chiếu cận cảnh tuỳ chỉnh, `POST /api/v1/mannequins/jewelry/generate` tạo một mẫu mới dựa trên các tuỳ chọn. Cả hai đều trả về một ID để bạn đưa vào request try-on.

Hệ thống xử lý kim loại phản chiếu và đá quý như thế nào?

Pipeline cận cảnh mang metadata về các điểm sáng phản chiếu (specular highlights) và cấu trúc vi hình học (micro-geometry). Vàng, bạc và bạch kim đánh bóng gương hiển thị chính xác mà không gặp hiện tượng bóng mờ (ghosting) hay nhòe sắc sai (chromatic smear) như các pipeline try-on đa dụng thường thấy. Khuyên dùng nền studio cực sạch để đạt kết quả tốt nhất.

Làm cách nào để poll kết quả?

GET `/api/v1/tryon/jewelry/:id` mỗi 3 đến 5 giây. Vòng đời trạng thái giống hệt trang phục: `processing` → `completed` hoặc `failed`. Khoảng thời gian từ 1.5 đến 4 phút là đủ xử lý phần lớn các job.

Các tính năng liên quan

Mọi số liệu trên trang này đều lấy từ tài liệu Photta API · đã kiểm tra

Thử nghiệm API trong năm phút

Tạo một Photta API key, dán đoạn mã cURL ở trên, và bạn sẽ nhận được bức ảnh mẫu mặc đồ đầu tiên trước khi pha xong ly cà phê.

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