cURL · API try-on trang sức
API try-on trang sức với cURL
Tóm tắt trong một câu
Export PHOTTA_API_KEY, gửi POST đến https://api.photta.app/api/v1/api/v1/tryon/jewelry với body JSON theo tài liệu, lấy generation ID, sau đó lặp lệnh GET trên /api/v1/tryon/jewelry/{id} mỗi 3 giây cho đến khi data.status chuyển thành completed. Kết hợp với jq để trích xuất output URL.
- 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')
# $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/jewelry/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
STATUS=$(echo "$RESULT" | jq -r '.data.status')
[ "$STATUS" = "completed" ] && break
[ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'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
async function waitFor(id) {
for (let attempt = 0; attempt < 120; attempt++) {
const res = await fetch(`https://api.photta.app/api/v1/tryon/jewelry/${id}`, { headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` } });
const { data } = await res.json();
if (data.status === "completed") return data.output_url;
if (data.status === "failed") throw new Error(data.error_message ?? "generation failed");
await new Promise((r) => setTimeout(r, 3000));
}
throw new Error("timed out after 6 minutes");
}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"]
import time
def wait_for(job_id):
for _ in range(120):
res = requests.get(f"https://api.photta.app/api/v1/tryon/jewelry/{job_id}", headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"})
data = res.json()["data"]
if data["status"] == "completed":
return data["output_url"]
if data["status"] == "failed":
raise RuntimeError(data.get("error_message", "generation failed"))
time.sleep(3)
raise TimeoutError("timed out after 6 minutes")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
Cơ chế hoạt động
Năm bước trên shell, không phụ thuộc vào bất kỳ công cụ nào ngoài curl và jq.
Bước 1
Đăng ký và tạo key
Truy cập ai.photta.app, mở tab Developers, nhấp vào Generate API key. Các key môi trường live sẽ bắt đầu bằng `photta_live_`.
Bước 2
Export key
Thêm `export PHOTTA_API_KEY="photta_live_xxx"` vào profile của shell hoặc file `.envrc` để mọi lệnh gọi curl tiếp theo tự động nhận diện key.
curl --version # macOS, Linux, WSL and Windows 10+ ship it export PHOTTA_API_KEY="photta_live_xxxxx"Bước 3
Cố định base URL
`export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` giúp các lệnh curl luôn ngắn gọn.
export PHOTTA_BASE_URL="https://api.photta.app/api/v1" export AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"Bước 4
Gửi request và polling
POST tới `$PHOTTA_BASE_URL/api/v1/tryon/jewelry` để lấy ID, sau đó lặp `curl $PHOTTA_BASE_URL/api/v1/tryon/jewelry/{id}` mỗi 3 giây. Pipe response sang jq để trích xuất `.data.status` một cách gọn gàng.
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') # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed". for i in $(seq 1 120); do RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/jewelry/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY") STATUS=$(echo "$RESULT" | jq -r '.data.status') [ "$STATUS" = "completed" ] && break [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1 sleep 3 done echo "$RESULT" | jq -r '.data.output_url'Bước 5
Lưu trữ kết quả
Khi job hoàn thành, trích xuất `.data.output_url` bằng jq và chạy `curl -o` để tải byte dữ liệu về bộ nhớ cục bộ — sẵn sàng cho bước tiếp theo trong pipeline.
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.
case "$STATUS_CODE" in
402) echo "insufficient_credits_error — top up before retrying" ;;
429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
4??) echo "$BODY" | jq '.error.type, .error.message' ;;
5??) echo "api_error — retry with backoff" ;;
esacGiớ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.
Vì sao cURL vẫn là cách nhanh nhất để kiểm thử một API
- Không cần cài đặt — cURL có sẵn trên mọi hệ điều hành phổ biến
- Kết hợp hoàn hảo với jq cho các pipeline dạng script (CI, cron, shell hook)
- Cách nhanh nhất để smoke-test một endpoint trước khi tích hợp vào code
- Mọi lệnh trên trang này đều có thể paste trực tiếp vào bất kỳ POSIX shell nào
Những hạn chế cần lưu ý
- Vòng lặp polling sẽ block terminal — hãy chuyển sang Node hoặc Python để chạy worker song song
- Polling là tín hiệu duy nhất để nhận biết hoàn thành; API không gửi webhook
- Người dùng Windows Command Prompt nên chạy WSL hoặc curl.exe của PowerShell
Câu hỏi thường gặp từ developer
Có công cụ Photta CLI không?
Chưa có — nhưng cURL kết hợp với một bash wrapper mười lăm dòng là đủ cho hầu hết nhu cầu. Tài liệu ưu tiên các ví dụ dùng cURL vì mọi ngôn ngữ đều có thể thực thi subprocess, và shell là mẫu số chung trong các pipeline CI.
Tôi có cần jq để sử dụng API không?
Không bắt buộc — nhưng viết script pipeline sẽ dễ dàng hơn nhiều nếu có nó. jq giúp bạn trích xuất `.data.id`, `.data.status` và `.data.output_url` từ JSON response mà không cần parse thủ công. Cài đặt bằng `brew install jq` trên macOS hoặc `apt install jq` trên Debian/Ubuntu.
Xác thực bằng curl như thế nào?
Thêm `-H "Authorization: Bearer $PHOTTA_API_KEY"` vào mỗi request. Hãy lưu key trong biến môi trường, đừng bao giờ hardcode trực tiếp vào script được commit. `curl --oauth2-bearer` cũng hoạt động nhưng dạng khai báo header tường minh sẽ rõ ràng hơn trong tài liệu và log.
Tôi có thể dùng script dựa trên curl trên production không?
Đối với các tác vụ backfill dữ liệu theo batch chạy một lần hoặc cron job thì có — hàng nghìn đội ngũ kỹ thuật vẫn cập nhật lại danh mục sản phẩm theo cách này. Đối với một ứng dụng chạy liên tục lâu dài, một ngôn ngữ lập trình thực thụ thường tốt hơn vì bạn có cơ chế xử lý lỗi, retry và khả năng quan sát (observability) bài bản. Các ví dụ curl trên trang này vẫn hoàn toàn chính xác kể cả khi bạn chuyển sang Node hoặc Python; cấu trúc request vẫn giữ nguyên.
Polling từ một vòng lặp bash như thế nào?
Sử dụng `for i in $(seq 1 120); do … ; sleep 3; done` với lệnh kiểm tra trạng thái nằm trong thân vòng lặp. Thoát vòng lặp khi `.data.status` chuyển thành `completed` hoặc `failed`. Đoạn code mẫu trên trang này minh họa chính xác pattern đó, bao gồm cả giới hạn thời gian tối đa để job bị kẹt không làm treo script mãi mãi.
Làm sao để đọc response lỗi trong curl?
Sử dụng `curl -w "\n%{http_code}"` để lấy HTTP status code cùng với JSON body. Rẽ nhánh xử lý theo status: 402 cho lỗi không đủ credits, 429 khi bị rate limit (hãy tuân thủ giá trị Retry-After), 5xx cho các lỗi máy chủ tạm thời. Error body luôn chứa trường `error.code` và `error.message`.
Các trang liên quan
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.
ĐọcTính năng
API try-on trang sức dành cho dây chuyền, nhẫn, vòng tay và hoa tai
Đưa dây chuyền, nhẫn, vòng tay và hoa tai lên người mẫu AI qua REST. 5 credits ở độ phân giải 2K, tích hợp sẵn mannequin cận cảnh, render chuẩn phản chiếu theo tài liệu Photta.
ĐọcXâ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.
ĐọcBắ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.
ĐọcTài liệu tham khảo
Bảng giá Photta API
Chi phí tính bằng credits cho từng endpoint của Photta API ở độ phân giải 2K và 4K, cơ chế trừ phí và hoàn tiền, cùng các endpoint miễn phí. Không tính giá tiền trực tiếp trên từng ảnh.
Đọc
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