Возможность · Детальные фото

API детальных фото товара для крупных планов

В двух словах

API детальных фото Photta рендерит крупный план конкретной зоны товара. Бесплатный вызов analyze предлагает список деталей для съёмки; вызов generate стоит фиксированные 3 credits без градаций по разрешению.

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

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

POST/api/v1/detail-photos
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

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

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

Эндпоинт
POST /api/v1/detail-photos
Аутентификация
API-ключ Bearer
Обработка
Асинхронно — опрашивайте эндпоинт статуса
Типичное время
20–60 sec
Кредиты
3 credits
Ограничения на входные данные
До 10 МБ на изображение; JPEG, PNG, WebP
Идемпотентность
Нет

Запрос и ответ

Запрос

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

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

{
  "data": {
    "id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
    "status": "processing",
    "detail_label": "collar stitching",
    "framing": "extreme-closeup",
    "credits_used": 3,
    "created_at": "2026-07-30T14:20:00Z"
  },
  "request_id": "req_dtl001"
}

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

product_image

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

The source image — a completed generation's output_url or any product photo. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

detail_label

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

The area to zoom into, e.g. "collar stitching", "cuff detail", "fabric weave on the chest", "pendant clasp". Max 100 characters.

detail_description

Тип: string

Extra guidance for the close-up. Max 400 characters.

framing

Тип: string

How tight the crop is: "extreme-closeup" — the detail fills ~90% of the frame (near-macro); "closeup" — ~70% with some surrounding context; "medium-closeup" — ~50% with body/outfit visible.

= medium-closeup

Значения: extreme-closeupcloseupmedium-closeup
source_type

Тип: string

Tunes what is preserved in the close-up.

= apparel

Значения: appareljewelry

Ошибки

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

    Для детальных фото используются те же учетные данные и тот же баланс credits, что и для всех остальных возможностей Photta.

  2. Шаг 2

    Запросите список деталей для съёмки

    Выполните POST `/api/v1/detail-photos/analyze` с `product_image`. Эндпоинт синхронно и бесплатно вернёт рекомендованные значения `detail_label`, `detail_description` и `framing` для этого товара.

  3. Шаг 3

    Отправьте POST-запрос на крупный план

    Выполните POST на `/api/v1/detail-photos` с `product_image` и `detail_label`. Укажите `framing` со значением `extreme-closeup`, `closeup` или `medium-closeup`, `source_type` как `apparel` или `jewelry`, а также добавьте `detail_description` длиной до 400 символов.

  4. Шаг 4

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

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

  5. Шаг 5

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

    Тело ответа при успешном завершении содержит `output_url`. Детальные фото готовы для мгновенной вставки в галерею карточки товара рядом с основным снимком.

Частые вопросы разработчиков перед внедрением детальных фото

Что такое API детальных фото?

Эндпоинт, генерирующий крупный план заданной зоны товара (строчки воротника, застёжки, плетения на груди) из одного общего снимка без необходимости проводить дополнительную студийную макросъёмку.

Сколько стоит детальное фото?

Фиксированные 3 credits. У этого эндпоинта нет тарифных сеток по разрешениям, а вызов analyze для подбора деталей бесплатен.

Что возвращает эндпоинт analyze?

Список предложенных вариантов, каждый из которых содержит `detail_label`, пояснение ценности этой зоны `detail_description` и рекомендуемое значение `framing`. Любой из вариантов можно сразу передавать в вызов generate.

Насколько сильно кадрирует каждый вариант framing?

`extreme-closeup` заполняет деталью практически весь кадр, `closeup` оставляет немного контекста вокруг, а `medium-closeup` показывает деталь в окружении изделия. Выбирайте вариант под конкретную деталь, а не для всего товара в целом.

Может ли исходником быть сгенерированное изображение?

Да. `product_image` принимает `output_url` завершенной генерации, а также любое ваше фото продукта в виде https URL или base64 data URI.

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

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

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

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

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

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

  • 20–60 sec
  • 3 credits
  • async, polling
  • 600 запросов/мин
  • Ключ Bearer