Fonctionnalité · Ghost mannequin par lot

API ghost mannequin par lot pour des catalogues entiers

En une phrase

L’endpoint ghost mannequin par lot de Photta prend en entrée un tableau de photos de vêtements et renvoie un batch id ainsi qu'un item id par image. Les crédits pour l’ensemble du lot sont réservés à l'avance ; effectuez un polling sur le lot pour obtenir un statut agrégé.

  • Délai typique: 1.5–4 min per image
  • Crédits: 4 crédits en 2K · 5 crédits en 4K
  • Traitement: asynchrone, polling
  • Limites: 600 requêtes/min
  • Authentification: Clé Bearer

Chaque chiffre sur cette page provient de la documentation de l'API Photta · vérifié

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
Exemple de sortie

En un coup d'œil

En un coup d'œil

Endpoint
POST /api/v1/ghost-mannequin/batch
Authentification
Clé API Bearer
Traitement
Asynchrone — interrogez l'endpoint de statut par polling
Délai typique
1.5–4 min per image
Crédits
4 crédits en 2K · 5 crédits en 4K
Rapports d'aspect
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limites d'entrée
Jusqu'à 10 Mo par image ; JPEG, PNG, WebP
Idempotent
Non

Requête et réponse

Requête

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 / Terminé

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

Paramètres de requête

product_images

Type: array[object]Requis

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

Valeurs: straightbackside
style

Type: string

Applied to all images.

= 3d

Valeurs: 3dflat_lay
background_color

Type: string

Applied to all images.

= white

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

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

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

Erreurs

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.

Limites

  • 600 requêtes par minute par clé API (Fenêtre fixe ; la limite est identique sur tous les forfaits)
  • Une 429 renvoie Retry-After: 30 secondes
  • Jusqu'à 10 Mo par image
  • Formats: JPEG, PNG, WebP
  • Lots simultanés par forfait: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Polling uniquement — l'API n'envoie aucun webhook.

Une seule requête, tout un portant de vêtements

Assemblez le tableau, soumettez une fois, effectuez le polling du lot, téléchargez chaque élément.

  1. Étape 1

    Générer une clé API

    Le ghost mannequin par lot utilise les mêmes identifiants et le même solde de crédits que toutes les autres fonctionnalités de Photta.

  2. Étape 2

    Assembler le tableau d'images

    `product_images` prend un objet par vêtement : `image`, ainsi qu'un `back_image` et un `image_side` optionnels. La limite de lot de l'API est de 5 images pour Free et Hobby, 10 pour Seller, 25 pour Brand et 50 pour Studio.

  3. Étape 3

    Envoyer le lot via POST

    POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution` et `aspect_ratio` s'appliquent à chaque élément, et `user_instruction` ajoute une note pouvant atteindre 400 caractères à l'ensemble d'entre eux. Les crédits pour tout le lot sont réservés avant le rendu du premier élément.

  4. Étape 4

    Effectuer le polling du lot

    GET `/api/v1/ghost-mannequin/batch/:id` toutes les 3 secondes. Le corps contient `total`, `completed`, `failed` ainsi qu'un détail par élément, vous permettant de commencer le téléchargement avant le traitement du dernier vêtement.

  5. Étape 5

    Télécharger chaque résultat

    Chaque élément terminé inclut son propre `output_url`, `credits_used` et sa durée. Les éléments en échec voient leurs crédits réservés remboursés et signalés dans `credits_refunded`.

Questions posées par les développeurs avant de lancer des lots

Qu'apporte l'endpoint de lot ?

Il accepte un tableau de photos de vêtements en une seule requête et les traite en arrière-plan. Vous obtenez un batch id pour la vue agrégée et un item id par photo, au lieu d'avoir à suivre des dizaines de tâches distinctes.

Combien d'images peuvent tenir dans un lot ?

La limite de lot de l'API est de 5 images pour Free et Hobby, 10 pour Seller, 25 pour Brand et 50 pour Studio — soit cinq fois la limite du tableau de bord. Un lot dépassant la limite autorisée par votre plan renvoie 400.

Comment les crédits sont-ils facturés pour un lot ?

L'ensemble du lot est réservé à l'avance : le nombre d'images multiplié par le prix par image, soit 4 crédits en 2K ou 5 en 4K. Si le solde ne couvre pas la réservation, la requête renvoie 402 et aucun rendu n'est lancé.

Que se passe-t-il lorsqu'un élément échoue ?

Le reste du lot continue son exécution. Le corps de réponse du lot indique `failed` aux côtés de `completed`, et les crédits réservés pour les éléments en échec sont restitués dans `credits_refunded`.

Combien de lots peuvent s'exécuter simultanément ?

Le nombre de lots simultanés en cours de traitement est limité selon le plan : 1 pour Free, 2 pour Hobby, 3 pour Seller, 4 pour Brand et 6 pour Studio. Toute soumission au-delà du plafond renvoie 409 — interrogez le lot actif jusqu'à sa résolution, puis soumettez à nouveau.

Comment effectuer le polling d'un lot ?

GET `/api/v1/ghost-mannequin/batch/:id` toutes les 3 secondes pour obtenir le statut agrégé, ou effectuez un polling sur un élément individuel via le chemin de statut standard du ghost mannequin si vous souhaitez le détail par vêtement.

Fonctionnalités associées

Chaque chiffre sur cette page provient de la documentation de l'API Photta · vérifié

Testez l'API en cinq minutes

Générez une clé d'API Photta, collez le snippet cURL ci-dessus, et vous obtiendrez votre première photo portée sur modèle avant même que le café ait fini de couler.

  • 1.5–4 min per image
  • 4 crédits en 2K · 5 crédits en 4K
  • asynchrone, polling
  • 600 requêtes/min
  • Clé Bearer