Yetenek · Toplu hayalet manken

Toplu hayalet manken API'si tüm kataloglar için

Tek cümlede

Photta'nın toplu hayalet manken endpoint'i bir kıyafet fotoğrafları dizisi alır; bir batch id ile görsel başına bir item id döndürür. Tüm grup için credits önceden rezerve edilir; toplu durum için grubu sorgulayın.

  • Tipik süre: 1.5–4 min per image
  • Credits: 2K'da 4 credits · 4K'da 5 credits
  • İşleme: asenkron, polling
  • Sınırlar: 600 istek/dk
  • Kimlik doğrulama: Bearer anahtarı

Bu sayfadaki her veri şuradan alınmıştır: Photta API dokümantasyonu · kontrol edildi

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
Örnek çıktı

Genel bakış

Genel bakış

Endpoint
POST /api/v1/ghost-mannequin/batch
Kimlik doğrulama
Bearer API anahtarı
İşleme
Asenkron — durum endpoint'ini sorgulayın (poll)
Tipik süre
1.5–4 min per image
Credits
2K'da 4 credits · 4K'da 5 credits
En-boy oranları
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Girdi sınırları
Görsel başına en fazla 10 MB; JPEG, PNG, WebP
Idempotent
Hayır

İstek ve yanıt

İstek

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

İstek parametreleri

product_images

Tür: array[object]Zorunlu

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

Tür: 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

Değerler: straightbackside
style

Tür: string

Applied to all images.

= 3d

Değerler: 3dflat_lay
background_color

Tür: string

Applied to all images.

= white

Değerler: whitegraybeigeblack
resolution

Tür: 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

Değerler: 2K4K
aspect_ratio

Tür: string

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

= 3:4

Değerler: 3:41:14:39:1616:9
user_instruction

Tür: 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

Tür: 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.

Hatalar

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.

Sınırlar

  • API anahtarı başına dakikada 600 istek (Sabit pencere; limit her planda aynıdır)
  • 429 yanıtı Retry-After: 30 saniye içerir
  • Görsel başına en fazla 10 MB
  • Formatlar: JPEG, PNG, WebP
  • Plan başına eşzamanlı toplu işlem: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Yalnızca polling — API webhook göndermez.

Tek istek, bir askı dolusu kıyafet

Diziyi oluşturun, bir kez gönderin, grubu sorgulayın, her öğeyi indirin.

  1. Adım 1

    Bir API anahtarı oluşturun

    Toplu hayalet manken, diğer tüm Photta yetenekleriyle aynı kimlik bilgilerini ve aynı kredi bakiyesini kullanır.

  2. Adım 2

    Görsel dizisini oluşturun

    `product_images` kıyafet başına bir nesne alır: `image` ile birlikte isteğe bağlı `back_image` ve `image_side`. API toplu işlem sınırı Free ve Hobby planlarında 5, Seller planında 10, Brand planında 25 ve Studio planında 50 görseldir.

  3. Adım 3

    Grubu POST edin

    POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution` ve `aspect_ratio` her öğeye uygulanır; `user_instruction` ise tümüne en fazla 400 karakterlik tek bir not ekler. Tüm grubun kredileri, ilk öğe render edilmeden önce rezerve edilir.

  4. Adım 4

    Grubu sorgulayın

    Her 3 saniyede bir GET `/api/v1/ghost-mannequin/batch/:id`. Gövde `total`, `completed`, `failed` ve öğe bazında bir döküm taşır; böylece son kıyafet tamamlanmadan indirmeye başlayabilirsiniz.

  5. Adım 5

    Her sonucu indirin

    Tamamlanan her öğe kendi `output_url`, `credits_used` ve süre bilgisini taşır. Başarısız olan öğeler rezerve edilen kredilerini iade eder ve bunlar `credits_refunded` içinde raporlanır.

Geliştiricilerin toplu işlemleri çalıştırmadan önce sorduğu sorular

Toplu işlem endpoint'i ne kazandırır?

Tek bir istekte bir kıyafet fotoğrafları dizisi kabul eder ve bunları arka planda işler. Onlarca ayrı işi takip etmek yerine, toplu görünüm için bir batch id ve fotoğraf başına bir item id alırsınız.

Bir gruba kaç görsel sığar?

API toplu işlem sınırı Free ve Hobby planlarında 5, Seller planında 10, Brand planında 25 ve Studio planında 50 görseldir — panel sınırının beş katı. Planınızın izin verdiğinden daha büyük bir grup 400 döndürür.

Bir grup için credits nasıl ücretlendirilir?

Tüm grup için önceden rezervasyon yapılır: görseller görsel başına fiyatla çarpılır; 2K'da 4 credits veya 4K'da 5 credits. Bakiye rezervasyonu karşılayamıyorsa istek 402 döndürür ve hiçbir şey render edilmez.

Bir öğe başarısız olduğunda ne olur?

Grubun geri kalanı devam eder. Grup gövdesi `completed` yanında `failed` durumunu da raporlar ve başarısız öğeler için rezerve edilen krediler `credits_refunded` içinde geri döner.

Aynı anda kaç toplu işlem çalışabilir?

Eşzamanlı devam eden gruplar plana göre sınırlandırılmıştır: Free 1, Hobby 2, Seller 3, Brand 4 ve Studio 6. Sınırın üzerinde gönderim yapmak 409 döndürür — etkin grup çözümlenene kadar sorgulayın, ardından tekrar gönderin.

Bir grubu nasıl sorgularım?

Toplu durum için her 3 saniyede bir GET `/api/v1/ghost-mannequin/batch/:id` yapın veya kıyafet bazında ayrıntı istediğinizde standart hayalet manken durum yolundan herhangi bir tekil öğeyi sorgulayın.

İlgili yetenekler

Bu sayfadaki her veri şuradan alınmıştır: Photta API dokümantasyonu · kontrol edildi

API'yi beş dakikada deneyin

Bir Photta API key oluşturun, yukarıdaki cURL kod parçacığını yapıştırın; kahveniz demlenmeden önce model üzerindeki ilk görselinizi alın.

  • 1.5–4 min per image
  • 2K'da 4 credits · 4K'da 5 credits
  • asenkron, polling
  • 600 istek/dk
  • Bearer anahtarı