Быстрый старт

Первое изображение в Photta менее чем за 5 минут.

В двух словах

Зарегистрируйтесь на ai.photta.app, нажмите Generate API key, экспортируйте его как PHOTTA_API_KEY, отправьте POST на /api/v1/tryon/apparel и опрашивайте возвращенный ID генерации каждые 3 секунды, пока статус не изменится на completed — обычно это занимает от 1.5 до 4 минут.

Получить API-ключДокументация
  • Аутентификация: Ключ Bearer
  • Обработка: async, polling
  • Лимиты: 600 запросов/мин

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

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

Как это работает

5 команд от старта до первого изображения

Вставляйте их в терминал по порядку. Каждый сниппет самодостаточен и требует только curl + jq.

  1. Шаг 1

    Генерация API-ключа

    Зарегистрируйтесь на ai.photta.app и перейдите в панель Developers. Нажмите Generate API key — боевые ключи начинаются с префикса photta_live_. Экспортируйте его, чтобы команды из этого руководства могли прочитать его из окружения оболочки.

    # https://ai.photta.app → Developers → Generate API key
export PHOTTA_API_KEY="photta_live_xxxxx"
export PHOTTA_BASE_URL="https://api.photta.app/api/v1"

  2. Шаг 2

    Отправка первого запроса на try-on

    Выполните запрос к /api/v1/tryon/apparel, передав URL изображения товара и mannequin ID. API мгновенно вернет ответ 202 Accepted с ID генерации в поле data.id.

    RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

  3. Шаг 3

    Polling до завершения задачи

    GET /api/v1/tryon/apparel/:id каждые 3 секунды. Обычное время выполнения — 1.5–4 минуты. Ограничьте число попыток сверху, чтобы зависшая задача не подвесила ваш скрипт навсегда.

    # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
  RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/apparel/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
  sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'

  4. Шаг 4

    Сохраняйте результат у себя

    Когда статус сменится на completed, поле data.output_url будет содержать ссылку на готовое изображение. Скачайте байты в собственное хранилище, чтобы ваш продукт не зависел от CDN Photta при отображении.

    OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url')
curl -sO "$OUTPUT_URL"
echo "Saved $(basename "$OUTPUT_URL")"

  5. Шаг 5

    Корректно обрабатывайте сбои

    Ветвите логику по HTTP-статусу: 402 при нехватке credits, 429 при превышении rate limit (учитывайте Retry-After), 5xx при временных ошибках сервера. В теле каждой ошибки возвращается машиночитаемый error.code, на который можно опираться.

    case "$STATUS_CODE" in
  402) echo "insufficient_credits_error — top up before retrying" ;;
  429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
  4??) echo "$BODY" | jq '.error.type, .error.message' ;;
  5??) echo "api_error — retry with backoff" ;;
esac

Частые вопросы разработчиков

Вопросы о начале работы

Сколько времени занимает быстрый старт?

Пять минут на регистрацию, генерацию ключа и первый cURL-запрос. Сама генерация занимает от 1.5 до 4 минут, так что рассчитывайте примерно на десять минут общего времени до получения первого изображения на модели.

Нужна ли банковская карта для тестирования?

Новые аккаунты получают пробные credits, которые можно потратить до внесения оплаты. Когда будете готовы к запуску в продакшен, оформите подписку на тарифный план, чтобы получить больший ежемесячный объем credits и более высокие rate limits.

С какого endpoint стоит начать?

Примерка одежды (/api/v1/tryon/apparel) — это самый популярный endpoint с наиболее полной документацией. Он иллюстрирует паттерн асинхронной работы и polling, который используется во всех остальных endpoint Photta. Как только освоитесь с ним, интеграция украшений и съемки на невидимом манекене (ghost mannequin) строится по тем же принципам.

Можно ли вызывать API напрямую из браузера?

Нет. API-ключ должен оставаться на стороне сервера: передача его в браузер скомпрометирует ключ перед каждым посетителем. Проксируйте вызовы через тонкий слой на собственном бэкенде (route handler в Next.js, Express, Flask, Lambda) и отправляйте запросы из браузера только к нему.

Связанные страницы

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

До вашего первого изображения — пять минут

Получить API-ключИзучить API
  • Ключ Bearer
  • async, polling
  • 600 запросов/мин