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

POST/api/v1/eyewear-studio
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')
Sunglasses photographed by the eyewear studio API
Kết quả mẫu

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')

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"
}

Tham số request

eyewear_image

Kiểu: stringBắt buộc

The eyewear product image — glasses or sunglasses. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

mode

Kiể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-model
sub_tool

Kiể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-laylifestylefloating
mannequin_id

Kiể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_angle

Kiểu: string

On-model only: the angle of the model's face.

= front

Giá trị: frontthree-quarterside-profile
expression

Kiểu: string

On-model only: the model's facial expression.

= neutral

Giá trị: neutralsoft-smileseriousconfident
lighting_style

Kiểu: string

On-model only: how the portrait is lit.

= soft-diffused

Giá trị: soft-diffusedstudionaturaldramatic
frame_fit_style

Kiểu: string

On-model only: the overall styling of how the frames are worn.

= casual

Giá trị: casualprofessionalfashion-editorialsporty
backdrop

Kiểu: string

Studio-shot only: the backdrop behind the eyewear.

= white

Giá trị: whitegrayblackgradient
lighting

Kiểu: string

Studio-shot only: the lighting setup.

= soft

Giá trị: softharddramaticnatural
surface

Kiểu: string

Flat-lay only: the surface the eyewear lies on.

= marble

Giá trị: marblewoodfabricconcretemetal
arrangement_style

Kiểu: string

Flat-lay only: how the composition is arranged.

= minimal

Giá trị: minimalsymmetricscatteredlayered
props

Kiểu: string

Flat-lay only: complementary props placed around the eyewear.

= none

Giá trị: noneplantsaccessoriestech
scene

Kiểu: string

Lifestyle only: the real-world setting.

= coffee-shop

Giá trị: coffee-shopbeachurban-streetofficepark
mood

Kiểu: string

Lifestyle only: the color mood of the scene.

= warm

Giá trị: warmcoolvibrantmoody
angle

Kiểu: string

Floating only: the camera angle on the suspended frames.

= front

Giá trị: frontthree-quartersidetop-down
shadow_style

Kiểu: string

Floating only: the shadow cast beneath the frames.

= soft-drop

Giá trị: soft-dropnonehard-dropreflection
background_color

Kiểu: string

Solid background color. Applies in both modes. Overridden by background_prompt when both are sent.

= white

Giá trị: whitegrayblackbeige
background_prompt

Kiểu: string

Free-text background description. Max 400 characters — excess is silently truncated. Overrides background_color.

aspect_ratio

Kiểu: string

Output aspect ratio.

= 3:4

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

Kiểu: string

Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.

= 2K

Giá trị: 2K4K

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.

Đầ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ề.

  1. 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.

  2. 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`.

  3. 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.

  4. 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.

  5. 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á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

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