Возможность · 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 · проверено
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')const res = await fetch("https://api.photta.app/api/v1/eyewear-studio", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/eyewear-studio",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]
Коротко о главном
Коротко о главном
- Эндпоинт
- 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')const res = await fetch("https://api.photta.app/api/v1/eyewear-studio", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/eyewear-studio",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"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"
},
)
data = res.json()["data"] # data["id"], data["status"]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"
}{
"data": {
"id": "eyw_7a1c9e42f05b3d688c2e4f01a9d6b357",
"status": "completed",
"mode": "product-only",
"sub_tool": "studio-shot",
"output_url": "https://cdn.photta.app/generated/eyw_7a1c9e42f05b3d688c2e4f01a9d6b357.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/eyw_7a1c9e42f05b3d688c2e4f01a9d6b357-thumb.jpg",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 5,
"created_at": "2026-08-01T09:15:00Z",
"completed_at": "2026-08-01T09:15:38Z"
},
"request_id": "req_eyw002"
}Параметры запроса
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-modelsub_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-laylifestylefloatingmannequin_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-profileexpressionТип: string
On-model only: the model's facial expression.
= neutral
Значения:neutralsoft-smileseriousconfidentlighting_styleТип: string
On-model only: how the portrait is lit.
= soft-diffused
Значения:soft-diffusedstudionaturaldramaticframe_fit_styleТип: string
On-model only: the overall styling of how the frames are worn.
= casual
Значения:casualprofessionalfashion-editorialsportybackdropТип: string
Studio-shot only: the backdrop behind the eyewear.
= white
Значения:whitegrayblackgradientlightingТип: string
Studio-shot only: the lighting setup.
= soft
Значения:softharddramaticnaturalsurfaceТип: string
Flat-lay only: the surface the eyewear lies on.
= marble
Значения:marblewoodfabricconcretemetalarrangement_styleТип: string
Flat-lay only: how the composition is arranged.
= minimal
Значения:minimalsymmetricscatteredlayeredpropsТип: string
Flat-lay only: complementary props placed around the eyewear.
= none
Значения:noneplantsaccessoriestechsceneТип: string
Lifestyle only: the real-world setting.
= coffee-shop
Значения:coffee-shopbeachurban-streetofficeparkmoodТип: string
Lifestyle only: the color mood of the scene.
= warm
Значения:warmcoolvibrantmoodyangleТип: string
Floating only: the camera angle on the suspended frames.
= front
Значения:frontthree-quartersidetop-downshadow_styleТип: string
Floating only: the shadow cast beneath the frames.
= soft-drop
Значения:soft-dropnonehard-dropreflectionbackground_colorТип: string
Solid background color. Applies in both modes. Overridden by background_prompt when both are sent.
= white
Значения:whitegrayblackbeigebackground_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:9resolutionТип: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Значения:2K4K
Ошибки
- 400
invalid_request_error - The request is malformed or contains invalid parameters.
- 401
authentication_error - The API key is missing, invalid, or expired.
- 402
insufficient_credits_error - Your account does not have enough credits.
- 404
not_found_error - The requested resource does not exist.
- 409
conflict_error - The request conflicts with current state — e.g. your concurrent-batch cap is reached.
- 429
rate_limit_error - Too many requests. Slow down and retry.Retry-After: 30
- 500
api_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
Сгенерируйте API-ключ
Eyewear studio использует те же учетные данные и тот же баланс credits, что и любая другая возможность Photta.
Шаг 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
Отправьте задачу на генерацию через POST
Отправьте POST-запрос на `/api/v1/eyewear-studio` с `eyewear_image` и полями стилизации. Поле `background_prompt` принимает до 400 символов и переопределяет `background_color`. Единственный сигнал о готовности — polling, API не отправляет вебхуки.
Шаг 4
Опрашивайте статус до завершения задачи
Выполняйте GET `/api/v1/eyewear-studio/:id` каждые 3 секунды, пока `data.status` не примет значение `completed` или `failed`; обычное время выполнения — от 20 до 60 секунд.
Шаг 5
Скачайте и сохраните результат
В теле ответа завершенной задачи возвращаются `output_url` и превью. Сохраняйте файл на своей стороне: URL служит для доставки результата одной задачи, а не для постоянного хостинга.
Один и тот же эндпоинт на Node.js, Python и cURL
Node.js
API виртуальной примерки очков на Node.js
Вызывайте aPI виртуальной примерки очков от Photta из бэкенда на Node.js с помощью нативного fetch. SDK не требуется: сохраните ключ, отправьте задачу, получите результат через polling.
ЧитатьPython
API виртуальной примерки очков на Python
Вызывайте Photta aPI виртуальной примерки очков на Python с помощью библиотеки requests. Обертка на тридцать строк, поддержка асинхронности через httpx, работает в Django, FastAPI и Celery.
ЧитатьcURL
API виртуальной примерки очков с помощью cURL
Вызывайте aPI виртуальной примерки очков от Photta напрямую из терминала с помощью cURL. Отправка, поллинг, загрузка — каждый фрагмент готов к использованию с jq для построения скриптовых пайплайнов.
Читать
Вопросы, которые разработчики задают перед интеграцией генерации очков
Что делает 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 виртуального try-on для одежды
REST API, примеряющий одежду на AI-манекены. Асинхронно, генерация за 1.5–4 минуты, 5 credits для 2K, 6 для 4K. Примеры для cURL, Node.js и Python.
Посмотреть endpointВозможности
API примерки ювелирных изделий для колье, колец, браслетов и серег
Примерка ожерелий, колец, браслетов и серёг на AI-моделях через REST. 5 credits в 2K, встроенные манекены крупным планом, рендеринг с учётом отражений из документации Photta.
Посмотреть endpointРазработка
Создайте сервис AI-фотографии товаров
Руководство для основателей по перепродаже API виртуального try-on от Photta как white-label SaaS: ключи для тенантов, пакетный fanout, биллинг за credits, реальность SLA.
Посмотреть endpointСравнение
Photta против FASHN — прямое сравнение fashion AI API
Сравнение Photta и FASHN: эндпоинты, цены в credits, тарифные планы, лимиты параллельных запросов. Данные собраны с официальных страниц с тарифами обеих компаний на 2026-04-19. Никаких выдуманных цифр.
Посмотреть endpointБыстрый старт
Первое изображение в Photta менее чем за 5 минут.
Зарегистрируйтесь, сгенерируйте API-ключ, выполните первый вызов cURL, опрашивайте статус до завершения, сохраните результат. 5 шагов с полным описанием.
Посмотреть endpointСправочник
Ошибки Photta API
Полный список типов ошибок Photta API с их статус-кодами, формат тела ошибки и сбои, которые имеет смысл повторять.
Посмотреть endpointСправочник
Rate limits в Photta API
Rate limit Photta API, его окно, заголовок Retry-After, интервал polling и ограничения параллелизма по планам — прямо из документации API.
Посмотреть endpoint
Все показатели на этой странице взяты из документации API Photta · проверено
Протестируйте API за пять минут
Сгенерируйте API-ключ Photta, вставьте пример cURL выше, и вы получите первое изображение на модели быстрее, чем сварится кофе.
- 20–60 sec
- 5 credits при 2K · 6 credits при 4K
- async, polling
- 600 запросов/мин
- Ключ Bearer