Funksjonalitet · Batch ghost mannequin

Batch ghost mannequin-API for hele varekataloger

I én setning

Phottas batch ghost mannequin-endpoint tar en array med klesbilder og returnerer en batch-id pluss én element-id per bilde. Credits for hele batchen reserveres på forhånd; poll batchen for en aggregert status.

  • Typisk tidsbruk: 1.5–4 min per image
  • Credits: 4 credits ved 2K · 5 credits ved 4K
  • Prosessering: asynkron, polling
  • Grenser: 600 forespørsler/min
  • Autentisering: Bearer-nøkkel

Hvert tall på denne siden er hentet fra dokumentasjonen for Photta-API-et · verifisert

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
Eksempel på respons

Kort oppsummert

Kort oppsummert

Endepunkt
POST /api/v1/ghost-mannequin/batch
Autentisering
Bearer API-nøkkel
Prosessering
Asynkron – poll status-endepunktet
Typisk tidsbruk
1.5–4 min per image
Credits
4 credits ved 2K · 5 credits ved 4K
Bildeformater
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Inndatagrenser
Opptil 10 MB per bilde; JPEG, PNG, WebP
Idempotent
Nei

Forespørsel og respons

Forespørsel

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

Forespørselsparametere

product_images

Type: array[object]Påkrevd

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

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

Verdier: straightbackside
style

Type: string

Applied to all images.

= 3d

Verdier: 3dflat_lay
background_color

Type: string

Applied to all images.

= white

Verdier: whitegraybeigeblack
resolution

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

Verdier: 2K4K
aspect_ratio

Type: string

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

= 3:4

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

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

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

Feil

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.

Grenser

  • 600 forespørsler per minutt per API-nøkkel (Fast tidsvindu; grensen er lik for alle abonnementer)
  • En 429 inneholder Retry-After: 30 sekunder
  • Opptil 10 MB per bilde
  • Formater: JPEG, PNG, WebP
  • Samtidige batcher per abonnement: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Kun polling – API-et sender ikke webhooks.

Én forespørsel, et helt klesstativ

Sett sammen arrayen, send inn én gang, poll batchen, last ned hvert element.

  1. Trinn 1

    Generer en API-nøkkel

    Batch ghost mannequin bruker samme autentisering og samme credit-saldo som all annen Photta-funksjonalitet.

  2. Trinn 2

    Sett sammen bildearrayen

    `product_images` tar ett objekt per plagg: `image`, pluss valgfri `back_image` og `image_side`. API-ets batchgrense er 5 bilder på Free og Hobby, 10 på Seller, 25 på Brand og 50 på Studio.

  3. Trinn 3

    POST batchen

    POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution` og `aspect_ratio` gjelder for alle elementer, og `user_instruction` legger til ett notat på opptil 400 tegn for samtlige. Credits for hele batchen reserveres før det første elementet genereres.

  4. Trinn 4

    Poll batchen

    GET `/api/v1/ghost-mannequin/batch/:id` hvert 3. sekund. Responsen inneholder `total`, `completed`, `failed` og en oppdeling per element, slik at du kan begynne nedlastingen før det siste plagget er ferdig.

  5. Trinn 5

    Last ned hvert resultat

    Hvert fullførte element har sin egen `output_url`, `credits_used` og tidsbruk. Elementer som feiler refunderer sine reserverte credits og rapporteres i `credits_refunded`.

Spørsmål utviklere stiller før de kjører batcher

Hva tilfører batch-endpointet?

Det godtar en array med klesbilder i én enkelt forespørsel og behandler dem i bakgrunnen. Du får en batch-id for den aggregerte visningen og en element-id per bilde, i stedet for å spore dusinvis av separate jobber.

Hvor mange bilder får plass i én batch?

API-ets batchgrense er 5 bilder på Free og Hobby, 10 på Seller, 25 på Brand og 50 på Studio — fem ganger grensen i dashbordet. En batch som er større enn planen din tillater, returnerer 400.

Hvordan belastes credits for en batch?

Hele batchen reserveres på forhånd: antall bilder multiplisert med prisen per bilde, 4 credits i 2K eller 5 i 4K. Hvis saldoen ikke dekker reservasjonen, returnerer forespørselen 402 og ingenting genereres.

Hva skjer hvis ett element feiler?

Resten av batchen fortsetter. Batch-responsen rapporterer `failed` sammen med `completed`, og de reserverte creditsene for feilede elementer tilbakeføres i `credits_refunded`.

Hvor mange batcher kan kjøre samtidig?

Samtidige aktive batcher er begrenset av planen: Free 1, Hobby 2, Seller 3, Brand 4 og Studio 6. Overskrides grensen returneres 409 — poll den aktive batchen til den er ferdig, og send inn på nytt.

Hvordan poller jeg en batch?

GET `/api/v1/ghost-mannequin/batch/:id` hvert 3. sekund for aggregert status, eller poll et enkelt element på standardstatusstien for ghost mannequin når du trenger detaljer per plagg.

Relatert funksjonalitet

Hvert tall på denne siden er hentet fra dokumentasjonen for Photta-API-et · verifisert

Prøv API-et på fem minutter

Generer en Photta API-nøkkel, lim inn cURL-kodesnutten ovenfor, og du har ditt første bilde på modell før kaffen er ferdig traktet.

  • 1.5–4 min per image
  • 4 credits ved 2K · 5 credits ved 4K
  • asynkron, polling
  • 600 forespørsler/min
  • Bearer-nøkkel