Возможность · Eyewear studio

API виртуальной примерки очков для очков и солнцезащитных очков

В двух словах

API eyewear studio от Photta превращает одну фотографию очков или солнцезащитных очков в готовый снимок. Выберите предметный режим или модель, отправьте POST, опрашивайте каждые 3 секунды, скачайте при статусе completed. 5 credits при 2K.

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

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

POST/api/v1/eyewear-studio
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/eyewear-studio \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
  "mode": "product-only",
  "sub_tool": "studio-shot",
  "backdrop": "gradient",
  "lighting": "soft",
  "aspect_ratio": "3:4",
  "resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')
Sunglasses photographed by the eyewear studio API
Пример результата

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

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

Эндпоинт
POST /api/v1/eyewear-studio
Аутентификация
API-ключ Bearer
Обработка
Асинхронно — опрашивайте эндпоинт статуса
Типичное время
20–60 sec
Кредиты
5 credits при 2K · 6 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/eyewear-studio \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
  "mode": "product-only",
  "sub_tool": "studio-shot",
  "backdrop": "gradient",
  "lighting": "soft",
  "aspect_ratio": "3:4",
  "resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

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

{
  "data": {
    "id": "eyw_7a1c9e42f05b3d688c2e4f01a9d6b357",
    "status": "processing",
    "mode": "product-only",
    "sub_tool": "studio-shot",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-08-01T09:15:00Z"
  },
  "request_id": "req_eyw001"
}

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

eyewear_image

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

The eyewear product image — glasses or sunglasses. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

mode

Тип: string

Generation mode: "product-only" — the eyewear alone, styled by sub_tool; "on-model" — the eyewear worn on an AI model's face (requires mannequin_id).

= product-only

Значения: product-onlyon-model
sub_tool

Тип: string

Product-only styling: "studio-shot" — clean studio product shot; "flat-lay" — top-down arrangement on a surface; "lifestyle" — the eyewear placed in a real-world scene; "floating" — the frames suspended mid-air. Sending sub_tool with mode "on-model" returns 400.

= studio-shot

Значения: studio-shotflat-laylifestylefloating
mannequin_id

Тип: string

Required when mode is "on-model": the AI model whose face wears the eyewear — an id ("mnk_...") from GET /api/v1/eyewear-studio/mannequins. Sending it in product-only mode returns 400.

face_angle

Тип: string

On-model only: the angle of the model's face.

= front

Значения: frontthree-quarterside-profile
expression

Тип: string

On-model only: the model's facial expression.

= neutral

Значения: neutralsoft-smileseriousconfident
lighting_style

Тип: string

On-model only: how the portrait is lit.

= soft-diffused

Значения: soft-diffusedstudionaturaldramatic
frame_fit_style

Тип: string

On-model only: the overall styling of how the frames are worn.

= casual

Значения: casualprofessionalfashion-editorialsporty
backdrop

Тип: string

Studio-shot only: the backdrop behind the eyewear.

= white

Значения: whitegrayblackgradient
lighting

Тип: string

Studio-shot only: the lighting setup.

= soft

Значения: softharddramaticnatural
surface

Тип: string

Flat-lay only: the surface the eyewear lies on.

= marble

Значения: marblewoodfabricconcretemetal
arrangement_style

Тип: string

Flat-lay only: how the composition is arranged.

= minimal

Значения: minimalsymmetricscatteredlayered
props

Тип: string

Flat-lay only: complementary props placed around the eyewear.

= none

Значения: noneplantsaccessoriestech
scene

Тип: string

Lifestyle only: the real-world setting.

= coffee-shop

Значения: coffee-shopbeachurban-streetofficepark
mood

Тип: string

Lifestyle only: the color mood of the scene.

= warm

Значения: warmcoolvibrantmoody
angle

Тип: string

Floating only: the camera angle on the suspended frames.

= front

Значения: frontthree-quartersidetop-down
shadow_style

Тип: string

Floating only: the shadow cast beneath the frames.

= soft-drop

Значения: soft-dropnonehard-dropreflection
background_color

Тип: string

Solid background color. Applies in both modes. Overridden by background_prompt when both are sent.

= white

Значения: whitegrayblackbeige
background_prompt

Тип: string

Free-text background description. Max 400 characters — excess is silently truncated. Overrides background_color.

aspect_ratio

Тип: string

Output aspect ratio.

= 3:4

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

Тип: string

Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.

= 2K

Значения: 2K4K

Ошибки

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-ключ

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

  2. Шаг 2

    Выберите режим и его стилизацию

    `mode` принимает значение `product-only` или `on-model`. Для product-only требуется `sub_tool` — `studio-shot`, `flat-lay`, `lifestyle` или `floating`, каждый из которых открывает свои параметры. Для on-model требуются `mannequin_id`, а также `face_angle`, `expression`, `lighting_style` и `frame_fit_style`.

  3. Шаг 3

    Отправьте задачу на генерацию через POST

    Отправьте POST-запрос на `/api/v1/eyewear-studio` с `eyewear_image` и полями стилизации. Поле `background_prompt` принимает до 400 символов и переопределяет `background_color`. Единственный сигнал о готовности — polling, API не отправляет вебхуки.

  4. Шаг 4

    Опрашивайте статус до завершения задачи

    Выполняйте GET `/api/v1/eyewear-studio/:id` каждые 3 секунды, пока `data.status` не примет значение `completed` или `failed`; обычное время выполнения — от 20 до 60 секунд.

  5. Шаг 5

    Скачайте и сохраните результат

    В теле ответа завершенной задачи возвращаются `output_url` и превью. Сохраняйте файл на своей стороне: URL служит для доставки результата одной задачи, а не для постоянного хостинга.

Вопросы, которые разработчики задают перед интеграцией генерации очков

Что делает API eyewear studio?

Он принимает одно фото очков или солнцезащитных очков и возвращает их стилизованную фотографию: либо саму оправу в студийном стиле, flat-lay, лайфстайл или левитации, либо на лице выбранной вами AI-модели.

Сколько стоит генерация одного снимка очков?

5 credits при 2K и 6 credits при 4K — так же, как примерка одежды и украшений. За сбойные задачи списания возвращаются автоматически.

В чем разница между product-only и on-model?

В режиме `product-only` оправы снимаются отдельно, управление идет через `sub_tool`. В режиме `on-model` они размещаются на лице AI-модели с параметрами `mannequin_id`, `face_angle`, `expression`, `lighting_style` и `frame_fit_style`. Поля другого режима игнорируются.

Какие параметры стилизации доступны для каждого sub-tool?

`studio-shot` принимает `backdrop` и `lighting`. `flat-lay` принимает `surface`, `arrangement_style` и `props`. `lifestyle` принимает `scene` и `mood`. `floating` принимает `angle` и `shadow_style`. Каждое из этих полей является enum, поэтому некорректное значение отклоняется, а не подбирается автоматически.

Можно ли использовать собственную AI-модель?

Да. Параметр `mannequin_id` принимает любой id манекена из GET `/api/v1/eyewear-studio/mannequins`; манекены, созданные через API генерации манекенов, используются точно так же.

Как опрашивать статус до получения результата?

Выполняйте GET `/api/v1/eyewear-studio/:id` каждые 3 секунды, пока `data.status` не станет `completed` или `failed`. Вебхуков нет: документированный способ отслеживания завершения — polling.

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

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

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

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

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