Ominaisuus · Batch ghost mannequin

Batch ghost mannequin -API kokonaisille katalogeille

Yhdellä lauseella

Phottan batch ghost mannequin -endpoint vastaanottaa taulukon vaatekuvia ja palauttaa batch-tunnisteen sekä yhden kohdetunnisteen kuvaa kohden. Koko erän credits-yksiköt varataan etukäteen; pollaa erää nähdäksesi kootun tilan.

  • Tyypillinen kesto: 1.5–4 min per image
  • Credits: 4 credits resoluutiolla 2K · 5 credits resoluutiolla 4K
  • Käsittely: asynkroninen, polling
  • Rajoitukset: 600 pyyntöä/min
  • Autentikointi: Bearer-avain

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu

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
Esimerkkitulos

Lyhyesti

Lyhyesti

Endpoint
POST /api/v1/ghost-mannequin/batch
Autentikointi
Bearer-API-avain
Käsittely
Asynkroninen — tee polling-kyselyitä status-endpointiin
Tyypillinen kesto
1.5–4 min per image
Credits
4 credits resoluutiolla 2K · 5 credits resoluutiolla 4K
Kuvasuhteet
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Syöterajoitukset
Enintään 10 MB per kuva; JPEG, PNG, WebP
Idempotentti
Ei

Pyyntö ja vastaus

Pyyntö

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

Pyyntöparametrit

product_images

Tyyppi: array[object]Pakollinen

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

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

Arvot: straightbackside
style

Tyyppi: string

Applied to all images.

= 3d

Arvot: 3dflat_lay
background_color

Tyyppi: string

Applied to all images.

= white

Arvot: whitegraybeigeblack
resolution

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

Arvot: 2K4K
aspect_ratio

Tyyppi: string

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

= 3:4

Arvot: 3:41:14:39:1616:9
user_instruction

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

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

Virheet

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.

Rajoitukset

  • 600 pyyntöä minuutissa per API-avain (Kiinteä aikaikkuna; rajoitus on sama kaikissa tilauksissa)
  • Vastaus 429 sisältää otsakkeen Retry-After: 30 sekuntia
  • Enintään 10 MB per kuva
  • Formaatit: JPEG, PNG, WebP
  • Rinnakkaiset eräajot per tilaus: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Vain polling — API ei lähetä webhookeja.

Yksi pyyntö, rekillinen vaatteita

Kokoa taulukko, lähetä kerran, pollaa erää, lataa kukin kohde.

  1. Vaihe 1

    Luo API-avain

    Batch ghost mannequin käyttää samoja tunnisteita ja samaa credits-saldoa kuin kaikki muutkin Phottan ominaisuudet.

  2. Vaihe 2

    Kokoa kuvataulukko

    `product_images` ottaa vastaan yhden objektin vaatetta kohden: `image` sekä valinnaiset `back_image` ja `image_side`. API:n eräkohtainen yläraja on 5 kuvaa (Free ja Hobby), 10 (Seller), 25 (Brand) ja 50 (Studio).

  3. Vaihe 3

    Tee erästä POST-pyyntö

    POST `/api/v1/ghost-mannequin/batch`. Parametrit `angle`, `style`, `background_color`, `resolution` ja `aspect_ratio` koskevat jokaista kohdetta, ja `user_instruction` lisää enintään 400 merkin huomautuksen niihin kaikkiin. Koko erän credits-yksiköt varataan ennen ensimmäisenkään kohteen renderöintiä.

  4. Vaihe 4

    Pollaa erää

    GET `/api/v1/ghost-mannequin/batch/:id` 3 sekunnin välein. Vastausrunko sisältää kentät `total`, `completed`, `failed` ja kohteenkohtaisen erittelyn, joten voit aloittaa lataamisen ennen kuin viimeinenkin vaate on valmis.

  5. Vaihe 5

    Lataa kukin tulos

    Jokainen valmistunut kohde sisältää omat kenttänsä `output_url`, `credits_used` ja keston. Epäonnistuneet kohteet palauttavat niille varatut credits-yksiköt, ja ne raportoidaan kentässä `credits_refunded`.

Kysymyksiä, joita kehittäjät kysyvät ennen erien ajamista

Mitä batch-endpoint tuo lisää?

Se ottaa vastaan taulukollisen vaatekuvia yhdellä pyynnöllä ja käsittelee ne taustalla. Saat batch-tunnisteen koottua näkymää varten ja kohdetunnisteen kuvaa kohden sen sijaan, että joutuisit seuraamaan kymmeniä erillisiä töitä.

Kuinka monta kuvaa yhteen erään mahtuu?

API:n eräkohtainen yläraja on 5 kuvaa (Free ja Hobby), 10 (Seller), 25 (Brand) ja 50 (Studio) — viisinkertaisesti hallintapaneelin rajaan verrattuna. Tilaustasosi sallimaa rajaa suurempi erä palauttaa koodin 400.

Miten credits-veloitukset toimivat erissä?

Koko erä varataan etukäteen: kuvien määrä kerrottuna kuvakohtaisella hinnalla, 4 credits resoluutiolla 2K tai 5 resoluutiolla 4K. Jos saldo ei kata varausta, pyyntö palauttaa koodin 402 eikä mitään renderöidä.

Mitä tapahtuu, kun yksi kohde epäonnistuu?

Loput erästä jatkavat käsittelyä. Erän runko raportoi tilan `failed` tilan `completed` rinnalla, ja epäonnistuneiden kohteiden varatut credits-yksiköt palautuvat kentässä `credits_refunded`.

Kuinka monta erää voi ajaa samanaikaisesti?

Samanaikaisten aktiivisten erien määrä on rajattu tilaustason mukaan: Free 1, Hobby 2, Seller 3, Brand 4 ja Studio 6. Rajan ylittävä lähetys palauttaa koodin 409 — pollaa aktiivista erää, kunnes se valmistuu, ja lähetä sitten uudelleen.

Miten pollaan erää?

GET `/api/v1/ghost-mannequin/batch/:id` 3 sekunnin välein kootun tilan saamiseksi, tai pollaa mitä tahansa yksittäistä kohdetta vakiomuotoisesta ghost mannequin -tilapolusta, kun haluat vaatekohtaiset tiedot.

Liittyvät ominaisuudet

Jokainen luku tällä sivulla on peräisin Photta-rajapinnan dokumentaatiosta · tarkistettu

Kokeile APIa viidessä minuutissa

Luo Photta-API-avain, liitä yllä oleva cURL-koodinpätkä, ja sinulla on ensimmäinen mallikuva ennen kuin kahvi ehtii tippua.

  • 1.5–4 min per image
  • 4 credits resoluutiolla 2K · 5 credits resoluutiolla 4K
  • asynkroninen, polling
  • 600 pyyntöä/min
  • Bearer-avain