Возможность · Ювелирные изделия
API примерки ювелирных изделий для колье, колец, браслетов и серег
В двух словах
API примерки ювелирных изделий Photta принимает фото украшения, jewelry_type (necklace, ring, bracelet или earrings) и ID манекена, возвращая фото модели крупным планом. Отправьте POST, опрашивайте каждые 3 секунды, скачайте по достижении статуса completed.
- Типичное время: 1.5–4 min
- Кредиты: 5 credits при 2K · 6 credits при 4K
- Обработка: async, polling
- Лимиты: 600 запросов/мин
- Аутентификация: Ключ Bearer
Все показатели на этой странице взяты из документации API Photta · проверено
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/jewelry \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
},
)
data = res.json()["data"] # data["id"], data["status"]
Коротко о главном
Коротко о главном
- Эндпоинт
- POST /api/v1/tryon/jewelry
- Аутентификация
- API-ключ Bearer
- Обработка
- Асинхронно — опрашивайте эндпоинт статуса
- Типичное время
- 1.5–4 min
- Кредиты
- 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/tryon/jewelry \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/tryon/jewelry", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/tryon/jewelry",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"background": "soft window light on dark velvet",
"resolution": "2K",
"aspect_ratio": "3:4",
"user_instruction": "Make the pendant 10% smaller."
},
)
data = res.json()["data"] # data["id"], data["status"]202 Accepted / Завершено
{
"data": {
"id": "jwl_a1b2c3",
"status": "processing",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 5,
"created_at": "2026-04-10T14:00:00Z"
},
"request_id": "req_jwl001"
}{
"data": {
"id": "jwl_a1b2c3",
"status": "completed",
"jewelry_type": "necklace",
"mannequin_id": "mnk_j9k1l2",
"resolution": "2K",
"aspect_ratio": "3:4",
"output_url": "https://cdn.photta.app/generated/jwl_a1b2c3.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/jwl_a1b2c3-thumb.jpg",
"credits_used": 5,
"created_at": "2026-04-10T14:00:00Z",
"completed_at": "2026-04-10T14:01:10Z",
"duration_ms": 70000
},
"request_id": "req_jwl002"
}Параметры запроса
jewelry_imageТип: stringОбязательное
URL or base64 data URI of the jewelry product image.
jewelry_typeТип: stringОбязательное
Type of jewelry.
Значения:necklaceearringsbraceletringmannequin_idТип: stringОбязательное
ID of the mannequin. Must be jewelry-compatible and have a matching close-up view for the given jewelry_type. Use GET /api/v1/mannequins?jewelry_type=necklace to find compatible mannequins.
backgroundТип: string
Optional. Pass a URL or base64 data URI to use a reference photo as the scene; pass any other string to use it as a free-form text description (e.g. "soft window light on dark velvet"). When omitted, the original mannequin backdrop is preserved.
resolutionТип: string
Output resolution. "2K" costs 5 credits per image; "4K" costs 6 credits per image. 4K is produced natively in a single generation — pick it upfront; the resolution cannot be changed after creation. 4K cannot be combined with aspect_ratio 1:1 (returns 400).
= 2K
Значения:2K4Kaspect_ratioТип: string
Output aspect ratio. 1:1 is not available at 4K resolution — that combination returns 400.
= 3:4
Значения:3:41:14:39:1616:9user_instructionТип: string
Free-form refinement, e.g. "make the pendant 10% smaller", "keep the clasp visible at the back of the neck". Capped at 400 characters server-side; longer strings are silently truncated. Requests to change the jewelry's size, scale, or proportions are honored and take priority; any other instruction applies only where it does not conflict with reproducing the jewelry exactly from the reference image. Not a determinism or seed control.
Ошибки
- 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-ключ
Тот же флоу, что и для одежды — ai.photta.app → Developers → Generate API key. Один ключ работает со всеми эндпоинтами; единый баланс credits покрывает все возможности.
Шаг 2
Выберите крупный план манекена
Получите список манекенов для украшений или загрузите свой собственный через `POST /api/v1/mannequins/jewelry` — Photta предоставляет специализированный набор манекенов крупного плана с текстурой кожи, оптимизированной под мелкий металл и камни.
Шаг 3
Отправьте задачу на примерку украшения через POST
Отправьте POST-запрос на `/api/v1/tryon/jewelry` с `jewelry_image`, `jewelry_type`, `mannequin_id` и опциональными `background`, `resolution` и `aspect_ratio`. Сервис автоматически масштабирует и размещает изделие под категорию украшения.
Шаг 4
Опрашивайте статус до завершения задачи
Делайте GET `/api/v1/tryon/jewelry/:id` каждые 3 секунды. Структура ответа идентична одежде — `data.status`, `data.output_url`, `data.thumbnail_url`.
Шаг 5
Скачайте и сохраните
Плотное кадрирование 1:1 лучше всего подходит для миниатюр на PDP; более широкие соотношения сторон — для editorial-контента. Сохраняйте байты у себя вместо хотлинкинга с CDN.
Один и тот же эндпоинт на 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 для построения скриптовых пайплайнов.
Читать
Вопросы разработчиков перед релизом try-on для украшений
Какие типы украшений поддерживаются?
Четыре явные категории: necklace, ring, bracelet, earrings. Для каждой категории есть собственный набор специализированных манекенов крупного плана и эвристика размещения, настроенная под соответствующий форм-фактор. Для колец и серег лучше всего подходит соотношение сторон 1:1; колье и ожерелья отлично смотрятся в 3:4.
Сколько стоит try-on для украшений?
Так же, как и для одежды: 5 credits в разрешении 2K, 6 credits в 4K. За неудачные задачи credits возвращаются автоматически. Дополнительной платы за библиотеку манекенов крупного плана нет.
Чем эндпоинт для украшений отличается от эндпоинта для одежды?
Та же аутентификация, тот же паттерн поллинга, та же структура ответа — отличия только в теле запроса. Вы передаете `jewelry_type` и `jewelry_image` вместо `product_type` и `product_images`, а также выбираете манекены с фильтрацией по категории украшений. Все остальное (2K/4K, соотношения сторон, credits) совпадает.
Могу ли я загрузить собственную модель для украшений?
Да — `POST /api/v1/mannequins/jewelry` принимает референс крупного плана, а `POST /api/v1/mannequins/jewelry/generate` создает новый на основе параметров. Оба эндпоинта возвращают ID, который затем передается в запрос на try-on.
Как система обрабатывает отражающие металлы и драгоценные камни?
Пайплайн крупного плана учитывает метаданные о зеркальных бликах и микрогеометрии. Золото, серебро и зеркально полированная платина рендерятся корректно, без размытия, артефактов или смазывания хроматических аберраций, характерных для универсальных try-on решений. Для наилучших результатов рекомендуются предельно чистые студийные фоны.
Как опрашивать результат?
Делайте GET `/api/v1/tryon/jewelry/:id` каждые 3–5 секунд. Тот же жизненный цикл статусов, что и у одежды: `processing` → `completed` или `failed`. Окно в 1.5–4 минуты покрывает подавляющее большинство задач.
Смежные возможности
Возможности
API виртуального try-on для одежды
REST API, примеряющий одежду на AI-манекены. Асинхронно, генерация за 1.5–4 минуты, 5 credits для 2K, 6 для 4K. Примеры для cURL, Node.js и Python.
Посмотреть endpointВозможности
API невидимого манекена (ghost mannequin) для фото товаров на невидимом манекене
AI-эндпоинт для эффекта невидимого манекена. Удаляет манекен с фото одежды с сохранением деталей внутренней части. 3D или раскладка, пакетная обработка, 4 credits в 2K.
Посмотреть 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 против Ayna — API для разработчиков или студия с фокусом на Shopify
Сравнение Photta и Ayna: три REST-эндпоинта против заточенной под Shopify студии с API. У каждого свои сильные стороны. Данные собраны с сайтов 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 выше, и вы получите первое изображение на модели быстрее, чем сварится кофе.
- 1.5–4 min
- 5 credits при 2K · 6 credits при 4K
- async, polling
- 600 запросов/мин
- Ключ Bearer