Funcionalidad · Ghost mannequin por lotes

API de ghost mannequin por lotes para catálogos completos

En una frase

El endpoint de ghost mannequin por lotes de Photta recibe un array de fotos de prendas y devuelve un batch id junto con un item id por imagen. Los créditos de todo el lote se reservan por adelantado; haz polling del lote para obtener un estado agregado.

Obtener una API keyLeer la documentación
  • Tiempo típico: 1.5–4 min per image
  • Credits: 4 credits a 2K · 5 credits a 4K
  • Procesamiento: asíncrono, polling
  • Límites: 600 requests/min
  • Autenticación: Bearer key

Cada cifra de esta página proviene de la documentación de la API de Photta · verificado

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
Salida de ejemplo

De un vistazo

De un vistazo

Endpoint
POST /api/v1/ghost-mannequin/batch
Autenticación
Bearer API key
Procesamiento
Asíncrono — realiza polling al endpoint de estado
Tiempo típico
1.5–4 min per image
Credits
4 credits a 2K · 5 credits a 4K
Relaciones de aspecto
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Límites de entrada
Hasta 10 MB por imagen; JPEG, PNG, WebP
Idempotente
No

Petición y respuesta

Petición

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

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

Parámetros de la petición

product_images

Tipo: array[object]Obligatorio

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

Valores: straightbackside
style

Tipo: string

Applied to all images.

= 3d

Valores: 3dflat_lay
background_color

Tipo: string

Applied to all images.

= white

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

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

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

Errores

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.

Límites

  • 600 solicitudes por minuto por API key (Ventana fija; el límite es el mismo en todos los planes)
  • Un 429 incluye Retry-After: 30 segundos
  • Hasta 10 MB por imagen
  • Formatos: JPEG, PNG, WebP
  • Lotes simultáneos por plan: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Solo polling — la API no envía webhooks.

Una petición, un perchero de prendas

Construye el array, envíalo una vez, haz polling del lote y descarga cada elemento.

  1. Paso 1

    Genera una API key

    Ghost mannequin por lotes utiliza las mismas credenciales y el mismo saldo de créditos que cualquier otra funcionalidad de Photta.

  2. Paso 2

    Construye el array de imágenes

    `product_images` admite un objeto por prenda: `image`, además de `back_image` e `image_side` opcionales. El límite del lote de la API es de 5 imágenes en Free y Hobby, 10 en Seller, 25 en Brand y 50 en Studio.

  3. Paso 3

    Envía el lote por POST

    POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution` y `aspect_ratio` se aplican a todos los elementos, y `user_instruction` añade una nota de hasta 400 caracteres para todos ellos. Los créditos del lote completo se reservan antes de que se procese el primer elemento.

  4. Paso 4

    Haz polling del lote

    GET `/api/v1/ghost-mannequin/batch/:id` cada 3 segundos. El cuerpo incluye `total`, `completed`, `failed` y un desglose por elemento, para que puedas empezar a descargar antes de que termine la última prenda.

  5. Paso 5

    Descarga cada resultado

    Cada elemento completado incluye su propio `output_url`, `credits_used` y duración. Los elementos que fallen reembolsan sus créditos reservados y se registran en `credits_refunded`.

El mismo endpoint en Node.js, Python y cURL

Preguntas que se hacen los desarrolladores antes de ejecutar lotes

¿Qué aporta el endpoint por lotes?

Acepta un array de fotos de prendas en una sola petición y las procesa en segundo plano. Obtienes un batch id para la vista agregada y un item id por foto, en lugar de tener que rastrear decenas de trabajos independientes.

¿Cuántas imágenes caben en un lote?

El límite de lote de la API es de 5 imágenes en Free y Hobby, 10 en Seller, 25 en Brand y 50 en Studio —cinco veces el límite del panel de control—. Un lote que supere lo permitido por tu plan devuelve 400.

¿Cómo se cobran los créditos de un lote?

Todo el lote se reserva por adelantado: imágenes multiplicadas por el precio unitario por imagen, 4 créditos a 2K o 5 a 4K. Si el saldo no cubre la reserva, la petición devuelve 402 y no se procesa nada.

¿Qué ocurre si falla un elemento?

El resto del lote sigue su curso. El cuerpo del lote reporta `failed` junto con `completed`, y los créditos reservados de los elementos fallidos se reintegran en `credits_refunded`.

¿Cuántos lotes pueden ejecutarse simultáneamente?

Los lotes concurrentes en curso están limitados según el plan: Free 1, Hobby 2, Seller 3, Brand 4 y Studio 6. Si envías peticiones por encima del límite recibirás un 409 —haz polling del lote activo hasta que finalice y luego vuelve a enviar—.

¿Cómo hago polling de un lote?

GET `/api/v1/ghost-mannequin/batch/:id` cada 3 segundos para obtener el estado agregado, o haz polling de cualquier elemento individual en la ruta de estado estándar de ghost mannequin si necesitas el detalle por prenda.

Funcionalidades relacionadas

Cada cifra de esta página proviene de la documentación de la API de Photta · verificado

Prueba la API en cinco minutos

Genera una API key de Photta, pega el snippet de cURL de arriba y tendrás tu primera imagen con modelo antes de que termine de prepararse el café.

Crear una cuenta y obtener una API keyLeer la documentación
  • 1.5–4 min per image
  • 4 credits a 2K · 5 credits a 4K
  • asíncrono, polling
  • 600 requests/min
  • Bearer key