Tính năng · Ghost mannequin

API ghost mannequin dành cho ảnh sản phẩm kiểu người vô hình

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

API ghost mannequin của Photta nhận ảnh trang phục chụp trên mannequin và trả về ảnh mannequin vô hình với phần bên trong của trang phục được tái tạo lại. Chọn style 3d hoặc flat_lay, POST, poll mỗi 3 giây, tải xuống khi hoàn thành.

  • Thời gian điển hình: 1.5–4 min
  • Credits: 4 credits ở 2K · 5 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/ghost-mannequin
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
A garment shown without its mannequin by the ghost mannequin API
Kết quả mẫu

Tổng quan nhanh

Tổng quan nhanh

Endpoint
POST /api/v1/ghost-mannequin
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
4 credits ở 2K · 5 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/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Completed

{
  "data": {
    "id": "gm_d4e5f6",
    "status": "processing",
    "style": "3d",
    "angle": "side",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 4,
    "created_at": "2026-04-10T16:00:00Z"
  },
  "request_id": "req_gm001"
}

Tham số request

product_image

Kiểu: stringBắt buộc

URL or base64 data URI of the garment photo (front or back, on a mannequin or flat).

back_image

Kiểu: string

URL or base64 data URI of the opposite side — helps the AI reconstruct the interior of the garment for a more realistic 3D effect.

image_side

Kiểu: string

Which side product_image represents.

= front

Giá trị: frontback
angle

Kiểu: string

Camera angle for the output. "side" is worth calling out: the side view is reconstructed from the front photo (plus the back photo when provided), giving you a third catalog view without a third photoshoot — and it works well even on textured garments (crochet, lace, embroidery).

= straight

Giá trị: straightbackside
style

Kiểu: string

Output style: "3d" (ghost mannequin with 3D body shape) or "flat_lay" (garment laid flat, mannequin removed).

= 3d

Giá trị: 3dflat_lay
background_color

Kiểu: string

Background color.

= white

Giá trị: whitegraybeigeblack
resolution

Kiểu: string

Output resolution. "2K" costs 4 credits per image; "4K" costs 5 credits per image. 4K is produced natively in a single generation — pick it upfront; the resolution cannot be changed after creation. Note: 4K cannot be combined with aspect_ratio 1:1 — that combination returns 400.

= 2K

Giá trị: 2K4K
aspect_ratio

Kiểu: string

Output aspect ratio. Note: 1:1 is not available at 4K resolution — 1:1 combined with 4K returns 400.

= 3:4

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

Kiểu: string

Optional free-form note, max 400 characters (anything longer is silently truncated). A guarded steer for ambiguous rendering choices — e.g. "closed front", "cream interior lining", "buttoned up" — it never overrides the source garment, brand label, or structural reconstruction, and it is explicitly NOT a determinism/seed control.

brand_label_id

Kiểu: string

Brand label UUID returned by the Brand Labels API. Applied to the generated garment when present. API v1 request fields use snake_case; use brand_label_id.

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 một ảnh, đầu ra một ảnh ma-nơ-canh vô hình

Tải ảnh gốc lên, chọn một style, gửi yêu cầu, polling, tải về.

  1. Bước 1

    Tạo một API key

    Ghost mannequin sử dụng chung thông tin xác thực với mọi tính năng khác của Photta — một key, một số dư credits.

  2. Bước 2

    Tải ảnh gốc lên

    Truyền một URL công khai hoặc data URI dạng base64 vào `product_image`; thêm `back_image` khi bạn có ảnh mặt sau. Định dạng JPEG, PNG và WebP tối đa 10 MB mỗi ảnh.

  3. Bước 3

    POST job ghost mannequin

    POST tới `/api/v1/ghost-mannequin` với `product_image`, `style` (`3d` hoặc `flat_lay`) và các tham số tùy chọn `angle`, `background_color`, `resolution`. Polling là tín hiệu hoàn thành duy nhất — API không gửi webhook.

  4. Bước 4

    Poll cho đến khi job hoàn thành

    GET `/api/v1/ghost-mannequin/:id` mỗi 3 giây cho đến khi `data.status` là `completed` hoặc `failed`; thời gian hoàn thành thông thường từ 1.5 đến 4 phút.

  5. Bước 5

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

    Kết quả trả về là file PNG đã được xóa ma-nơ-canh và tái tạo phần bên trong của trang phục. Lý tưởng cho ảnh ghost chụp trang PDP, thư viện sản phẩm tạo cảm giác 3D và ảnh chèn dạng flat-lay.

Các câu hỏi kỹ sư thường đặt ra trước khi triển khai ghost mannequin

Nhiếp ảnh ghost mannequin là gì?

Một hình thức xử lý ảnh cho PDP, trong đó trang phục trông như đang mặc trên một cơ thể vô hình, hiển thị đồng thời cả phom dáng lẫn cấu trúc bên trong. Trước đây, kiểu ảnh này phải ghép từ nhiều bức ảnh chụp studio; API của Photta xử lý xong chỉ trong một lệnh gọi duy nhất từ một bức ảnh chụp trên ma-nơ-canh.

Ghost mannequin có giá bao nhiêu?

4 credits ở độ phân giải 2K, 5 credits ở độ phân giải 4K — rẻ hơn 1 credit ở mỗi gói so với try-on. Các job lỗi sẽ được tự động hoàn trả.

Sự khác biệt giữa style 3D và style flat-lay là gì?

Style `3d` giữ nguyên phom dáng cơ thể 3 chiều của ma-nơ-canh — trang phục vẫn giữ được độ phồng, phần vai và tay áo hiển thị tự nhiên, và mặt trong được tái tạo. Style `flat_lay` ép phẳng trang phục thành bố cục 2D gọn gàng, lý tưởng cho các bộ sưu tập capsule hoặc danh sách sản phẩm trên sàn thương mại điện tử vốn yêu cầu hình dạng trực diện đồng nhất.

Tôi có thể xử lý hàng loạt nhiều ảnh cùng lúc không?

Có. POST tới `/api/v1/ghost-mannequin/batch` với một mảng các ảnh gốc. Phản hồi sẽ trả về cho bạn một batch ID kèm theo các generation ID của từng mục. Poll `/api/v1/ghost-mannequin/batch/:id` để lấy trạng thái tổng hợp hoặc poll từng mục riêng lẻ.

API có giữ lại đường may bên trong và nhãn mác không?

Có — mô hình sẽ tái tạo mặt trong của trang phục (mặt trong cổ áo, mặt trong cổ tay, lớp lót cạp quần) thay vì tự suy diễn ra một bề mặt chung chung. Nhãn mác và mác in nhìn thấy được trên ảnh gốc sẽ được giữ lại khi khả thi.

Làm thế nào để poll kết quả?

GET `/api/v1/ghost-mannequin/:id` mỗi 3 giây. Đối với batch job, hãy poll endpoint cha để nhận trạng thái tổng hợp kèm theo chi tiết từng mục.

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

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