Tính năng · Trang phục

Virtual try-on API cho trang phục

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

Virtual try-on API của Photta nhận ảnh trang phục trải sàn, mannequin ID cùng pose ID và trả về ảnh mẫu mặc đồ độ phân giải 2K hoặc 4K. POST job, polling mỗi 3–5 giây, tải xuống khi status là completed.

Lấy API key Đọc tài liệu

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 2026-09-10

POST/api/v1/tryon/apparel

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/tryon/apparel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_type": "top",
    "product_images": [
      "https://cdn.yourstore.com/products/shirt-front.jpg"
    ],
    "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
    "product_category": "t_shirt",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "body_size": "M",
    "expression": "neutral",
    "user_instruction": "Keep the collar pattern crisp and centered."
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/tryon/apparel",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_type": "top",
      "product_images": [
        "https://cdn.yourstore.com/products/shirt-front.jpg"
      ],
      "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
      "product_category": "t_shirt",
      "mannequin_id": "mnk_f3a9b1",
      "pose_id": "pose_c2d4e5",
      "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
      "lock_background": True,
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "body_size": "M",
      "expression": "neutral",
      "user_instruction": "Keep the collar pattern crisp and centered."
    },
)
data = res.json()["data"]  # data["id"], data["status"]

A garment rendered on an AI model by the apparel try-on API — Kết quả mẫu

Tổng quan nhanh

Endpoint: POST /api/v1/tryon/apparel
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/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/tryon/apparel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "product_type": "top",
    "product_images": [
      "https://cdn.yourstore.com/products/shirt-front.jpg"
    ],
    "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
    "product_category": "t_shirt",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "body_size": "M",
    "expression": "neutral",
    "user_instruction": "Keep the collar pattern crisp and centered."
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/tryon/apparel",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "product_type": "top",
      "product_images": [
        "https://cdn.yourstore.com/products/shirt-front.jpg"
      ],
      "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
      "product_category": "t_shirt",
      "mannequin_id": "mnk_f3a9b1",
      "pose_id": "pose_c2d4e5",
      "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
      "lock_background": True,
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "body_size": "M",
      "expression": "neutral",
      "user_instruction": "Keep the collar pattern crisp and centered."
    },
)
data = res.json()["data"]  # data["id"], data["status"]

202 Accepted / Completed

{
  "data": {
    "id": "try_abc123",
    "status": "processing",
    "product_type": "top",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "lock_background": true,
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-04-10T12:00:00Z"
  },
  "request_id": "req_xyz789"
}

{
  "data": {
    "id": "try_abc123",
    "status": "completed",
    "product_type": "top",
    "mannequin_id": "mnk_f3a9b1",
    "pose_id": "pose_c2d4e5",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "output_url": "https://cdn.photta.app/generated/try_abc123.jpg",
    "thumbnail_url": "https://cdn.photta.app/generated/try_abc123-thumb.jpg",
    "credits_used": 5,
    "created_at": "2026-04-10T12:00:00Z",
    "completed_at": "2026-04-10T12:01:15Z",
    "duration_ms": 75000
  },
  "request_id": "req_abc001"
}

Tham số request

TrườngMô tả

product_type

Kiểu: stringBắt buộc

Type of garment.

topbottomtop_and_bottomone_piece

product_images

Kiểu: array[string]Bắt buộc

Array of image URLs or base64 data URIs. The first entry is the FRONT image and is required. Not used when product_type is "top_and_bottom".

product_back_image

Kiểu: string

Optional URL or base64 data URI for the BACK of the garment. When supplied, the pipeline auto-switches to the back image whenever the selected pose is back-facing (Back / BackCloseUp). Not used when product_type is "top_and_bottom".

top_image

Kiểu: string

Front image of the top garment. Required when product_type is "top_and_bottom".

top_back_image

Kiểu: string

Optional back image of the top garment. Auto-selected on back-facing poses when present.

bottom_image

Kiểu: string

Front image of the bottom garment. Required when product_type is "top_and_bottom".

bottom_back_image

Kiểu: string

Optional back image of the bottom garment. Auto-selected on back-facing poses when present.

mannequin_id

Kiểu: stringBắt buộc

ID of the mannequin to wear the garment. Use GET /api/v1/mannequins to list available options.

pose_id

Kiểu: stringBắt buộc

ID of the pose. Use GET /api/v1/poses to list available options. The pose dictates the framing of the output — what's in frame, whether the face/feet are visible, full body vs half body, etc.

background

Kiểu: string

Optional URL or base64 data URI to a background photo. Anything that is not a URL or data: URI is rejected with HTTP 400. When omitted, an editorial neutral backdrop is used.

lock_background

Kiểu: boolean

When true, the supplied background image is reproduced faithfully (locked) instead of being treated as loose inspiration. Requires the background field — returns 400 if set without a background. Echoed back in the response object.

= false

resolution

Kiểu: string

Output resolution. 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

2K4K

aspect_ratio

Kiểu: string

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

= 3:4

3:41:14:39:1616:9

body_size

Kiểu: string

Body size of the mannequin.

= M

XSSMLXLXXL

expression

Kiểu: string

Facial expression.

= neutral

neutralhappyserioussmiling

footwear_url

Kiểu: string

URL or base64 of a custom footwear image. The pipeline always stages the footwear when supplied; the prompt's pose-authority block decides whether to render it (poses that don't show feet drop it cleanly).

user_instruction

Kiểu: string

Free-form refinement, e.g. "preserve the seam pattern across the shoulder", "keep the collar contrast strong". Capped at 500 characters server-side; longer strings are silently truncated. Useful for brand-specific details that need an extra nudge.

product_category

Kiểu: string

Optional silhouette anchor for the garment (e.g. "t_shirt", "jeans", "blazer", "midi_dress"). Helps disambiguate the structure of the garment when the silhouette is ambiguous from the photo alone. Used for product_type "top", "bottom", and "one_piece".

top_category

Kiểu: string

Silhouette anchor for the top half. Only valid when product_type is "top_and_bottom".

bottom_category

Kiểu: string

Silhouette anchor for the bottom half. Only valid when product_type is "top_and_bottom".

length

Kiểu: string

Garment length key for product_type "top", "bottom", or "one_piece". List available values with GET /api/v1/garment-attributes?type=length&garment_type={product_type}.

fit

Kiểu: string

Garment fit key for product_type "top", "bottom", or "one_piece". List available values with GET /api/v1/garment-attributes?type=fit&garment_type={product_type}.

top_length

Kiểu: string

Top length key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=length&garment_type=top.

top_fit

Kiểu: string

Top fit key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=fit&garment_type=top.

bottom_length

Kiểu: string

Bottom length key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=length&garment_type=bottom.

bottom_fit

Kiểu: string

Bottom fit key. Only valid when product_type is "top_and_bottom". List with GET /api/v1/garment-attributes?type=fit&garment_type=bottom.

Lỗi

Trạng tháiKiểuÝ nghĩa

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.

Năm bước, một ảnh sản phẩm

Chọn một mannequin, gửi job, polling cho đến khi hoàn tất, tải kết quả về.

Bước 1
Tạo một API key
Đăng ký tại ai.photta.app, mở tab Developers, nhấp Generate API key. Live key bắt đầu bằng `photta_live_`. Đặt key vào `PHOTTA_API_KEY` — tuyệt đối không commit.
Bước 2
Chọn mannequin và tư thế
GET `/api/v1/mannequins` để lấy danh sách tùy chọn khả dụng. GET `/api/v1/poses` để chọn khung hình. Cả hai ID đều được đưa vào request try-on.
Bước 3
POST job try-on
Gửi một POST đến `/api/v1/tryon/apparel` với `product_type`, `product_images`, `mannequin_id`, `pose_id` cùng `resolution` và `aspect_ratio` tùy chọn. API trả về 202 Accepted kèm generation ID.
Bước 4
Polling cho đến khi job hoàn tất
GET `/api/v1/tryon/apparel/:id` mỗi 3 giây. Khi `data.status` chuyển sang `completed`, payload sẽ bao gồm `output_url` và `thumbnail_url`. Hãy đặt giới hạn trên để job bị treo không làm nghẽn request của bạn.
Bước 5
Tải về và lưu trữ
Fetch các byte từ `output_url` và lưu chúng vào object storage của riêng bạn. URL CDN ổn định nhưng sản phẩm của bạn không nên phụ thuộc vào nó để render.

Cùng một endpoint trên Node.js, Python và cURL

Những câu hỏi lập trình viên đặt ra trước khi triển khai try-on trang phục

API virtual try-on của Photta là gì?

Một REST endpoint nhận ảnh sản phẩm chụp trải sàn (flat-lay) cùng mannequin ID và trả về ảnh mặc trên người mẫu chân thực. Cùng một pipeline với ứng dụng cho người dùng cuối của Photta. Hỗ trợ 4 loại sản phẩm: top, bottom, top+bottom, one-piece.

Chi phí mỗi lượt gọi là bao nhiêu?

5 credits cho kết quả 2K, 6 credits cho 4K. Credits đi kèm gói thuê bao của bạn và có thể nạp thêm. Các lượt tạo thất bại không tốn credits — chúng sẽ được hoàn lại.

Mất bao lâu để hoàn tất một lượt tạo?

Thời gian hoàn tất thông thường từ 1.5 đến 4 phút, đo lường toàn trình (end to end). Lệnh POST trả về generation ID trong chưa đầy 1 giây; GPU xử lý ngầm trong khi bạn polling.

Những loại sản phẩm nào được hỗ trợ?

Bốn loại: `top`, `bottom`, `top_and_bottom`, `one_piece`. Mỗi loại yêu cầu cấu trúc `product_images` khác nhau — ví dụ `top_and_bottom` cần cả URL của `top_image` lẫn `bottom_image`.

Tôi có thể dùng mannequin của riêng mình không?

Được. Tải ảnh mannequin lên bằng `POST /api/v1/mannequins` hoặc tạo một AI mannequin mới bằng `POST /api/v1/mannequins/generate`. ID trả về có thể gắn trực tiếp vào request try-on.

Tôi polling kết quả như thế nào?

GET `/api/v1/tryon/apparel/:id` mỗi 3 đến 5 giây cho đến khi `data.status` là `completed` hoặc `failed`. Hãy đặt giới hạn trên cho số lần thử — 120 × 3s là thừa đủ bao trọn khoảng thời gian theo 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 2026-09-10

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

Tạo tài khoản và lấy API key Đọc tài liệu

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

Virtual try-on API cho trang phục

Tổng quan nhanh

Request và response

Tham số request

Lỗi

Năm bước, một ảnh sản phẩm

Tạo một API key

Chọn mannequin và tư thế

POST job try-on

Polling cho đến khi job hoàn tất

Tải về và lưu trữ

Cùng một endpoint trên Node.js, Python và cURL

Những câu hỏi lập trình viên đặt ra trước khi triển khai try-on trang phục

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

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