Возможность · Workflows

Workflows API один вызов — один пресет

В двух словах

Workflows API от Photta применяет готовые шаблоны сцен к фотографиям ваших товаров. Получите каталог, заполните слоты изображений и опции воркфлоу, отправьте POST-запрос, затем опрашивайте каждый возвращённый элемент до завершения.

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

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

POST/api/v1/workflows/{workflow_id}
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')

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

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

Эндпоинт
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')

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"
}

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

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:9
resolution

Тип: string

Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.

= 2K

Значения: 2K4K

Ошибки

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 не отправляет вебхуки.

Получите каталог, заполните слоты, запустите

Получите список воркфлоу, заполните объявленные слоты, отправьте запрос, опросите каждый элемент, скачайте.

  1. Шаг 1

    Сгенерируйте API-ключ

    Воркфлоу используют те же учетные данные и тот же баланс credits, что и любая другая возможность Photta.

  2. Шаг 2

    Получите каталог воркфлоу

    GET `/api/v1/workflows` возвращает 53 шаблона в 7 категориях, каждый из которых объявляет собственные слоты изображений, перечисления опций и соотношение сторон по умолчанию. Фильтруйте через `category` — неизвестная категория возвращает 400 вместо игнорирования.

  3. Шаг 3

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

    Выполните POST `/api/v1/workflows/:workflow_id` с `images` (сопоставление id слота с изображениями) и `options` (сопоставление id опции с id выбора), взятыми из записи каталога. `user_text` принимает произвольный текст с пожеланиями по стилю, а `num_images` запускает генерацию от 1 до 4 изображений за один вызов.

  4. Шаг 4

    Опрашивайте каждый элемент

    Ответ 202 содержит по одному элементу на каждое запрошенное изображение. Выполняйте GET `/api/v1/workflows/generations/:id` каждые 3 секунды для каждого id, пока `data.status` не станет `completed` или `failed`; стандартное время генерации составляет от 20 до 60 секунд на изображение.

  5. Шаг 5

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

    Каждый завершённый элемент содержит собственный `output_url`. Элементы генерируются независимо, поэтому вы можете опубликовать первый результат, пока остальные ещё рендерятся.

Вопросы разработчиков перед запуском воркфлоу

Что такое 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 Photta · проверено

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

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

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