Возможность · Ювелирные изделия

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 · проверено

POST/api/v1/tryon/jewelry
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')
A necklace rendered on an AI model by the jewelry try-on API
Пример результата

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

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

Эндпоинт
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')

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

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

jewelry_image

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

URL or base64 data URI of the jewelry product image.

jewelry_type

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

Type of jewelry.

Значения: necklaceearringsbraceletring
mannequin_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

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

Тип: string

Output aspect ratio. 1:1 is not available at 4K resolution — that combination returns 400.

= 3:4

Значения: 3:41:14:39:1616:9
user_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.

Ошибки

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

    Тот же флоу, что и для одежды — ai.photta.app → Developers → Generate API key. Один ключ работает со всеми эндпоинтами; единый баланс credits покрывает все возможности.

  2. Шаг 2

    Выберите крупный план манекена

    Получите список манекенов для украшений или загрузите свой собственный через `POST /api/v1/mannequins/jewelry` — Photta предоставляет специализированный набор манекенов крупного плана с текстурой кожи, оптимизированной под мелкий металл и камни.

  3. Шаг 3

    Отправьте задачу на примерку украшения через POST

    Отправьте POST-запрос на `/api/v1/tryon/jewelry` с `jewelry_image`, `jewelry_type`, `mannequin_id` и опциональными `background`, `resolution` и `aspect_ratio`. Сервис автоматически масштабирует и размещает изделие под категорию украшения.

  4. Шаг 4

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

    Делайте GET `/api/v1/tryon/jewelry/:id` каждые 3 секунды. Структура ответа идентична одежде — `data.status`, `data.output_url`, `data.thumbnail_url`.

  5. Шаг 5

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

    Плотное кадрирование 1:1 лучше всего подходит для миниатюр на PDP; более широкие соотношения сторон — для editorial-контента. Сохраняйте байты у себя вместо хотлинкинга с CDN.

Вопросы разработчиков перед релизом 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 Photta · проверено

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

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

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