Funktion · Batch-ghost-mannekäng

API för batch-ghost-mannekäng för hela kataloger

I en mening

Phottas batch-endpoint för ghost-mannekäng tar emot en array med plaggfoton och returnerar ett batch-id samt ett objekt-id per bild. Credits för hela batchen reserveras i förväg; polla batchen för samlad status.

Hämta en API-nyckelLäs dokumentationen
  • Typisk tid: 1.5–4 min per image
  • Credits: 4 credits vid 2K · 5 credits vid 4K
  • Bearbetning: asynkron, polling
  • Gränser: 600 requests/min
  • Autentisering: Bearer-nyckel

Varje siffra på den här sidan kommer från Photter API-dokumentationen · kontrollerad

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
Exempelutdata

I korthet

I korthet

Endpoint
POST /api/v1/ghost-mannequin/batch
Autentisering
Bearer API-nyckel
Bearbetning
Asynkron — polla status-endpointen
Typisk tid
1.5–4 min per image
Credits
4 credits vid 2K · 5 credits vid 4K
Bildförhållanden
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Indatagränser
Upp till 10 MB per bild; JPEG, PNG, WebP
Idempotent
Nej

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

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

Request-parametrar

product_images

Typ: array[object]Obligatorisk

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

Värden: straightbackside
style

Typ: string

Applied to all images.

= 3d

Värden: 3dflat_lay
background_color

Typ: string

Applied to all images.

= white

Värden: 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

Värden: 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

Värden: 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.

Fel

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.

Gränser

  • 600 anrop per minut per API-nyckel (Fast fönster; gränsen är densamma på alla planer)
  • En 429 innehåller Retry-After: 30 sekunder
  • Upp till 10 MB per bild
  • Format: JPEG, PNG, WebP
  • Samtidiga batcher per plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Endast polling — API:et skickar inga webhooks.

En förfrågan, en hel klädställning

Bygg arrayen, skicka en gång, polla batchen, ladda ner varje objekt.

  1. Steg 1

    Skapa en API-nyckel

    Batch-ghost-mannekäng använder samma autentiseringsuppgifter och samma credit-saldo som alla andra Photta-funktioner.

  2. Steg 2

    Bygg bild-arrayen

    `product_images` tar ett objekt per plagg: `image`, plus valfritt `back_image` och `image_side`. API-taket för batcher är 5 bilder på Free och Hobby, 10 på Seller, 25 på Brand och 50 på Studio.

  3. Steg 3

    POST:a batchen

    POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution` och `aspect_ratio` tillämpas på varje objekt, och `user_instruction` lägger till en instruktion på upp till 400 tecken för samtliga. Credits för hela batchen reserveras innan det första objektet renderas.

  4. Steg 4

    Polla batchen

    GET `/api/v1/ghost-mannequin/batch/:id` var 3:e sekund. Svarskroppen innehåller `total`, `completed`, `failed` och en uppdelning per objekt, så att du kan börja ladda ner innan det sista plagget är klart.

  5. Steg 5

    Ladda ner varje resultat

    Varje slutfört objekt har sin egen `output_url`, `credits_used` och körtid. Objekt som misslyckas återbetalar sina reserverade credits och rapporteras i `credits_refunded`.

Samma endpoint i Node.js, Python och cURL

Vanliga utvecklarfrågor inför batch-körningar

Vad tillför batch-endpointen?

Den tar emot en array av plaggfoton i en enda förfrågan och bearbetar dem i bakgrunden. Du får ett batch-id för den samlade vyn och ett objekt-id per foto, istället för att behöva hålla koll på dussintals separata jobb.

Hur många bilder ryms i en batch?

API-taket för en batch är 5 bilder på Free och Hobby, 10 på Seller, 25 på Brand och 50 på Studio — fem gånger högre än gränsen i instrumentpanelen. En batch som är större än vad din plan tillåter returnerar 400.

Hur debiteras credits för en batch?

Hela batchen reserveras i förväg: antal bilder multiplicerat med priset per bild, 4 credits i 2K eller 5 i 4K. Om saldot inte täcker reservationen returnerar förfrågan 402 och ingenting renderas.

Vad händer om ett objekt misslyckas?

Resten av batchen fortsätter. Batch-responsen rapporterar `failed` jämte `completed`, och reserverade credits för misslyckade objekt återbetalas i `credits_refunded`.

Hur många batcher kan köras samtidigt?

Antalet samtidiga aktiva batcher begränsas av din plan: Free 1, Hobby 2, Seller 3, Brand 4 och Studio 6. Skickar du in fler än gränsen tillåter returneras 409 — polla den aktiva batchen tills den är klar och skicka sedan igen.

Hur pollar jag en batch?

GET `/api/v1/ghost-mannequin/batch/:id` var 3:e sekund för samlad status, eller polla ett enskilt objekt via standardsökvägen för ghost mannequin-status när du vill ha detaljer per plagg.

Relaterade funktioner

Varje siffra på den här sidan kommer från Photter API-dokumentationen · kontrollerad

Testa API:et på fem minuter

Generera en Photta API-nyckel, klistra in cURL-kodfragmentet ovan, och du har din första bild på en modell innan kaffet har bryggts klart.

Skapa ett konto och hämta en API-nyckelLäs dokumentationen
  • 1.5–4 min per image
  • 4 credits vid 2K · 5 credits vid 4K
  • asynkron, polling
  • 600 requests/min
  • Bearer-nyckel