Funzionalità · Ghost mannequin in batch

API batch per ghost mannequin per interi cataloghi

In sintesi

L'endpoint ghost mannequin in batch di Photta accetta un array di foto di capi e restituisce un batch id oltre a un item id per ciascuna immagine. I credits per l'intero batch vengono riservati in anticipo; esegui il polling del batch per monitorare lo stato aggregato.

Ottieni una chiave APILeggi la documentazione
  • Tempo tipico: 1.5–4 min per image
  • Credits: 4 credits a 2K · 5 credits a 4K
  • Elaborazione: asincrono, polling
  • Limiti: 600 richieste/min
  • Autenticazione: Chiave Bearer

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato

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
Esempio di output

Panoramica

Panoramica

Endpoint
POST /api/v1/ghost-mannequin/batch
Autenticazione
API key Bearer
Elaborazione
Asincrona — effettua il polling dell'endpoint di stato
Tempo tipico
1.5–4 min per image
Credits
4 credits a 2K · 5 credits a 4K
Rapporti d'aspetto
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limiti di input
Fino a 10 MB per immagine; JPEG, PNG, WebP
Idempotente
No

Richiesta e risposta

Richiesta

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 / Completato

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

Parametri della richiesta

product_images

Tipo: array[object]Obbligatorio

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

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

Valori: straightbackside
style

Tipo: string

Applied to all images.

= 3d

Valori: 3dflat_lay
background_color

Tipo: string

Applied to all images.

= white

Valori: whitegraybeigeblack
resolution

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

Valori: 2K4K
aspect_ratio

Tipo: string

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

= 3:4

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

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

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

Errori

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.

Limiti

  • 600 richieste al minuto per API key (Finestra fissa; il limite è lo stesso per ogni piano)
  • Un 429 restituisce Retry-After: 30 secondi
  • Fino a 10 MB per immagine
  • Formati: JPEG, PNG, WebP
  • Batch simultanei per piano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Solo polling — l'API non invia webhook.

Una sola richiesta, un intero set di capi

Componi l'array, invia una volta sola, esegui il polling del batch e scarica ogni elemento.

  1. Passaggio 1

    Genera una chiave API

    Il ghost mannequin in batch utilizza le stesse credenziali e lo stesso saldo crediti di qualsiasi altra funzionalità Photta.

  2. Passaggio 2

    Componi l'array di immagini

    `product_images` accetta un oggetto per capo: `image`, più `back_image` e `image_side` opzionali. Il limite di batch dell'API è di 5 immagini per Free e Hobby, 10 per Seller, 25 per Brand e 50 per Studio.

  3. Passaggio 3

    Invia il batch con POST

    POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution` e `aspect_ratio` vengono applicati a ogni elemento, mentre `user_instruction` aggiunge una nota fino a 400 caratteri valida per tutti. I credits per l'intero batch vengono riservati prima che inizi il rendering del primo elemento.

  4. Passaggio 4

    Esegui il polling del batch

    GET `/api/v1/ghost-mannequin/batch/:id` ogni 3 secondi. Il body include `total`, `completed`, `failed` e il dettaglio per singolo elemento, consentendo di avviare il download prima del completamento dell'ultimo capo.

  5. Passaggio 5

    Scarica ciascun risultato

    Ogni elemento completato include il proprio `output_url`, `credits_used` e la durata. Gli elementi che falliscono rimborsano i credits riservati, segnalati in `credits_refunded`.

Lo stesso endpoint in Node.js, Python e cURL

Domande frequenti degli sviluppatori prima di eseguire batch

Cosa aggiunge l'endpoint batch?

Accetta un array di foto di capi in un'unica richiesta e le elabora in background. Restituisce un batch id per la vista aggregata e un item id per ciascuna foto, evitando di dover tracciare decine di job separati.

Quante immagini è possibile includere in un batch?

Il limite di batch dell'API è di 5 immagini per Free e Hobby, 10 per Seller, 25 per Brand e 50 per Studio — cinque volte il limite della dashboard. Se il batch supera la soglia consentita dal piano, l'API restituisce 400.

Come vengono addebitati i credits per un batch?

L'intero batch viene riservato in anticipo: numero di immagini moltiplicato per il costo unitario, 4 credits a 2K o 5 a 4K. Se il saldo non è sufficiente a coprire la prenotazione, la richiesta restituisce 402 e nessun rendering viene avviato.

Cosa succede se un singolo elemento fallisce?

L'elaborazione del resto del batch prosegue regolarmente. Il body del batch segnala `failed` insieme a `completed`, e i credits riservati per gli elementi falliti vengono riaccreditati in `credits_refunded`.

Quanti batch possono essere eseguiti contemporaneamente?

I batch simultanei in corso sono limitati in base al piano: 1 per Free, 2 per Hobby, 3 per Seller, 4 per Brand e 6 per Studio. L'invio oltre la soglia massima restituisce 409 — monitora il batch attivo fino al completamento prima di inviarne un altro.

Come si esegue il polling di un batch?

GET `/api/v1/ghost-mannequin/batch/:id` ogni 3 secondi per lo stato aggregato, oppure esegui il polling di un singolo elemento sul percorso di stato standard di ghost mannequin per ottenere i dettagli del singolo capo.

Funzionalità correlate

Ogni dato in questa pagina proviene da la documentazione dell'API di Photta · verificato

Prova l'API in 5 minuti

Genera una chiave API di Photta, incolla lo snippet cURL qui sopra e otterrai la tua prima immagine con modello prima ancora che il caffè sia pronto.

Crea un account e ottieni una chiave APILeggi la documentazione
  • 1.5–4 min per image
  • 4 credits a 2K · 5 credits a 4K
  • asincrono, polling
  • 600 richieste/min
  • Chiave Bearer