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
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')const res = await fetch("https://api.photta.app/api/v1/ghost-mannequin/batch", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/ghost-mannequin/batch",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]
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')const res = await fetch("https://api.photta.app/api/v1/ghost-mannequin/batch", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/ghost-mannequin/batch",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"batch_id": "gmb_x7y8z9",
"status": "completed",
"total": 3,
"completed": 3,
"failed": 0,
"processing": 0,
"credits_reserved": 12,
"credits_used": 12,
"credits_refunded": 0,
"items": [
{
"id": "gm_p1q2r3",
"status": "completed",
"output_url": "https://cdn.photta.app/generated/gm_p1q2r3.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/gm_p1q2r3-thumb.jpg",
"credits_used": 4,
"completed_at": "2026-04-10T16:06:42Z",
"duration_ms": 102000
},
{
"id": "gm_s4t5u6",
"status": "completed",
"output_url": "https://cdn.photta.app/generated/gm_s4t5u6.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/gm_s4t5u6-thumb.jpg",
"credits_used": 4,
"completed_at": "2026-04-10T16:08:18Z",
"duration_ms": 96000
},
{
"id": "gm_v7w8x9",
"status": "completed",
"output_url": "https://cdn.photta.app/generated/gm_v7w8x9.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/gm_v7w8x9-thumb.jpg",
"credits_used": 4,
"completed_at": "2026-04-10T16:09:50Z",
"duration_ms": 92000
}
],
"created_at": "2026-04-10T16:05:00Z",
"completed_at": "2026-04-10T16:09:50Z"
},
"request_id": "req_gmbs002"
}Tham số request
product_imagesKiể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.
angleKiể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ị:straightbacksidestyleKiểu: string
Applied to all images.
= 3d
Giá trị:3dflat_laybackground_colorKiểu: string
Applied to all images.
= white
Giá trị:whitegraybeigeblackresolutionKiể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ị:2K4Kaspect_ratioKiể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:9user_instructionKiể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_idKiể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
- 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.
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.
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.
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.
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.
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.
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ùng một endpoint trên Node.js, Python và cURL
Node.js
Batch ghost mannequin API trong Node.js
Gọi batch ghost mannequin API 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
Batch ghost mannequin API trong Python
Gọi batch ghost mannequin API 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
Batch ghost mannequin API với cURL
Gọi trực tiếp batch ghost mannequin API 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 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
Tính năng
API ghost mannequin dành cho ảnh sản phẩm kiểu người vô hình
AI ghost mannequin endpoint. Xóa bỏ mannequin khỏi ảnh chụp trang phục và bảo toàn chi tiết bên trong. Dạng 3D hoặc flat-lay, xử lý hàng loạt, 4 credits ở 2K.
Xem endpointTí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 endpointXây dựng
Tự động hóa tác vụ tách ghost mannequin cho danh mục sản phẩm của bạn
Công thức tự động hóa danh mục hàng đêm: lấy các bản cập nhật sản phẩm từ hôm qua, gửi batch lên ghost-mannequin API của Photta, polling batch cha, lưu dữ liệu vào cơ sở dữ liệu của bạn.
Xem endpointSo sánh
Photta vs Pixazo — pipeline tự phát triển hay nền tảng tổng hợp mô hình
So sánh Photta vs Pixazo: pipeline thời trang độc quyền so với nền tảng tổng hợp đa mô hình. Endpoint, độ trễ, gói miễn phí và các đánh đổi kỹ thuật. Dữ liệu trích xuất ngày 2026-04-19.
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ê.
- 1.5–4 min per image
- 4 credits ở 2K · 5 credits ở 4K
- async, polling
- 600 requests/min
- Bearer key