Возможность · Пакетный ghost mannequin

Пакетный ghost mannequin API для каталогов целиком

В двух словах

Пакетный endpoint ghost mannequin от Photta принимает массив фотографий одежды и возвращает id пакета вместе с отдельным id для каждого изображения. Credits на весь пакет резервируются заранее; опрашивайте пакет для получения общего статуса.

  • Типичное время: 1.5–4 min per image
  • Кредиты: 4 credits при 2K · 5 credits при 4K
  • Обработка: async, polling
  • Лимиты: 600 запросов/мин
  • Аутентификация: Ключ Bearer

Все показатели на этой странице взяты из документации API Photta · проверено

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
Пример результата

Коротко о главном

Коротко о главном

Эндпоинт
POST /api/v1/ghost-mannequin/batch
Аутентификация
API-ключ Bearer
Обработка
Асинхронно — опрашивайте эндпоинт статуса
Типичное время
1.5–4 min per image
Кредиты
4 credits при 2K · 5 credits при 4K
Соотношения сторон
3:4 · 1:1 · 4:3 · 9:16 · 16:9
Ограничения на входные данные
До 10 МБ на изображение; JPEG, PNG, WebP
Идемпотентность
Нет

Запрос и ответ

Запрос

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 / Завершено

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

Параметры запроса

product_images

Тип: array[object]Обязательное

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

Тип: 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

Значения: straightbackside
style

Тип: string

Applied to all images.

= 3d

Значения: 3dflat_lay
background_color

Тип: string

Applied to all images.

= white

Значения: whitegraybeigeblack
resolution

Тип: 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

Значения: 2K4K
aspect_ratio

Тип: string

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

= 3:4

Значения: 3:41:14:39:1616:9
user_instruction

Тип: 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

Тип: 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.

Ошибки

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.

Лимиты

  • 600 запросов в минуту на один API-ключ (Фиксированное окно; лимит одинаков для всех планов)
  • Ответ 429 содержит заголовок Retry-After: 30 секунд
  • До 10 МБ на изображение
  • Форматы: JPEG, PNG, WebP
  • Параллельных пакетов на план: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Только polling — API не отправляет вебхуки.

Один запрос, целая стойка одежды

Соберите массив, отправьте один раз, опрашивайте статус пакета, скачайте каждый элемент.

  1. Шаг 1

    Сгенерируйте API-ключ

    Пакетный ghost mannequin использует те же учетные данные и тот же баланс credits, что и любая другая возможность Photta.

  2. Шаг 2

    Соберите массив изображений

    `product_images` принимает по одному объекту на каждый предмет одежды: `image`, а также опциональные `back_image` и `image_side`. Лимит размера пакета в API: 5 изображений на тарифах Free и Hobby, 10 на Seller, 25 на Brand и 50 на Studio.

  3. Шаг 3

    Отправьте пакет методом POST

    POST `/api/v1/ghost-mannequin/batch`. Параметры `angle`, `style`, `background_color`, `resolution` и `aspect_ratio` применяются ко всем элементам, а `user_instruction` добавляет ко всем единую инструкцию длиной до 400 символов. Credits на весь пакет резервируются до старта рендеринга первого элемента.

  4. Шаг 4

    Опрашивайте статус пакета

    Выполняйте GET `/api/v1/ghost-mannequin/batch/:id` каждые 3 секунды. Тело ответа содержит `total`, `completed`, `failed` и разбивку по элементам, так что скачивание можно начинать еще до завершения обработки всей партии.

  5. Шаг 5

    Скачайте каждый результат

    Каждый завершенный элемент содержит собственный `output_url`, `credits_used` и время обработки. Элементы, завершившиеся ошибкой, возвращают зарезервированные credits — они отображаются в `credits_refunded`.

Вопросы разработчиков перед запуском пакетов

Что дает пакетный endpoint?

Он принимает массив фотографий одежды в одном запросе и обрабатывает их в фоновом режиме. Вместо отслеживания десятков отдельных задач вы получаете id пакета для сводного статуса и отдельный id для каждого фото.

Сколько изображений помещается в один пакет?

Лимит размера пакета в API составляет 5 изображений на тарифах Free и Hobby, 10 на Seller, 25 на Brand и 50 на Studio — в пять раз больше, чем через панель управления. Отправка пакета сверх лимита тарифа возвращает 400.

Как списываются credits за пакет?

Сумма за весь пакет резервируется заранее: количество изображений умножается на цену за изображение — 4 credits в 2K или 5 в 4K. Если на балансе недостаточно средств для резервирования, запрос возвращает 402 и обработка не запускается.

Что происходит при сбое обработки отдельного элемента?

Обработка остальной части пакета продолжается. В теле ответа пакета поле `failed` отображается наряду с `completed`, а зарезервированные credits за неуспешные элементы возвращаются в `credits_refunded`.

Сколько пакетов можно запускать одновременно?

Количество одновременно выполняемых пакетов ограничено тарифом: Free — 1, Hobby — 2, Seller — 3, Brand — 4 и Studio — 6. Превышение лимита возвращает 409 — опрашивайте активный пакет до его завершения, затем повторите отправку.

Как опрашивать статус пакета?

Выполняйте GET `/api/v1/ghost-mannequin/batch/:id` каждые 3 секунды для получения общего статуса либо опрашивайте любой конкретный элемент по стандартному пути статуса ghost mannequin, если нужны подробности по отдельному изделию.

Связанные возможности

Все показатели на этой странице взяты из документации API Photta · проверено

Протестируйте API за пять минут

Сгенерируйте API-ключ Photta, вставьте пример cURL выше, и вы получите первое изображение на модели быстрее, чем сварится кофе.

  • 1.5–4 min per image
  • 4 credits при 2K · 5 credits при 4K
  • async, polling
  • 600 запросов/мин
  • Ключ Bearer