Возможность · Ghost mannequin

API невидимого манекена (ghost mannequin) для фото товаров на невидимом манекене

В двух словах

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

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

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

POST/api/v1/ghost-mannequin
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/ghost-mannequin \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "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
Аутентификация
API-ключ Bearer
Обработка
Асинхронно — опрашивайте эндпоинт статуса
Типичное время
1.5–4 min
Кредиты
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 \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/jacket-front.jpg",
  "back_image": "https://cdn.yourstore.com/products/jacket-back.jpg",
  "image_side": "front",
  "angle": "side",
  "style": "3d",
  "background_color": "white",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "closed front, cream interior lining",
  "brand_label_id": "7cc9f988-068b-44cd-8004-22f486b10e67"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Завершено

{
  "data": {
    "id": "gm_d4e5f6",
    "status": "processing",
    "style": "3d",
    "angle": "side",
    "background_color": "white",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 4,
    "created_at": "2026-04-10T16:00:00Z"
  },
  "request_id": "req_gm001"
}

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

product_image

Тип: stringОбязательное

URL or base64 data URI of the garment photo (front or back, on a mannequin or flat).

back_image

Тип: string

URL or base64 data URI of the opposite side — helps the AI reconstruct the interior of the garment for a more realistic 3D effect.

image_side

Тип: string

Which side product_image represents.

= front

Значения: frontback
angle

Тип: string

Camera angle for the output. "side" is worth calling out: the side view is reconstructed from the front photo (plus the back photo when provided), giving you a third catalog view without a third photoshoot — and it works well even on textured garments (crochet, lace, embroidery).

= straight

Значения: straightbackside
style

Тип: string

Output style: "3d" (ghost mannequin with 3D body shape) or "flat_lay" (garment laid flat, mannequin removed).

= 3d

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

Тип: string

Background color.

= white

Значения: whitegraybeigeblack
resolution

Тип: string

Output resolution. "2K" costs 4 credits per image; "4K" costs 5 credits per image. 4K is produced natively in a single generation — 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

Output aspect ratio. 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

Optional free-form note, 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

Brand label UUID returned by the Brand Labels API. Applied to the generated garment when present. 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 не отправляет вебхуки.

Одно фото на входе, одно фото с невидимым манекеном на выходе

Загрузите исходник, выберите стиль, отправьте запрос, выполните polling, скачайте результат.

  1. Шаг 1

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

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

  2. Шаг 2

    Загрузите исходное фото

    Передайте публичный URL или base64 data URI в `product_image`; добавьте `back_image`, если есть вид сзади. JPEG, PNG и WebP до 10 MB на изображение.

  3. Шаг 3

    Отправьте POST-запрос на задачу ghost mannequin

    Выполните POST к `/api/v1/ghost-mannequin` с `product_image`, `style` (`3d` или `flat_lay`) и опциональными `angle`, `background_color`, `resolution`. Polling — единственный сигнал завершения, API не отправляет вебхуки.

  4. Шаг 4

    Выполняйте polling до завершения задачи

    Выполняйте GET `/api/v1/ghost-mannequin/:id` каждые 3 секунды, пока `data.status` не станет `completed` или `failed`; обычно выполнение занимает от 1.5 до 4 минут.

  5. Шаг 5

    Скачайте и сохраните

    На выходе — PNG с удаленным манекеном и реконструированной внутренней частью вещи. Идеально для ghost-снимков на PDP, галерей товаров с 3D-объемом и вставок flat-lay.

Вопросы, которые разработчики задают перед внедрением ghost mannequin

Что такое съемка с эффектом ghost mannequin?

Формат для карточек товаров (PDP), где вещь словно надета на невидимое тело, одновременно демонстрируя форму и внутреннее устройство. Исторически его собирают из нескольких студийных кадров; API Photta генерирует его за один вызов из одного фото на манекене.

Сколько стоит ghost mannequin?

4 credits для 2K, 5 credits для 4K — на один credit дешевле на каждом тарифе по сравнению с try-on. При неудачном выполнении задачи credits возвращаются автоматически.

В чем разница между стилями 3D и flat-lay?

Стиль `3d` сохраняет трехмерную форму тела манекена — вещь держит объем, плечи и рукава смотрятся естественно, а внутренняя часть реконструируется. `flat_lay` переводит вещь в аккуратную плоскую 2D-раскладку, что идеально для капсульных коллекций или листингов на маркетплейсах, где требуется единая фронтальная форма.

Можно ли обрабатывать несколько фото пачкой?

Да. Отправьте POST к `/api/v1/ghost-mannequin/batch` с массивом исходных изображений. В ответе вы получите batch ID и ID генерации для каждого элемента. Выполняйте polling `/api/v1/ghost-mannequin/batch/:id` для получения общего статуса или проверяйте каждый элемент отдельно.

Сохраняются ли внутренние швы и ярлыки?

Да — модель реконструирует изнанку изделия (внутреннюю часть горловины, манжет, подкладку пояса), а не галлюцинирует абстрактную поверхность. Бирки и напечатанные лейблы, видимые на исходном фото, по возможности сохраняются.

Как опрашивать результат через polling?

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

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

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

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

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

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