cURL · API виртуального try-on

API виртуального try-on с помощью cURL

В двух словах

Экспортируйте PHOTTA_API_KEY, выполните POST к https://api.photta.app/api/v1/api/v1/tryon/apparel с документированным JSON-телом, сохраните ID генерации, а затем циклически делайте GET к /api/v1/tryon/apparel/{id} каждые 3 секунды, пока data.status не станет completed. Используйте jq для извлечения URL результата.

  • Типичное время: 1.5–4 min
  • Кредиты: 5 credits при 2K · 6 credits при 4K
  • Обработка: async, polling
  • Лимиты: 600 запросов/мин
  • Аутентификация: Ключ Bearer

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

POST/api/v1/tryon/apparel
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')

# $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'

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

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

Эндпоинт
POST /api/v1/tryon/apparel
Аутентификация
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
Идемпотентность
Нет

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

Пять шагов в шелле, ноль зависимостей, кроме curl и jq.

  1. Шаг 1

    Регистрация и генерация ключа

    Перейдите на ai.photta.app, откройте вкладку Developers, нажмите Generate API key. Боевые ключи начинаются с `photta_live_`.

  2. Шаг 2

    Экспорт ключа

    Добавьте `export PHOTTA_API_KEY="photta_live_xxx"` в профиль вашего шелла или в файл `.envrc`, чтобы каждый последующий вызов curl подхватывал его автоматически.

    curl --version   # macOS, Linux, WSL and Windows 10+ ship it
    export PHOTTA_API_KEY="photta_live_xxxxx"
  3. Шаг 3

    Фиксация базового URL

    `export PHOTTA_BASE_URL="https://api.photta.app/api/v1"` сократит команды curl.

    export PHOTTA_BASE_URL="https://api.photta.app/api/v1"
    export AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"
  4. Шаг 4

    Отправка и polling

    Отправьте POST-запрос на `$PHOTTA_BASE_URL/api/v1/tryon/apparel`, чтобы получить ID, затем вызывайте в цикле `curl $PHOTTA_BASE_URL/api/v1/tryon/apparel/{id}` каждые 3 секунды. Передавайте ответ через пайп в jq, чтобы аккуратно извлечь `.data.status`.

    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')
    
    # $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'
  5. Шаг 5

    Сохранение результата

    Когда задача завершится, извлеките `.data.output_url` с помощью jq и выполните `curl -o`, чтобы сохранить байты в локальное хранилище — готово для следующего этапа вашего пайплайна.

Ошибки

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.
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

Лимиты

  • 600 запросов в минуту на один API-ключ (Фиксированное окно; лимит одинаков для всех планов)
  • Ответ 429 содержит заголовок Retry-After: 30 секунд
  • До 10 МБ на изображение
  • Форматы: JPEG, PNG, WebP
  • Параллельных пакетов на план: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • Только polling — API не отправляет вебхуки.

Почему cURL — по-прежнему самый быстрый способ проверить API

  • Без установки — cURL поставляется с каждой популярной ОС
  • Отлично работает в связке с jq для скриптовых пайплайнов (CI, cron, хуки оболочки)
  • Самый быстрый способ выполнить smoke-тестирование эндпоинта перед интеграцией в код
  • Каждая команда на этой странице вставляется в любую POSIX-оболочку

Для чего это не подходит

  • Цикл polling блокирует терминал — для параллельных воркеров переходите на Node или Python
  • Polling — единственный способ отследить завершение; API не отправляет вебхуки
  • Пользователям командной строки Windows лучше запускать WSL или curl.exe в PowerShell

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

Есть ли CLI-утилита для Photta?

Пока нет, но связка cURL и bash-обертки на 15 строк решает большинство задач. В документации приоритет отдается примерам на cURL, поскольку любой язык умеет запускать подпроцессы, а командная строка — это общий знаменатель в CI-пайплайнах.

Нужен ли jq для работы с API?

Строго говоря, нет, но скриптовые пайплайны с ним строить намного проще. jq позволяет доставать `.data.id`, `.data.status` и `.data.output_url` из JSON-ответа без ручного парсинга. Установка: `brew install jq` на macOS или `apt install jq` на Debian/Ubuntu.

Как аутентифицироваться в curl?

Добавьте `-H "Authorization: Bearer $PHOTTA_API_KEY"` к каждому запросу. Храните ключ в переменной окружения и никогда не хардкодьте его в скриптах, попадающих в репозиторий. Вариант `curl --oauth2-bearer` тоже работает, но явный заголовок нагляднее в документации и логах.

Можно ли использовать скрипты на curl в проде?

Для разовых пакетных бэкфиллов и cron-задач — да, тысячи команд обновляют каталоги именно так. Для долгоживущих приложений надежнее взять полноценный язык программирования: вы получите корректную обработку ошибок, повторные попытки и мониторинг. Примеры с curl на этой странице останутся актуальными и после переноса на Node или Python: структура запроса не меняется.

Как реализовать polling в цикле bash?

Используйте конструкцию `for i in $(seq 1 120); do … ; sleep 3; done` с проверкой статуса внутри тела цикла. Прерывайте цикл, когда `.data.status` примет значение `completed` или `failed`. В примере кода на этой странице показан точный паттерн, включая жесткий лимит итераций, чтобы зависшая задача не подвесила скрипт навсегда.

Как читать ответы с ошибками в curl?

Используйте флаг `curl -w "\n%{http_code}"`, чтобы получить HTTP-код статуса вместе с телом JSON. Настройте ветвление по коду: 402 при нехватке credits, 429 при срабатывании rate limit (учитывайте значение заголовка Retry-After), 5xx при временных сбоях сервера. В теле ошибки всегда присутствуют поля `error.code` и `error.message`.

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

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

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

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

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