cURL · API примерки ювелирных изделий
API примерки ювелирных изделий с помощью cURL
В двух словах
Экспортируйте PHOTTA_API_KEY, выполните POST к https://api.photta.app/api/v1/api/v1/tryon/jewelry с документированным JSON-телом, сохраните ID генерации, а затем циклически делайте GET к /api/v1/tryon/jewelry/{id} каждые 3 секунды, пока data.status не станет completed. Используйте jq для извлечения URL результата.
- Типичное время: 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')
# $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/jewelry/$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'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.status
async function waitFor(id) {
for (let attempt = 0; attempt < 120; attempt++) {
const res = await fetch(`https://api.photta.app/api/v1/tryon/jewelry/${id}`, { headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}` } });
const { data } = await res.json();
if (data.status === "completed") return data.output_url;
if (data.status === "failed") throw new Error(data.error_message ?? "generation failed");
await new Promise((r) => setTimeout(r, 3000));
}
throw new Error("timed out after 6 minutes");
}import 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"]
import time
def wait_for(job_id):
for _ in range(120):
res = requests.get(f"https://api.photta.app/api/v1/tryon/jewelry/{job_id}", headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"})
data = res.json()["data"]
if data["status"] == "completed":
return data["output_url"]
if data["status"] == "failed":
raise RuntimeError(data.get("error_message", "generation failed"))
time.sleep(3)
raise TimeoutError("timed out after 6 minutes")Коротко о главном
Коротко о главном
- Эндпоинт
- 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
- Идемпотентность
- Нет
Как это работает
Пять шагов в шелле, ноль зависимостей, кроме curl и jq.
Шаг 1
Регистрация и генерация ключа
Перейдите на ai.photta.app, откройте вкладку Developers, нажмите Generate API key. Боевые ключи начинаются с `photta_live_`.
Шаг 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
Фиксация базового 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
Отправка и polling
Отправьте POST-запрос на `$PHOTTA_BASE_URL/api/v1/tryon/jewelry`, чтобы получить ID, затем вызывайте в цикле `curl $PHOTTA_BASE_URL/api/v1/tryon/jewelry/{id}` каждые 3 секунды. Передавайте ответ через пайп в jq, чтобы аккуратно извлечь `.data.status`.
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') # $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/jewelry/$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
Сохранение результата
Когда задача завершится, извлеките `.data.output_url` с помощью jq и выполните `curl -o`, чтобы сохранить байты в локальное хранилище — готово для следующего этапа вашего пайплайна.
Ошибки
- 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.
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`.
Связанные страницы
Node.js
API примерки ювелирных изделий на Node.js
Вызывайте aPI примерки ювелирных изделий от Photta из бэкенда на Node.js с помощью нативного fetch. SDK не требуется: сохраните ключ, отправьте задачу, получите результат через polling.
ЧитатьPython
API примерки ювелирных изделий на Python
Вызывайте Photta aPI примерки ювелирных изделий на Python с помощью библиотеки requests. Обертка на тридцать строк, поддержка асинхронности через httpx, работает в Django, FastAPI и Celery.
ЧитатьВозможности
API примерки ювелирных изделий для колье, колец, браслетов и серег
Примерка ожерелий, колец, браслетов и серёг на AI-моделях через REST. 5 credits в 2K, встроенные манекены крупным планом, рендеринг с учётом отражений из документации Photta.
ЧитатьРазработка
Создайте сервис AI-фотографии товаров
Руководство для основателей по перепродаже API виртуального try-on от Photta как white-label SaaS: ключи для тенантов, пакетный fanout, биллинг за credits, реальность SLA.
ЧитатьБыстрый старт
Первое изображение в Photta менее чем за 5 минут.
Зарегистрируйтесь, сгенерируйте API-ключ, выполните первый вызов cURL, опрашивайте статус до завершения, сохраните результат. 5 шагов с полным описанием.
ЧитатьСправочник
Тарифы Photta API
Сколько стоит каждый endpoint Photta API в credits при 2K и 4K, как устроены списания и возвраты, и какие эндпоинты бесплатны. Никаких цен в деньгах за изображение.
Читать
Все показатели на этой странице взяты из документации API Photta · проверено
Протестируйте API за пять минут
Сгенерируйте API-ключ Photta, вставьте пример cURL выше, и вы получите первое изображение на модели быстрее, чем сварится кофе.
- 1.5–4 min
- 5 credits при 2K · 6 credits при 4K
- async, polling
- 600 запросов/мин
- Ключ Bearer