Возможность · Workflows
Workflows API один вызов — один пресет
В двух словах
Workflows API от Photta применяет готовые шаблоны сцен к фотографиям ваших товаров. Получите каталог, заполните слоты изображений и опции воркфлоу, отправьте POST-запрос, затем опрашивайте каждый возвращённый элемент до завершения.
- Типичное время: 20–60 sec / image
- Кредиты: 4 credits при 2K · 5 credits при 4K
- Обработка: async, polling
- Лимиты: 600 запросов/мин
- Аутентификация: Ключ Bearer
Все показатели на этой странице взяты из документации API Photta · проверено
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/workflows/jewelry-studio-shot \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
},
)
data = res.json()["data"] # data["id"], data["status"]Коротко о главном
Коротко о главном
- Эндпоинт
- POST /api/v1/workflows/{workflow_id}
- Аутентификация
- API-ключ Bearer
- Обработка
- Асинхронно — опрашивайте эндпоинт статуса
- Типичное время
- 20–60 sec / image
- Кредиты
- 4 credits при 2K · 5 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/workflows/jewelry-studio-shot \
-H "Authorization: Bearer $PHOTTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')const res = await fetch("https://api.photta.app/api/v1/workflows/jewelry-studio-shot", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
}),
});
const { data } = await res.json(); // data.id, data.statusimport os, requests
res = requests.post(
"https://api.photta.app/api/v1/workflows/jewelry-studio-shot",
headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
json={
"images": {
"jewelry": [
"https://cdn.yourstore.com/products/gold-ring.jpg"
]
},
"options": {
"jewelryLighting": "dramatic",
"backdrop": "dark"
},
"user_text": "hero shot, ring angled slightly toward the camera",
"num_images": 2,
"aspect_ratio": "3:4",
"resolution": "2K"
},
)
data = res.json()["data"] # data["id"], data["status"]202 Accepted / Завершено
{
"data": {
"items": [
{
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "processing",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z"
},
{
"id": "wfl_8b2d64f0a1c9573ee4082d6cb95a3f17",
"workflow_id": "jewelry-studio-shot",
"status": "processing",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z"
}
],
"workflow_id": "jewelry-studio-shot",
"workflow_version": 1,
"credits_used": 8
},
"request_id": "req_wfl002"
}{
"data": {
"id": "wfl_1f7c03a9e5b2486dd90c4b17ae62f508",
"workflow_id": "jewelry-studio-shot",
"status": "completed",
"output_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508.jpg",
"thumbnail_url": "https://cdn.photta.app/generated/wfl_1f7c03a9e5b2486dd90c4b17ae62f508-thumb.jpg",
"resolution": "2K",
"aspect_ratio": "3:4",
"credits_used": 4,
"created_at": "2026-08-03T10:20:00Z",
"completed_at": "2026-08-03T10:20:41Z",
"error_code": null,
"error_message": null
},
"request_id": "req_wfl003"
}Параметры запроса
workflow_idТип: stringОбязательное
The workflow to run — an id from GET /api/v1/workflows (e.g. "jewelry-studio-shot"). Unknown ids return 404.
imagesТип: objectОбязательное
Map of image slot id → array of images (https URL or base64 data URI). Slot ids, required flags, and min/max image counts come from the workflow's image_slots in the catalog. Missing entirely, missing a required slot, using an unknown slot, or exceeding a slot's max_images returns 400.
optionsТип: object
Map of option id → choice id, both from the workflow's options in the catalog. Omitted options use their default_choice. Unknown option ids or choice ids return 400, as does sending an option that a filled image slot replaces (see replaces_options).
user_textТип: string
Free-text styling/framing request (e.g. "hero shot, slightly angled"). Max 500 characters — excess is silently truncated. It never overrides product fidelity: the product always stays true to your images.
num_imagesТип: integer
Images per run, 1-4. Each image is generated independently through the production model pipeline. Credits scale per image.
= 1
aspect_ratioТип: string
Output aspect ratio. Defaults to the workflow's default_aspect_ratio from the catalog (3:4 for every current workflow).
= 3:4
Значения:3:41:14:39:1616:9resolutionТип: string
Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.
= 2K
Значения:2K4K
Ошибки
- 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.
Лимиты
- 600 запросов в минуту на один API-ключ (Фиксированное окно; лимит одинаков для всех планов)
- Ответ 429 содержит заголовок Retry-After: 30 секунд
- До 10 МБ на изображение
- Форматы: JPEG, PNG, WebP
- Параллельных пакетов на план: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
- Только polling — API не отправляет вебхуки.
Получите каталог, заполните слоты, запустите
Получите список воркфлоу, заполните объявленные слоты, отправьте запрос, опросите каждый элемент, скачайте.
Шаг 1
Сгенерируйте API-ключ
Воркфлоу используют те же учетные данные и тот же баланс credits, что и любая другая возможность Photta.
Шаг 2
Получите каталог воркфлоу
GET `/api/v1/workflows` возвращает 53 шаблона в 7 категориях, каждый из которых объявляет собственные слоты изображений, перечисления опций и соотношение сторон по умолчанию. Фильтруйте через `category` — неизвестная категория возвращает 400 вместо игнорирования.
Шаг 3
Отправьте POST-запрос на запуск
Выполните POST `/api/v1/workflows/:workflow_id` с `images` (сопоставление id слота с изображениями) и `options` (сопоставление id опции с id выбора), взятыми из записи каталога. `user_text` принимает произвольный текст с пожеланиями по стилю, а `num_images` запускает генерацию от 1 до 4 изображений за один вызов.
Шаг 4
Опрашивайте каждый элемент
Ответ 202 содержит по одному элементу на каждое запрошенное изображение. Выполняйте GET `/api/v1/workflows/generations/:id` каждые 3 секунды для каждого id, пока `data.status` не станет `completed` или `failed`; стандартное время генерации составляет от 20 до 60 секунд на изображение.
Шаг 5
Скачайте и сохраните
Каждый завершённый элемент содержит собственный `output_url`. Элементы генерируются независимо, поэтому вы можете опубликовать первый результат, пока остальные ещё рендерятся.
Один и тот же эндпоинт на Node.js, Python и cURL
Node.js
Workflows API на Node.js
Вызывайте workflows API от Photta из бэкенда на Node.js с помощью нативного fetch. SDK не требуется: сохраните ключ, отправьте задачу, получите результат через polling.
ЧитатьPython
Workflows API на Python
Вызывайте Photta workflows API на Python с помощью библиотеки requests. Обертка на тридцать строк, поддержка асинхронности через httpx, работает в Django, FastAPI и Celery.
ЧитатьcURL
Workflows API с помощью cURL
Вызывайте workflows API от Photta напрямую из терминала с помощью cURL. Отправка, поллинг, загрузка — каждый фрагмент готов к использованию с jq для построения скриптовых пайплайнов.
Читать
Вопросы разработчиков перед запуском воркфлоу
Что такое workflows API?
Каталог готовых шаблонов сцен, которые вы применяете к собственным фотографиям товаров. Вместо составления промпта вы выбираете воркфлоу и заполняете объявленные им слоты изображений и опции.
Сколько стоит запуск воркфлоу?
4 credits за изображение в 2K и 5 за изображение в 4K, умноженные на `num_images`. В каталоге указана актуальная цена для каждого воркфлоу — считывайте её оттуда, а не рассчитывайте вручную.
Как узнать id воркфлоу?
Выполните GET `/api/v1/workflows`. Каждая запись содержит свой id, категорию, слоты для изображений и опции. Фильтруйте список с помощью `category`: `jewelry`, `product`, `shoe`, `cosmetics`, `food`, `bag` или `watch`.
Что передавать в images и options?
`images` сопоставляет id слота из записи каталога с массивом изображений в виде https URL или base64 data URI. `options` сопоставляет id опции с одним из доступных для неё id вариантов выбора. Структура обоих полей берется из каталога, благодаря чему интеграция продолжает работать при добавлении новых воркфлоу.
Сколько изображений можно сгенерировать за один запуск?
`num_images` принимает значения от 1 до 4. Каждое изображение генерируется независимо и получает собственный id элемента в ответе, поэтому сбой в одном не повлияет на остальные.
Как опрашивать результаты через polling?
Опрашивайте каждый элемент отдельно: GET `/api/v1/workflows/generations/:id` каждые 3 секунды. GET `/api/v1/workflows/generations/list` возвращает постраничный список с фильтрацией по `workflow_id` или `status`.
Связанные возможности
Возможности
API виртуального try-on для одежды
REST API, примеряющий одежду на AI-манекены. Асинхронно, генерация за 1.5–4 минуты, 5 credits для 2K, 6 для 4K. Примеры для cURL, Node.js и Python.
Посмотреть endpointВозможности
API примерки ювелирных изделий для колье, колец, браслетов и серег
Примерка ожерелий, колец, браслетов и серёг на AI-моделях через REST. 5 credits в 2K, встроенные манекены крупным планом, рендеринг с учётом отражений из документации Photta.
Посмотреть endpointРазработка
Создайте сервис AI-фотографии товаров
Руководство для основателей по перепродаже API виртуального try-on от Photta как white-label SaaS: ключи для тенантов, пакетный fanout, биллинг за credits, реальность SLA.
Посмотреть endpointСравнение
Photta против Ayna — API для разработчиков или студия с фокусом на Shopify
Сравнение Photta и Ayna: три REST-эндпоинта против заточенной под Shopify студии с API. У каждого свои сильные стороны. Данные собраны с сайтов 2026-04-19.
Посмотреть endpointБыстрый старт
Первое изображение в Photta менее чем за 5 минут.
Зарегистрируйтесь, сгенерируйте API-ключ, выполните первый вызов cURL, опрашивайте статус до завершения, сохраните результат. 5 шагов с полным описанием.
Посмотреть endpointСправочник
Ошибки Photta API
Полный список типов ошибок Photta API с их статус-кодами, формат тела ошибки и сбои, которые имеет смысл повторять.
Посмотреть endpointСправочник
Rate limits в Photta API
Rate limit Photta API, его окно, заголовок Retry-After, интервал polling и ограничения параллелизма по планам — прямо из документации API.
Посмотреть endpoint
Все показатели на этой странице взяты из документации API Photta · проверено
Протестируйте API за пять минут
Сгенерируйте API-ключ Photta, вставьте пример cURL выше, и вы получите первое изображение на модели быстрее, чем сварится кофе.
- 20–60 sec / image
- 4 credits при 2K · 5 credits при 4K
- async, polling
- 600 запросов/мин
- Ключ Bearer