Tính năng · Eyewear studio
API virtual try-on kính mắt cho kính thuốc và kính râm
Tóm tắt trong một câu
API eyewear studio của Photta biến một bức ảnh kính thuốc hoặc kính râm thành một bức ảnh hoàn thiện. Chọn chế độ chỉ chụp sản phẩm hoặc trên người mẫu, gửi request POST, polling mỗi 3 giây một lần, tải về khi trạng thái chuyển sang completed. 5 credits ở độ phân giải 2K.
- Thời gian điển hình: 20–60 sec
- 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/eyewear-studio \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
"mode": "product-only",
"sub_tool": "studio-shot",
"backdrop": "gradient",
"lighting": "soft",
"aspect_ratio": "3:4",
"resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/eyewear-studio", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
"mode": "product-only",
"sub_tool": "studio-shot",
"backdrop": "gradient",
"lighting": "soft",
"aspect_ratio": "3:4",
"resolution": "2K"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/eyewear-studio",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
"mode": "product-only",
"sub_tool": "studio-shot",
"backdrop": "gradient",
"lighting": "soft",
"aspect_ratio": "3:4",
"resolution": "2K"
},
)
data = res.json()["data"] # data["id"], data["status"]
Tổng quan nhanh
Tổng quan nhanh
- Endpoint
- POST /api/v1/eyewear-studio
- Xác thực
- Bearer API key
- Xử lý
- Bất đồng bộ — polling status endpoint
- Thời gian điển hình
- 20–60 sec
- 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/eyewear-studio \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
"mode": "product-only",
"sub_tool": "studio-shot",
"backdrop": "gradient",
"lighting": "soft",
"aspect_ratio": "3:4",
"resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/eyewear-studio", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
"mode": "product-only",
"sub_tool": "studio-shot",
"backdrop": "gradient",
"lighting": "soft",
"aspect_ratio": "3:4",
"resolution": "2K"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/eyewear-studio",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
"mode": "product-only",
"sub_tool": "studio-shot",
"backdrop": "gradient",
"lighting": "soft",
"aspect_ratio": "3:4",
"resolution": "2K"
},
)
data = res.json()["data"] # data["id"], data["status"]202 Accepted / Completed
{
"data": {
"id": "eyw_7a1c9e42f05b3d688c2e4f01a9d6b357",
"status": "processing",
"mode": "product-only",
"sub_tool": "studio-shot",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 5,
"created_at": "2026-08-01T09:15:00Z"
},
"request_id": "req_eyw001"
}{
"data": {
"id": "eyw_7a1c9e42f05b3d688c2e4f01a9d6b357",
"status": "completed",
"mode": "product-only",
"sub_tool": "studio-shot",
"output_url": "https://cdn.photta.app/generated/eyw_7a1c9e42f05b3d688c2e4f01a9d6b357.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/eyw_7a1c9e42f05b3d688c2e4f01a9d6b357-thumb.jpg",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 5,
"created_at": "2026-08-01T09:15:00Z",
"completed_at": "2026-08-01T09:15:38Z"
},
"request_id": "req_eyw002"
}Tham số request
eyewear_imageKiểu: stringBắt buộc
The eyewear product image — glasses or sunglasses. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.
modeKiểu: string
Generation mode: "product-only" — the eyewear alone, styled by sub_tool; "on-model" — the eyewear worn on an AI model's face (requires mannequin_id).
= product-only
Giá trị:product-onlyon-modelsub_toolKiểu: string
Product-only styling: "studio-shot" — clean studio product shot; "flat-lay" — top-down arrangement on a surface; "lifestyle" — the eyewear placed in a real-world scene; "floating" — the frames suspended mid-air. Sending sub_tool with mode "on-model" returns 400.
= studio-shot
Giá trị:studio-shotflat-laylifestylefloatingmannequin_idKiểu: string
Required when mode is "on-model": the AI model whose face wears the eyewear — an id ("mnk_...") from GET /api/v1/eyewear-studio/mannequins. Sending it in product-only mode returns 400.
face_angleKiểu: string
On-model only: the angle of the model's face.
= front
Giá trị:frontthree-quarterside-profileexpressionKiểu: string
On-model only: the model's facial expression.
= neutral
Giá trị:neutralsoft-smileseriousconfidentlighting_styleKiểu: string
On-model only: how the portrait is lit.
= soft-diffused
Giá trị:soft-diffusedstudionaturaldramaticframe_fit_styleKiểu: string
On-model only: the overall styling of how the frames are worn.
= casual
Giá trị:casualprofessionalfashion-editorialsportybackdropKiểu: string
Studio-shot only: the backdrop behind the eyewear.
= white
Giá trị:whitegrayblackgradientlightingKiểu: string
Studio-shot only: the lighting setup.
= soft
Giá trị:softharddramaticnaturalsurfaceKiểu: string
Flat-lay only: the surface the eyewear lies on.
= marble
Giá trị:marblewoodfabricconcretemetalarrangement_styleKiểu: string
Flat-lay only: how the composition is arranged.
= minimal
Giá trị:minimalsymmetricscatteredlayeredpropsKiểu: string
Flat-lay only: complementary props placed around the eyewear.
= none
Giá trị:noneplantsaccessoriestechsceneKiểu: string
Lifestyle only: the real-world setting.
= coffee-shop
Giá trị:coffee-shopbeachurban-streetofficeparkmoodKiểu: string
Lifestyle only: the color mood of the scene.
= warm
Giá trị:warmcoolvibrantmoodyangleKiểu: string
Floating only: the camera angle on the suspended frames.
= front
Giá trị:frontthree-quartersidetop-downshadow_styleKiểu: string
Floating only: the shadow cast beneath the frames.
= soft-drop
Giá trị:soft-dropnonehard-dropreflectionbackground_colorKiểu: string
Solid background color. Applies in both modes. Overridden by background_prompt when both are sent.
= white
Giá trị:whitegrayblackbeigebackground_promptKiểu: string
Free-text background description. Max 400 characters — excess is silently truncated. Overrides background_color.
aspect_ratioKiểu: string
Output aspect ratio.
= 3:4
Giá trị:3:41:14:39:1616:9resolutionKiểu: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Giá trị:2K4K
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.
Đầu vào là một ảnh gọng kính, đầu ra là một ảnh kính mắt đã tạo kiểu
Chọn chế độ, cấu hình kiểu dáng mà chế độ đó cung cấp, gửi request, polling và tải về.
Bước 1
Tạo API key
Eyewear studio dùng chung thông tin xác thực và số dư credits với mọi tính năng khác của Photta.
Bước 2
Chọn chế độ và kiểu dáng tương ứng
`mode` có giá trị là `product-only` hoặc `on-model`. Product-only nhận `sub_tool` — `studio-shot`, `flat-lay`, `lifestyle` hoặc `floating` — và mỗi tùy chọn sẽ mở ra các bộ điều khiển riêng. On-model nhận `mannequin_id` kèm theo `face_angle`, `expression`, `lighting_style` và `frame_fit_style`.
Bước 3
Gửi POST tạo job kính mắt
Gửi POST tới `/api/v1/eyewear-studio` với `eyewear_image` cùng các trường tạo kiểu của bạn. `background_prompt` chấp nhận tối đa 400 ký tự và sẽ ghi đè `background_color`. Polling là tín hiệu hoàn thành duy nhất — API không gửi webhook.
Bước 4
Polling cho đến khi job hoàn thành
Gửi GET `/api/v1/eyewear-studio/:id` mỗi 3 giây một lần cho đến khi `data.status` chuyển sang `completed` hoặc `failed`; thời gian hoàn thành thông thường từ 20 đến 60 giây.
Bước 5
Tải về và lưu trữ lâu dài
Body trả về khi hoàn tất chứa `output_url` và một ảnh thumbnail. Bạn hãy tự lưu trữ file — URL này chỉ dùng để bàn giao kết quả của một job, không phải là nơi lưu trữ vĩnh viễn.
Cùng một endpoint trên Node.js, Python và cURL
Node.js
API virtual try-on kính mắt trong Node.js
Gọi aPI virtual try-on kính mắt 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 virtual try-on kính mắt trong Python
Gọi aPI virtual try-on kính mắt 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 virtual try-on kính mắt với cURL
Gọi trực tiếp aPI virtual try-on kính mắt 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 ra trước khi triển khai chụp ảnh kính mắt
API eyewear studio dùng để làm gì?
Nó nhận một ảnh sản phẩm kính thuốc hoặc kính râm và trả về một bức ảnh đã được tạo kiểu hoàn chỉnh — chụp riêng gọng kính theo phong cách studio, flat-lay, lifestyle, floating, hoặc đeo trực tiếp lên khuôn mặt của người mẫu AI do bạn chọn.
Chi phí cho một bức ảnh kính mắt là bao nhiêu?
5 credits ở độ phân giải 2K và 6 credits ở độ phân giải 4K, tương tự như try-on trang phục và trang sức. Các job thất bại sẽ được tự động hoàn credit.
Điểm khác biệt giữa product-only và on-model là gì?
`product-only` chụp riêng gọng kính và được điều khiển bởi `sub_tool`. `on-model` đeo kính lên mặt người mẫu AI và được điều khiển bởi `mannequin_id`, `face_angle`, `expression`, `lighting_style` và `frame_fit_style`. Các trường thuộc về chế độ còn lại sẽ bị bỏ qua.
Mỗi sub-tool cung cấp những tùy chọn tạo kiểu nào?
`studio-shot` nhận `backdrop` và `lighting`. `flat-lay` nhận `surface`, `arrangement_style` và `props`. `lifestyle` nhận `scene` và `mood`. `floating` nhận `angle` và `shadow_style`. Tất cả các trường này đều là enum, do đó giá trị không hợp lệ sẽ bị từ chối thay vì hệ thống tự suy đoán.
Tôi có thể dùng AI model riêng của mình không?
Có. `mannequin_id` chấp nhận bất kỳ mannequin id nào từ GET `/api/v1/eyewear-studio/mannequins`, và các mannequin bạn tạo bằng mannequin generation API cũng có thể được sử dụng theo cách tương tự.
Tôi polling kết quả như thế nào?
GET `/api/v1/eyewear-studio/:id` mỗi 3 giây cho đến khi `data.status` là `completed` hoặc `failed`. Không có webhook; polling là tín hiệu hoàn thành được ghi nhận trong tài liệu.
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 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.
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 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ê.
- 20–60 sec
- 5 credits ở 2K · 6 credits ở 4K
- async, polling
- 600 requests/min
- Bearer key