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
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.statusimport 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"]
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')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.statusimport 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"
}Tham số request
jewelry_imageKiểu: stringBắt buộc
URL or base64 data URI of the jewelry product image.
jewelry_typeKiểu: stringBắt buộc
Type of jewelry.
Giá trị:necklaceearringsbraceletringmannequin_idKiể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.
backgroundKiể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.
resolutionKiể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ị:2K4Kaspect_ratioKiể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:9user_instructionKiể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
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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.
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.
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ỏ.
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.
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`.
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ùng một endpoint trên Node.js, Python và cURL
Node.js
API try-on trang sức trong Node.js
Gọi aPI try-on trang sức của Photta từ backend Node.js bằng fetch gốc. Không cần SDK: chỉ cần lưu key, gửi job và poll kết quả.
ĐọcPython
API try-on trang sức trong Python
Gọi aPI try-on trang sức của Photta trong Python với thư viện requests. Wrapper ba mươi dòng, hỗ trợ async qua httpx, hoạt động trong Django, FastAPI và Celery.
ĐọccURL
API try-on trang sức với cURL
Gọi trực tiếp aPI try-on trang sức của Photta từ shell bằng cURL. Gửi request, poll, tải về — mọi snippet đều kết hợp hoàn hảo với jq cho các script pipeline.
Đọc
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
Tính năng
Virtual try-on API cho trang phục
REST API giúp mặc trang phục lên mannequin AI. Bất đồng bộ, thời gian tạo 1.5–4 phút, 5 credits ở 2K, 6 ở 4K. Kèm ví dụ cURL, Node.js và Python.
Xem endpointTính năng
API ghost mannequin dành cho ảnh sản phẩm kiểu người vô hình
AI ghost mannequin endpoint. Xóa bỏ mannequin khỏi ảnh chụp trang phục và bảo toàn chi tiết bên trong. Dạng 3D hoặc flat-lay, xử lý hàng loạt, 4 credits ở 2K.
Xem endpointXây dựng
Xây dựng dịch vụ chụp ảnh sản phẩm bằng AI
Sổ tay chiến lược dành cho founder để bán lại virtual try-on API của Photta dưới dạng SaaS white-label: khóa cho từng tenant, xử lý phân nhánh hàng loạt, thanh toán theo credit, thực tế về SLA.
Xem endpointSo sánh
Photta vs FASHN — So sánh trực tiếp API AI thời trang
So sánh Photta và FASHN: endpoint, giá credits, các gói dịch vụ, giới hạn concurrency. Dữ liệu được trích xuất từ chính trang bảng giá của từng công ty vào ngày 2026-04-19. Không có số liệu tự dựng.
Xem endpointSo sánh
Photta vs Ayna — API cho lập trình viên hay studio chuyên cho Shopify
So sánh Photta vs Ayna: ba REST endpoint đối đầu với studio ưu tiên Shopify + API. Cả hai đều có thế mạnh riêng. Dữ liệu trích xuất từ website mỗi bên vào 2026-04-19.
Xem endpointBắt đầu nhanh
Tạo ảnh Photta đầu tiên trong vòng chưa đầy năm phút.
Đăng ký, tạo API key, chạy lệnh cURL đầu tiên, polling cho đến khi hoàn thành, lưu trữ kết quả. Năm bước, có tài liệu hướng dẫn trọn gói từ đầu đến cuối.
Xem endpointTài liệu tham khảo
Mã lỗi Photta API
Danh sách đầy đủ các loại lỗi của Photta API kèm theo status code, cấu trúc body của lỗi, và những lỗi nào có thể thử lại.
Xem endpointTài liệu tham khảo
Rate limit của Photta API
Rate limit của Photta API, khung thời gian, header Retry-After, khoảng thời gian polling và giới hạn đồng thời theo từng gói, tất cả đều được lấy từ tài liệu API.
Xem endpoint
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