Możliwość · Batch ghost mannequin

API batch ghost mannequin dla całych katalogów

W jednym zdaniu

Endpoint batch ghost mannequin platformy Photta przyjmuje tablicę zdjęć odzieży i zwraca identyfikator batcha oraz jeden identyfikator elementu na obraz. Credits dla całego batcha są rezerwowane z góry; odpytuj batch o stan zagregowany.

  • Typowy czas: 1.5–4 min per image
  • Credits: 4 credits w 2K · 5 credits w 4K
  • Przetwarzanie: asynchroniczne, polling
  • Limity: 600 requests/min
  • Uwierzytelnianie: Klucz Bearer

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono

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
Przykładowy wynik

W skrócie

W skrócie

Endpoint
POST /api/v1/ghost-mannequin/batch
Uwierzytelnianie
Klucz API Bearer
Przetwarzanie
Asynchroniczne — odpytuj endpoint statusu
Typowy czas
1.5–4 min per image
Credits
4 credits w 2K · 5 credits w 4K
Proporcje obrazu
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limity wejściowe
Do 10 MB na obraz; JPEG, PNG, WebP
Idempotentne
Nie

Żądanie i odpowiedź

Żądanie

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

Parametry żądania

product_images

Typ: array[object]Wymagane

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

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

Wartości: straightbackside
style

Typ: string

Applied to all images.

= 3d

Wartości: 3dflat_lay
background_color

Typ: string

Applied to all images.

= white

Wartości: whitegraybeigeblack
resolution

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

Wartości: 2K4K
aspect_ratio

Typ: string

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

= 3:4

Wartości: 3:41:14:39:1616:9
user_instruction

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

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

Błędy

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.

Limity

  • 600 żądań na minutę na klucz API (Stałe okno czasowe; limit jest taki sam w każdym planie)
  • Odpowiedź 429 zawiera nagłówek Retry-After: 30 s
  • Do 10 MB na obraz
  • Formaty: JPEG, PNG, WebP
  • Jednoczesne zadania wsadowe w zależności od planu: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Tylko polling — API nie wysyła webhooków.

Jedno żądanie, cały wieszak ubrań

Zbuduj tablicę, wyślij raz, odpytuj batch, pobierz każdy element.

  1. Krok 1

    Wygeneruj klucz API

    Batch ghost mannequin używa tych samych danych uwierzytelniających i tego samego salda credits, co każda inna funkcja Photta.

  2. Krok 2

    Zbuduj tablicę obrazów

    `product_images` przyjmuje jeden obiekt na ubranie: `image` oraz opcjonalne `back_image` i `image_side`. Limit batcha w API wynosi 5 obrazów w planach Free i Hobby, 10 w Seller, 25 w Brand i 50 w Studio.

  3. Krok 3

    Wyślij żądanie POST dla batcha

    POST `/api/v1/ghost-mannequin/batch`. Parametry `angle`, `style`, `background_color`, `resolution` i `aspect_ratio` mają zastosowanie do każdego elementu, a `user_instruction` dodaje jedną notatkę do 400 znaków dla wszystkich z nich. Credits dla całego batcha są rezerwowane przed wyrenderowaniem pierwszego elementu.

  4. Krok 4

    Odpytuj batch

    GET `/api/v1/ghost-mannequin/batch/:id` co 3 sekundy. Treść odpowiedzi zawiera `total`, `completed`, `failed` oraz podział na poszczególne elementy, dzięki czemu możesz rozpocząć pobieranie, zanim ostatnie ubranie zostanie przetworzone.

  5. Krok 5

    Pobierz każdy wynik

    Każdy ukończony element zawiera własny `output_url`, `credits_used` oraz czas trwania. Elementy, które zakończą się niepowodzeniem, zwracają zarezerwowane credits, co jest raportowane w `credits_refunded`.

Pytania, które programiści zadają przed uruchomieniem batchy

Co daje endpoint batch?

Przyjmuje tablicę zdjęć odzieży w jednym żądaniu i przetwarza je w tle. Otrzymujesz identyfikator batcha dla widoku zagregowanego oraz identyfikator elementu dla każdego zdjęcia, zamiast śledzić dziesiątki osobnych zadań.

Ile obrazów mieści się w jednym batchu?

Limit batcha w API wynosi 5 obrazów w planach Free i Hobby, 10 w Seller, 25 w Brand i 50 w Studio — pięć razy więcej niż limit w panelu. Przesłanie batcha większego niż pozwala na to Twój plan zwraca kod 400.

Jak naliczane są credits za batch?

Cały batch jest rezerwowany z góry: liczba obrazów pomnożona przez cenę za pojedynczy obraz, 4 credits w 2K lub 5 w 4K. Jeśli saldo nie pokrywa rezerwacji, żądanie zwraca kod 402 i nic nie jest renderowane.

Co się dzieje, gdy jeden element zakończy się niepowodzeniem?

Reszta batcha jest kontynuowana. Treść odpowiedzi batcha raportuje `failed` obok `completed`, a zarezerwowane credits za nieudane elementy wracają w `credits_refunded`.

Ile batchy może działać jednocześnie?

Liczba współbieżnych, aktywnych batchy jest ograniczona planem: Free 1, Hobby 2, Seller 3, Brand 4 i Studio 6. Wysłanie żądania przekraczającego limit zwraca kod 409 — odpytuj aktywny batch do momentu jego zakończenia, a następnie ponów próbę.

Jak odpytywać batch?

Wysyłaj GET `/api/v1/ghost-mannequin/batch/:id` co 3 sekundy, aby uzyskać stan zagregowany, lub odpytuj dowolny pojedynczy element na standardowej ścieżce stanu ghost mannequin, gdy potrzebujesz szczegółów dotyczących konkretnego ubrania.

Powiązane możliwości

Każda liczba na tej stronie pochodzi z dokumentacji API Photta · sprawdzono

Wypróbuj API w 5 minut

Wygeneruj klucz Photta API, wklej powyższy snippet cURL, a otrzymasz swoje pierwsze zdjęcie na modelu, zanim zaparzy się kawa.

  • 1.5–4 min per image
  • 4 credits w 2K · 5 credits w 4K
  • asynchroniczne, polling
  • 600 requests/min
  • Klucz Bearer