Funktion · Batch ghost mannequin

Batch ghost mannequin-API til hele kataloger

I én sætning

Phottas batch ghost mannequin-endpoint modtager et array af tøjfotos og returnerer et batch-id plus ét element-id pr. billede. Credits for hele batchet reserveres forud; poll batchet for en samlet status.

Hent en API-nøgleLæs dokumentationen
  • Typisk tid: 1.5–4 min per image
  • Credits: 4 credits ved 2K · 5 credits ved 4K
  • Behandling: async, polling
  • Grænser: 600 requests/min
  • Autentifikation: Bearer key

Hvert tal på denne side stammer fra Photta API-dokumentationen · tjekket

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å output

Kort fortalt

Kort fortalt

Endpoint
POST /api/v1/ghost-mannequin/batch
Autentifikation
Bearer API-nøgle
Behandling
Asynkron — poll status-endpointet
Typisk tid
1.5–4 min per image
Credits
4 credits ved 2K · 5 credits ved 4K
Billedformater
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Inputgrænser
Op til 10 MB pr. billede; JPEG, PNG, WebP
Idempotent
Nej

Request og 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-parametre

product_images

Type: array[object]Påkrævet

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

Værdier: straightbackside
style

Type: string

Applied to all images.

= 3d

Værdier: 3dflat_lay
background_color

Type: string

Applied to all images.

= white

Værdier: 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

Værdier: 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

Værdier: 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.

Fejl

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 anmodninger i minuttet pr. API-nøgle (Fast vindue; grænsen er den samme på alle planer)
  • En 429 indeholder Retry-After: 30 sekunder
  • Op til 10 MB pr. billede
  • Formater: JPEG, PNG, WebP
  • Samtidige batches pr. plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Kun polling — API'et sender ingen webhooks.

Én anmodning, et helt stativ af tøj

Sammensæt arrayet, indsend én gang, poll batchet, download hvert element.

  1. Trin 1

    Generér en API-nøgle

    Batch ghost mannequin bruger de samme legitimationsoplysninger og den samme credit-saldo som enhver anden Photta-funktion.

  2. Trin 2

    Sammensæt billed-arrayet

    `product_images` modtager ét objekt pr. stykke tøj: `image` samt valgfri `back_image` og `image_side`. API-batchgrænsen er 5 billeder på Free og Hobby, 10 på Seller, 25 på Brand og 50 på Studio.

  3. Trin 3

    POST batchet

    POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution` og `aspect_ratio` gælder for hvert element, og `user_instruction` tilføjer én note på op til 400 tegn til dem alle. Credits for hele batchet reserveres, før det første element renderes.

  4. Trin 4

    Poll batchet

    GET `/api/v1/ghost-mannequin/batch/:id` hvert 3. sekund. Svarets body indeholder `total`, `completed`, `failed` og en opdeling pr. element, så du kan begynde at downloade, før det sidste stykke tøj er færdigt.

  5. Trin 5

    Download hvert resultat

    Hvert fuldført element har sin egen `output_url`, `credits_used` og varighed. Elementer, der fejler, refunderer deres reserverede credits og rapporteres i `credits_refunded`.

Det samme endpoint i Node.js, Python og cURL

Spørgsmål, udviklere stiller, før de kører batches

Hvad tilfører batch-endpointet?

Det accepterer et array af tøjfotos i én anmodning og behandler dem i baggrunden. Du får et batch-id til den samlede visning og et element-id pr. foto i stedet for at skulle spore dusinvis af separate jobs.

Hvor mange billeder kan der være i ét batch?

API-batchgrænsen er 5 billeder på Free og Hobby, 10 på Seller, 25 på Brand og 50 på Studio — fem gange dashboard-grænsen. Et batch, der er større end din plan tillader, returnerer 400.

Hvordan opkræves credits for et batch?

Hele batchet reserveres forud: billeder ganget med stykprisen, 4 credits ved 2K eller 5 ved 4K. Hvis saldoen ikke dækker reservationen, returnerer anmodningen 402, og intet renderes.

Hvad sker der, hvis ét element fejler?

Resten af batchet fortsætter. Batchets body rapporterer `failed` side om side med `completed`, og de reserverede credits for fejlslagne elementer føres tilbage i `credits_refunded`.

Hvor mange batches kan køre på samme tid?

Samtidige igangværende batches er begrænset af planen: Free 1, Hobby 2, Seller 3, Brand 4 og Studio 6. Indsendelse ud over grænsen returnerer 409 — poll det aktive batch, indtil det er afsluttet, og indsend derefter igen.

Hvordan poller jeg et batch?

GET `/api/v1/ghost-mannequin/batch/:id` hvert 3. sekund for den samlede status, eller poll ethvert enkelt element på den almindelige statussti til ghost mannequin, når du vil have detaljer pr. stykke tøj.

Relaterede funktioner

Hvert tal på denne side stammer fra Photta API-dokumentationen · tjekket

Prøv API'et på fem minutter

Generér en Photta API-nøgle, indsæt cURL-kodestykket ovenfor, og du har dit første billede på en model, før kaffen er færdigbrygget.

Opret en konto og hent en API-nøgleLæs dokumentationen
  • 1.5–4 min per image
  • 4 credits ved 2K · 5 credits ved 4K
  • async, polling
  • 600 requests/min
  • Bearer key