Kapabilitas · Batch ghost mannequin

API batch ghost mannequin untuk seluruh katalog

Ringkasan singkat

Endpoint batch ghost mannequin Photta menerima array foto pakaian dan mengembalikan satu id batch ditambah satu id item per gambar. Credits untuk seluruh batch direservasi di muka; lakukan polling pada batch untuk status agregat.

Dapatkan API key Baca dokumentasi

Waktu umum: 1.5–4 min per image
Credits: 4 credits pada 2K · 5 credits pada 4K
Pemrosesan: async, polling
Batasan: 600 requests/min
Autentikasi: Bearer key

Setiap angka di halaman ini bersumber dari dokumentasi API Photta · diperiksa 2026-09-10

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

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

import 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"]

A garment shown without its mannequin by the ghost mannequin API — Contoh output

Sekilas

Endpoint: POST /api/v1/ghost-mannequin/batch
Autentikasi: API key Bearer
Pemrosesan: Asinkron — lakukan polling ke endpoint status
Waktu umum: 1.5–4 min per image
Credits: 4 credits pada 2K · 5 credits pada 4K
Rasio aspek: 3:4 · 1:1 · 4:3 · 9:16 · 16:9
Batas input: Hingga 10 MB per gambar; JPEG, PNG, WebP
Idempoten: Tidak

Request dan 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.status

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

Parameter request

FieldDeskripsi

product_images

Tipe: array[object]Wajib

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

Tipe: 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

straightbackside

style

Tipe: string

Applied to all images.

= 3d

3dflat_lay

background_color

Tipe: string

Applied to all images.

= white

whitegraybeigeblack

resolution

Tipe: 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

2K4K

aspect_ratio

Tipe: string

Applied to all images. Note: 1:1 is not available at 4K resolution — 1:1 combined with 4K returns 400.

= 3:4

3:41:14:39:1616:9

user_instruction

Tipe: 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

Tipe: 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.

Error

StatusTipeArti

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.

Batasan

600 request per menit per API key (Fixed window; batasannya sama di setiap paket)
Respons 429 menyertakan Retry-After: 30 detik
Hingga 10 MB per gambar
Format: JPEG, PNG, WebP
Batch konkuren per paket: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
Hanya polling — API tidak mengirim webhook.

Satu request, sederet pakaian

Susun array, kirim sekali, lakukan polling batch, unduh setiap item.

Langkah 1
Buat API key
Batch ghost mannequin menggunakan kredensial yang sama dan saldo credit yang sama seperti setiap kapabilitas Photta lainnya.
Langkah 2
Susun array gambar
`product_images` menerima satu objek per pakaian: `image`, ditambah `back_image` dan `image_side` opsional. Batas batch API adalah 5 gambar pada Free dan Hobby, 10 pada Seller, 25 pada Brand, dan 50 pada Studio.
Langkah 3
POST batch
POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution`, dan `aspect_ratio` berlaku untuk setiap item, dan `user_instruction` menambahkan satu instruksi hingga 400 karakter untuk semuanya. Credits untuk seluruh batch direservasi sebelum item pertama dirender.
Langkah 4
Lakukan polling pada batch
GET `/api/v1/ghost-mannequin/batch/:id` setiap 3 detik. Body memuat `total`, `completed`, `failed`, dan rincian per item, sehingga Anda dapat mulai mengunduh sebelum pakaian terakhir selesai diproses.
Langkah 5
Unduh setiap hasil
Setiap item yang selesai membawa `output_url`, `credits_used`, dan durasinya sendiri. Item yang gagal akan mengembalikan credits yang telah direservasi dan dilaporkan dalam `credits_refunded`.

Endpoint yang sama dalam Node.js, Python, dan cURL

Pertanyaan yang diajukan developer sebelum menjalankan batch

Apa nilai tambah dari endpoint batch?

Endpoint ini menerima array foto pakaian dalam satu request dan memprosesnya di latar belakang. Anda mendapatkan satu id batch untuk tampilan agregat dan satu id item per foto, alih-alih melacak puluhan tugas terpisah.

Berapa banyak gambar yang muat dalam satu batch?

Batas batch API adalah 5 gambar pada Free dan Hobby, 10 pada Seller, 25 pada Brand, dan 50 pada Studio — lima kali lipat batas dasbor. Batch yang lebih besar dari batas paket Anda akan mengembalikan 400.

Bagaimana credits ditagihkan untuk sebuah batch?

Seluruh batch direservasi di muka: jumlah gambar dikalikan dengan harga per gambar, 4 credits pada 2K atau 5 pada 4K. Jika saldo tidak mencukupi reservasi, request mengembalikan 402 dan tidak ada yang dirender.

Apa yang terjadi jika satu item gagal?

Sisa batch tetap dilanjutkan. Body batch melaporkan `failed` bersamaan dengan `completed`, dan credits yang direservasi untuk item yang gagal akan dikembalikan dalam `credits_refunded`.

Berapa banyak batch yang dapat berjalan bersamaan?

Batch berjalan konkuren dibatasi per paket: Free 1, Hobby 2, Seller 3, Brand 4, dan Studio 6. Mengirim melebihi batas akan mengembalikan 409 — lakukan polling pada batch yang aktif hingga selesai, lalu kirim ulang.

Bagaimana cara melakukan polling pada batch?

GET `/api/v1/ghost-mannequin/batch/:id` setiap 3 detik untuk status agregat, atau lakukan polling pada item tunggal mana pun di path status ghost mannequin standar ketika Anda membutuhkan detail per pakaian.

Kapabilitas terkait

Setiap angka di halaman ini bersumber dari dokumentasi API Photta · diperiksa 2026-09-10

Coba API dalam lima menit

Buat Photta API key, tempel cuplikan cURL di atas, dan Anda akan mendapatkan gambar on-model pertama sebelum kopi selesai diseduh.

Buat akun dan dapatkan API key Baca dokumentasi

1.5–4 min per image
4 credits pada 2K · 5 credits pada 4K
async, polling
600 requests/min
Bearer key

API batch ghost mannequin untuk seluruh katalog

Sekilas

Request dan response

Parameter request

Error

Satu request, sederet pakaian

Buat API key

Susun array gambar

POST batch

Lakukan polling pada batch

Unduh setiap hasil

Endpoint yang sama dalam Node.js, Python, dan cURL

Pertanyaan yang diajukan developer sebelum menjalankan batch

Kapabilitas terkait

Coba API dalam lima menit