Tính năng · Batch ghost mannequin

Batch ghost mannequin API dành cho toàn bộ catalog

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

Endpoint batch ghost mannequin của Photta nhận một mảng ảnh trang phục và trả về một batch id cùng một item id cho mỗi ảnh. Credits cho toàn bộ batch được giữ trước; poll batch để lấy trạng thái tổng hợp.

  • Thời gian điển hình: 1.5–4 min per image
  • 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/batch
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin/batch \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_images": [
    {
      "image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/shirt-front.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/trousers-front.jpg",
      "image_side": "front"
    }
  ],
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, buttoned up",
  "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/batch
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 per image
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/batch \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_images": [
    {
      "image": "https://cdn.yourstore.com/products/jacket-front.jpg",
      "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/shirt-front.jpg",
      "image_side": "front"
    },
    {
      "image": "https://cdn.yourstore.com/products/trousers-front.jpg",
      "image_side": "front"
    }
  ],
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, buttoned up",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Completed

{
  "data": {
    "batch_id": "gmb_x7y8z9",
    "status": "processing",
    "total": 3,
    "completed": 0,
    "failed": 0,
    "items": [
      {
        "id": "gm_p1q2r3",
        "status": "processing"
      },
      {
        "id": "gm_s4t5u6",
        "status": "processing"
      },
      {
        "id": "gm_v7w8x9",
        "status": "processing"
      }
    ],
    "style": "3d",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_reserved": 12,
    "created_at": "2026-04-10T16:05:00Z"
  },
  "request_id": "req_gmb001"
}

Tham số request

product_images

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

Array of image objects. Each object contains "image" (URL or base64), optional "back_image", and optional "image_side". API batch caps (5× the dashboard limit): Free/Hobby/Hobby v2 5, Seller/Starter 10, Brand/Pro 25, Studio/Premium 50.

angle

Kiểu: string

Applied to all images. "side" reconstructs the side view from each front photo (plus back_image when provided) — see the single-generate endpoint for details.

= straight

Giá trị: straightbackside
style

Kiểu: string

Applied to all images.

= 3d

Giá trị: 3dflat_lay
background_color

Kiểu: string

Applied to all images.

= white

Giá trị: whitegraybeigeblack
resolution

Kiểu: string

Applied to all images. "2K" = 4 credits each. "4K" = 5 credits each. 4K is produced natively in a single generation per item — 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

Applied to all images. 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

Batch-level: one note applied to every item. Optional free-form string, 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

Applied to all images. Brand label UUID returned by the Brand Labels API. 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.

Một request, xử lý cả loạt trang phục

Tập hợp mảng dữ liệu, submit một lần, poll batch, tải xuống từng item.

  1. Bước 1

    Tạo API key

    Batch ghost mannequin dùng chung thông tin xác thực và số dư credits như mọi tính năng khác của Photta.

  2. Bước 2

    Tập hợp mảng ảnh

    `product_images` nhận một object cho mỗi trang phục: `image`, cùng `back_image` và `image_side` tùy chọn. Giới hạn batch của API là 5 ảnh trên gói Free và Hobby, 10 trên Seller, 25 trên Brand và 50 trên Studio.

  3. Bước 3

    POST batch

    POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution` và `aspect_ratio` áp dụng cho mọi item, và `user_instruction` thêm một ghi chú tối đa 400 ký tự cho tất cả các item đó. Credits cho toàn bộ batch được giữ trước khi item đầu tiên bắt đầu render.

  4. Bước 4

    Poll batch

    GET `/api/v1/ghost-mannequin/batch/:id` mỗi 3 giây một lần. Body trả về gồm `total`, `completed`, `failed` và chi tiết từng item, giúp bạn có thể bắt đầu tải xuống trước khi trang phục cuối cùng xử lý xong.

  5. Bước 5

    Tải xuống từng kết quả

    Mỗi item hoàn thành đều có `output_url`, `credits_used` và thời gian xử lý riêng. Các item thất bại sẽ được hoàn lại credits đã giữ và được ghi nhận trong `credits_refunded`.

Các câu hỏi lập trình viên thường đặt ra trước khi chạy batch

Endpoint batch mang lại lợi ích gì?

Nó nhận một mảng ảnh trang phục trong một request duy nhất và xử lý chúng ở chế độ nền. Bạn nhận được một batch id để theo dõi tổng thể và một item id cho mỗi ảnh, thay vì phải theo dõi hàng tá tác vụ riêng biệt.

Một batch chứa được bao nhiêu ảnh?

Giới hạn batch của API là 5 ảnh trên gói Free và Hobby, 10 trên Seller, 25 trên Brand và 50 trên Studio — gấp năm lần giới hạn trên dashboard. Gửi một batch vượt quá gói cho phép sẽ trả về lỗi 400.

Credits được tính như thế nào cho một batch?

Toàn bộ batch được giữ credits trước: số lượng ảnh nhân với đơn giá mỗi ảnh, 4 credits ở 2K hoặc 5 credits ở 4K. Nếu số dư không đủ để giữ credits, request sẽ trả về lỗi 402 và không có gì được render.

Điều gì xảy ra khi một item bị lỗi?

Phần còn lại của batch vẫn tiếp tục xử lý. Body của batch sẽ báo cáo số lượng `failed` bên cạnh `completed`, và credits đã giữ cho các item thất bại sẽ được hoàn lại trong `credits_refunded`.

Có thể chạy cùng lúc bao nhiêu batch?

Số lượng batch in-flight đồng thời bị giới hạn theo gói: Free 1, Hobby 2, Seller 3, Brand 4 và Studio 6. Gửi vượt quá giới hạn sẽ trả về lỗi 409 — hãy poll batch đang hoạt động cho đến khi hoàn tất, sau đó gửi lại.

Làm thế nào để poll một batch?

GET `/api/v1/ghost-mannequin/batch/:id` mỗi 3 giây một lần để lấy trạng thái tổng hợp, hoặc poll bất kỳ item đơn lẻ nào theo đường dẫn trạng thái ghost mannequin tiêu chuẩn khi bạn muốn xem chi tiết từng trang phụ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 per image
  • 4 credits ở 2K · 5 credits ở 4K
  • async, polling
  • 600 requests/min
  • Bearer key