Funcionalidade · Ghost mannequin em lote

API de ghost mannequin em lote para catálogos inteiros

Em uma frase

O endpoint de ghost mannequin em lote da Photta recebe um array de fotos de roupas e retorna um ID de lote mais um ID de item por imagem. Os créditos para todo o lote são reservados antecipadamente; faça o polling do lote para obter o status agregado.

Obter uma chave de APILer a documentação
  • Tempo típico: 1.5–4 min per image
  • Credits: 4 credits em 2K · 5 credits em 4K
  • Processamento: assíncrono, polling
  • Limites: 600 requisições/min
  • Autenticação: Chave Bearer

Todos os números nesta página vêm de a documentação da API da 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
Exemplo de saída

Visão geral

Visão geral

Endpoint
POST /api/v1/ghost-mannequin/batch
Autenticação
API key Bearer
Processamento
Assíncrono — faça polling no endpoint de status
Tempo típico
1.5–4 min per image
Credits
4 credits em 2K · 5 credits em 4K
Proporções de tela
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Limites de entrada
Até 10 MB por imagem; JPEG, PNG, WebP
Idempotente
Não

Requisição e resposta

Requisição

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 / Concluído

{
  "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 da requisição

product_images

Tipo: array[object]Obrigatório

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.

Erros

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 requisições por minuto por API key (Janela fixa; o limite é o mesmo em todos os planos)
  • Um 429 retorna Retry-After: 30 segundos
  • Até 10 MB por imagem
  • Formatos: JPEG, PNG, WebP
  • Batches concorrentes por plano: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Apenas polling — a API não envia webhooks.

Uma requisição, uma arara de roupas

Monte o array, envie uma única vez, faça o polling do lote, baixe cada item.

  1. Passo 1

    Gere uma chave de API

    O ghost mannequin em lote usa as mesmas credenciais e o mesmo saldo de créditos que qualquer outra funcionalidade da Photta.

  2. Passo 2

    Monte o array de imagens

    `product_images` recebe um objeto por peça: `image`, além dos opcionais `back_image` e `image_side`. O limite de lote da API é de 5 imagens nos planos Free e Hobby, 10 no Seller, 25 no Brand e 50 no Studio.

  3. Passo 3

    Envie o lote via POST

    POST `/api/v1/ghost-mannequin/batch`. `angle`, `style`, `background_color`, `resolution` e `aspect_ratio` se aplicam a todos os itens, e `user_instruction` adiciona uma nota de até 400 caracteres para todos eles. Os créditos para todo o lote são reservados antes que o primeiro item seja renderizado.

  4. Passo 4

    Faça o polling do lote

    GET `/api/v1/ghost-mannequin/batch/:id` a cada 3 segundos. O corpo da resposta traz `total`, `completed`, `failed` e um detalhamento por item, para que você possa começar a baixar antes que a última peça termine.

  5. Passo 5

    Baixe cada resultado

    Cada item concluído inclui seu próprio `output_url`, `credits_used` e duração. Os itens que falharem têm seus créditos reservados estornados e são reportados em `credits_refunded`.

O mesmo endpoint em Node.js, Python e cURL

Perguntas que os desenvolvedores fazem antes de rodar lotes

O que o endpoint em lote acrescenta?

Ele aceita um array de fotos de roupas em uma única requisição e as processa em segundo plano. Você recebe um ID de lote para a visualização agregada e um ID de item por foto, em vez de monitorar dezenas de tarefas separadas.

Quantas imagens cabem em um único lote?

O limite de lote da API é de 5 imagens nos planos Free e Hobby, 10 no Seller, 25 no Brand e 50 no Studio — cinco vezes o limite do painel. Um lote maior do que o seu plano permite retorna 400.

Como os créditos são cobrados em um lote?

O lote inteiro é reservado antecipadamente: a quantidade de imagens multiplicada pelo preço unitário, 4 créditos em 2K ou 5 em 4K. Se o saldo não for suficiente para cobrir a reserva, a requisição retorna 402 e nada é renderizado.

O que acontece se um item falhar?

O restante do lote continua normalmente. O corpo da resposta do lote reporta `failed` junto de `completed`, e os créditos reservados para os itens que falharam retornam em `credits_refunded`.

Quantos lotes podem rodar simultaneamente?

O número de lotes em processamento simultâneo é limitado pelo plano: Free 1, Hobby 2, Seller 3, Brand 4 e Studio 6. Enviar requisições acima do limite retorna 409 — faça o polling do lote ativo até que ele termine e então envie novamente.

Como faço o polling de um lote?

GET `/api/v1/ghost-mannequin/batch/:id` a cada 3 segundos para obter o status agregado, ou faça o polling de qualquer item individual no caminho de status padrão de ghost mannequin quando quiser detalhes por peça.

Funcionalidades relacionadas

Todos os números nesta página vêm de a documentação da API da Photta · verificado

Experimente a API em cinco minutos

Gere uma chave de API do Photta, cole o snippet de cURL acima e você terá sua primeira imagem com modelo antes que o café termine de passar.

Criar uma conta e obter uma chave de APILer a documentação
  • 1.5–4 min per image
  • 4 credits em 2K · 5 credits em 4K
  • assíncrono, polling
  • 600 requisições/min
  • Chave Bearer