Документация API

PhotoFig API

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

Нужна машиночитаемая схема? Скачать OpenAPI JSON.

На этой странице

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

Создайте API-ключ в разделе Настройки. Замените YOUR_API_KEY ниже и сохраните тестовое фото под именем product.jpg.

  1. Отправьте фото

    Загрузите фото, чтобы добавить тень товара. В ответе придут идентификатор задачи и ссылка statusUrl.

    curl https://api.photofig.com/v1/tools/ai-shadows/edit \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "image=@product.jpg"
  2. Проверьте статус задачи

    Подставьте полученный statusUrl вместо STATUS_URL. Пока статус равен queued или processing, подождите перед следующей проверкой.

    curl "STATUS_URL" \
      -H "Authorization: Bearer YOUR_API_KEY"
  3. Скачайте результат

    Когда статус сменится на completed, подставьте полученный resultUrl вместо RESULT_URL, чтобы сохранить изображение.

    curl -fL "RESULT_URL" -o photofig-result.png

Используйте раздел Вебхуки, чтобы получать события о завершении автоматически.

Аутентификация

Маршруты API принимают API-ключи, созданные в разделе Настройки. Полный секретный ключ показывается только один раз сразу после создания.

Authorization: Bearer pf_live_...

API-ключи работают только с конечными точками, описанными на этой странице; все остальные маршруты PhotoFig их отклоняют. Ключ действует от имени создавшего его пользователя и в том рабочем пространстве, где был создан.

Лимиты и квоты

Доступ к API включён в каждый тариф. Запрос GET /v1/account показывает лимиты вашего тарифа и остаток на текущий период: API-обтравки в поле apiCutouts и число новых запросов в минуту в поле limits.writesPerMinute. Дополнительный API-блок добавляет API-обтравки и ИИ-кредиты к любому тарифу и повышает лимиты запросов; его название возвращается в поле apiBlock.

Запросы, запускающие или изменяющие работу (POST, PATCH, DELETE), расходуют минутный лимит. Чтение статусов задач, списков и результатов не учитывается. В учитываемых ответах передаются заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. При исчерпании квоты API возвращает 429 rate_limit_exceeded с заголовком Retry-After.

Инструменты mask, ai-bg и ai-shadows расходуют по одной API-обтравке, так как каждый из них удаляет фон; ai-bg и ai-shadows также списывают по одному ИИ-кредиту. Инструмент resize не расходует ни того ни другого. API-обтравка резервируется на время выполнения задачи и списывается только при успешном завершении; при сбое или отмене она возвращается. Когда API-обтравки заканчиваются, новые запросы получают 402 api_cutouts_exhausted до начала следующего периода. Удаления фона в веб-приложении считаются отдельно. В пакетах каждое фото списывает одну API-обтравку по завершении, а ожидающие фото резервируют квоту на время обработки.

Ожидающие и выполняющиеся задачи API учитываются в лимите одновременных задач тарифа (limits.maxInFlight) отдельно от задач в веб-приложении. При превышении этого порога новые запросы получают 429 too_many_jobs с заголовком Retry-After, пока не завершатся текущие задачи.

Запросы на создание ресурсов (загрузок, обработок, шаблонов, пакетов, загрузок в пакет, запуска пакета и публичных ссылок) поддерживают необязательный заголовок X-Idempotency-Key. Повторный запрос с тем же ключом вернёт исходный ответ вместо запуска дублирующей задачи, поэтому генерируйте новый ключ для каждой отдельной операции.

Аккаунт

GET/v1/account

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

{
  "accountId": "uuid",
  "workspaceId": "uuid",
  "plan": "pro",
  "apiBlock": null,
  "apiEnabled": true,
  "credits": {
    "remaining": 2000,
    "bonusRemaining": 0,
    "periodEndsAt": "2026-11-01T00:00:00Z"
  },
  "apiCutouts": {
    "limit": 500,
    "used": 0,
    "remaining": 500,
    "periodEndsAt": "2026-11-01T00:00:00Z"
  },
  "limits": {
    "maxFileSizeBytes": 10485760,
    "writesPerMinute": 20,
    "maxInFlight": 20,
    "maxApiKeys": 2,
    "freeBgRemovals": 0,
    "bgRemovalsUsed": 0,
    "aiCredits": 2000
  },
  "tools": [
    "mask",
    "ai-bg",
    "ai-shadows",
    "resize"
  ]
}

Инструменты

GET/v1/tools
GET/v1/tools/{tool_id}

Каждый инструмент принимает обычное фото товара через imageUrl, uploadSessionId или multipart-загрузку. Вызывать mask заранее не нужно: ai-bg и ai-shadows сами удаляют фон.

mask

Удаляет фон и возвращает PNG с вырезанным товаром на прозрачном фоне. Используйте его, когда изолированный товар нужен для собственной вёрстки или публикации на маркетплейсе.

ai-shadows

Добавляет реалистичную тень товара и возвращает изображение, готовое к размещению на чистом фоне. Лучше всего работает на кадрах, где товар хорошо виден и не перекрыт пёстрым окружением.

ai-bg

Генерирует новый фон для товара по короткому описанию сцены, например тёплая дубовая столешница или минималистичная белая студия. Отправляйте исходное фото товара напрямую: отдельный запрос на удаление фона не требуется.

resize

Вписывает фото в точный размер холста, сохраняя исходный фон. Выберите режим вписывания или заполнения, положение кадра и заливку полей. Не расходует ИИ-кредиты.

Загрузка и обработка одним запросом

POST/v1/tools/{tool_id}/edit

Это самый простой способ: передайте imageUrl, если исходное фото уже доступно по ссылке, или отправьте локальный файл в multipart-поле image. Подходит, когда нужно применить один инструмент к одному изображению.

Выбирайте этот вариант для одного изображения и одной операции, когда загруженный исходник не нужно использовать повторно.

curl -X POST https://api.photofig.com/v1/tools/ai-shadows/edit \
  -H "Authorization: Bearer pf_live_..." \
  -F "image=@product.jpg" \
  -F "seed=128742"

Результат в том же ответе

Добавьте заголовок Prefer: wait=60, и соединение будет ожидать завершения обработки, но не дольше 60 сек. При успехе вернётся код 200 с готовой задачей или само изображение, если также передать Accept: image/png. При ошибке обработки вернётся 422 job_failed. Если время ожидания истекло, а задача ещё выполняется, вернётся 202 с объектом задачи для отслеживания: обработка продолжится, и вебхук всё равно сработает.

curl -X POST https://api.photofig.com/v1/tools/mask/edit \
  -H "X-Api-Key: pf_live_..." \
  -H "Prefer: wait=60" \
  -H "Accept: image/png" \
  -F "image_file=@product.jpg" \
  -o cutout.png

Переход с remove.bg

Базовый запрос на удаление фона переносится простой заменой URL и ключа с добавлением двух заголовков выше. X-Api-Key работает так же, как Authorization: Bearer, а multipart-поля image_file и image_url принимаются как есть. Параметры вроде size, crop и bg_color игнорируются: для размеров и фонов используйте инструмент resize или шаблон.

Сначала загрузка, потом обработка

POST/v1/uploads

Создайте сессию загрузки, чтобы отправить байты изображения напрямую в хранилище, а затем запустите обработку с полученным uploadSessionId. Лимит размера файла такой же, как при multipart-запросе, и каждая сессия используется для одной операции.

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

UPLOAD_JSON=$(curl -s -X POST https://api.photofig.com/v1/uploads \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "image/jpeg",
    "filename": "product.jpg",
    "sizeBytes": 1842031
  }')

curl -X PUT "$(echo "$UPLOAD_JSON" | jq -r '.uploadUrl')" \
  -H "Content-Type: image/jpeg" \
  --data-binary @product.jpg

curl -X POST https://api.photofig.com/v1/tools/ai-shadows/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d "{
    \"uploadSessionId\": \"$(echo "$UPLOAD_JSON" | jq -r '.uploadSessionId')\",
    \"parameters\": { \"seed\": 128742 }
  }"

Запуск обработки

POST/v1/tools/{tool_id}/edit

Отправляйте запросы на обработку с imageUrl, uploadSessionId или multipart-полем image. В ответе возвращается идентификатор задачи для проверки статуса, отмены, удаления и сопоставления событий вебхуков. Параметры, которые инструмент не использует, игнорируются.

ИИ-фон

Конечная точка ИИ-фона лучше всего работает с коротким описанием сцены в несколько слов: обстановка, поверхность, свет или настроение. Удачные примеры: тёплая дубовая столешница,минималистичная белая студия, and мягкий утренний свет на кухне.

curl -X POST https://api.photofig.com/v1/tools/ai-bg/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/product.png",
    "parameters": {
      "theme": "warm oak tabletop",
      "seed": 128742
    }
  }'

Product Shadow

curl -X POST https://api.photofig.com/v1/tools/ai-shadows/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/product.png",
    "parameters": { "seed": 128742 }
  }'

Обтравка (mask)

Инструмент mask не принимает параметров и возвращает PNG с вырезанным товаром на прозрачном фоне.

curl -X POST https://api.photofig.com/v1/tools/mask/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/product.png"
  }'

Изменение размера (resize)

Параметры width и height задают размер результата в пикселях от 100 до 4096. Режим mode принимает значения fit (вписать фото целиком, по умолчанию), fill (заполнить холст с обрезкой краёв), width или height. Параметры horizontal и vertical задают выравнивание фото, а background заполняет свободные поля: transparent, цвет #RRGGBB или объект градиента. Результат возвращается в формате PNG.

curl -X POST https://api.photofig.com/v1/tools/resize/edit \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/product.jpg",
    "parameters": {
      "width": 1000,
      "height": 1000,
      "mode": "fit",
      "background": "#ffffff"
    }
  }'

Задачи

GET/v1/jobs
GET/v1/jobs/{job_id}
POST/v1/jobs/{job_id}/cancel
DELETE/v1/jobs/{job_id}

Просматривайте список, проверяйте статус, отменяйте и удаляйте задачи API. Задачи API не отображаются в разделах «Загрузки» и «Дизайны» веб-приложения, а при удалении задачи стираются и созданные ею файлы.

Запрос GET /v1/jobs/{job_id} возвращает статус задачи. Когда она перейдёт в статус completed, скачайте изображение по ссылке resultUrl до наступления expiresAt. Проверки статуса не расходуют минутный лимит запросов, но вебхуки сообщают о готовности быстрее.

{
  "id": "api_edit_uuid",
  "tool": "ai-shadows",
  "status": "completed",
  "createdAt": "2026-07-15T10:15:00Z",
  "startedAt": "2026-07-15T10:15:04Z",
  "finishedAt": "2026-07-15T10:15:23Z",
  "statusUrl": "https://api.photofig.com/v1/jobs/api_edit_uuid",
  "resultUrl": "https://storage.example.com/signed-result-url",
  "thumbnailUrl": "https://storage.example.com/signed-thumbnail-url",
  "expiresAt": "2026-07-15T11:15:23Z",
  "error": null
}

Шаблоны

GET/v1/templates
POST/v1/templates
GET/v1/templates/{template_id}
PATCH/v1/templates/{template_id}
DELETE/v1/templates/{template_id}

Шаблон задаёт единое оформление для множества фото: удаление фона, размещение, фон и тень, поля и размеры экспорта. Шаблоны, созданные через API, открываются и редактируются в приложении PhotoFig, и наоборот. Системные шаблоны готовы к работе и доступны только для чтения.

Шаг resize обязателен. Шаг mask нужен для любого действия с обтравкой, например для замены фона или наложения тени. Шаги выполняются в фиксированном порядке. Неизвестные шаги и поля отклоняются, а значения должны укладываться в диапазоны редактора. Полный список полей приведён в схеме OpenAPI.

curl -X POST https://api.photofig.com/v1/templates \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cream catalog",
    "steps": {
      "mask": {},
      "reposition": { "horizontal": "center", "vertical": "center", "scale": 0.85 },
      "background": { "backgroundType": "solid", "color": "#f6f1ea" },
      "ai-shadows": { "opacity": 0.8 },
      "resize": { "mode": "fit", "targets": [{ "width": 2000, "height": 2000 }] }
    },
    "export": { "format": "jpg", "background": "#ffffff" }
  }'

Поле creditsPerPhoto показывает стоимость шаблона за одно фото, например один ИИ-кредит за ai-shadows.

Пакеты

POST/v1/batches
POST/v1/batches/{batch_id}/uploads
POST/v1/batches/{batch_id}/uploads/{upload_id}/complete
POST/v1/batches/{batch_id}/process
GET/v1/batches/{batch_id}
GET/v1/batches
POST/v1/batches/{batch_id}/cancel
DELETE/v1/batches/{batch_id}

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

Каждое фото загружается напрямую в хранилище: запросите загрузку, отправьте байты методом PUT на uploadUrl и подтвердите завершение загрузки.

BATCH_ID=$(curl -s -X POST https://api.photofig.com/v1/batches \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring arrivals" }' | jq -r '.id')

# For each photo: ask for an upload, PUT the bytes, complete it.
UPLOAD=$(curl -s -X POST "https://api.photofig.com/v1/batches/$BATCH_ID/uploads" \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "filename": "boots.jpg", "contentType": "image/jpeg", "sizeBytes": 1842031, "position": 0 }')
curl -X PUT "$(echo "$UPLOAD" | jq -r '.uploadUrl')" \
  -H "Content-Type: image/jpeg" --data-binary @boots.jpg
curl -X POST "https://api.photofig.com/v1/batches/$BATCH_ID/uploads/$(echo "$UPLOAD" | jq -r '.uploadId')/complete" \
  -H "Authorization: Bearer pf_live_..."

curl -X POST "https://api.photofig.com/v1/batches/$BATCH_ID/process" \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "TEMPLATE_ID" }'

Уведомление о завершении пакета

Один раз зарегистрируйте вебхук на событие batch.completed вместо периодического опроса. PhotoFig вызовет его по завершении каждого пакета и передаст идентификатор пакета и число успешных и неуспешных фото.

curl -X POST https://api.photofig.com/v1/webhooks \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/photofig/webhooks",
    "events": ["batch.completed"]
  }'
{
  "event": "batch.completed",
  "eventId": "uuid",
  "createdAt": "2026-10-06T12:00:00Z",
  "data": {
    "batchId": "uuid",
    "status": "completed",
    "totalItems": 12,
    "completedItems": 12,
    "failedItems": 0
  }
}

При получении события batch.completed запросите данные пакета. У каждого готового фото есть ссылка на превью размером до 1024 пикс. Каждое успешно обработанное фото расходует одну API-обтравку независимо от состава шаблона, а ИИ-шаги дополнительно списывают ИИ-кредиты.

{
  "id": "uuid",
  "name": "Spring arrivals",
  "status": "completed",
  "templateName": "Cream catalog",
  "totalItems": 2,
  "completedItems": 2,
  "failedItems": 0,
  "resultsAvailableUntil": "2026-10-20T12:00:00Z",
  "items": [
    {
      "id": "uuid",
      "position": 0,
      "filename": "boots.jpg",
      "status": "completed",
      "width": 3024,
      "height": 4032,
      "preview": {
        "url": "https://...",
        "width": 1024,
        "height": 1024
      }
    }
  ]
}

Скачивание результатов

GET/v1/batches/{batch_id}/items/{item_id}/download
GET/v1/batches/{batch_id}/download-url

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

Публичная ссылка на результаты

POST/v1/batches/{batch_id}/share
GET/v1/batches/{batch_id}/share
DELETE/v1/batches/{batch_id}/share

Публичная ссылка открывает страницу с превью «до» и «после» и кнопкой скачивания ZIP без входа в аккаунт. У пакета одна такая ссылка: повторный запрос вернёт её же, а отзыв мгновенно закроет доступ. Скачивания со страницы ничего дополнительно не стоят, и ссылка действует до времени availableUntil. Публичные ссылки доступны на платных тарифах.

curl -X POST "https://api.photofig.com/v1/batches/$BATCH_ID/share" \
  -H "Authorization: Bearer pf_live_..."
{
  "url": "https://photofig.com/share/TOKEN",
  "availableUntil": "2026-10-20T12:00:00Z",
  "createdAt": "2026-10-06T12:05:00Z",
  "downloadCount": 0
}

Вебхуки

Вебхуки позволяют PhotoFig уведомлять ваш сервер, когда задача API завершена, завершилась ошибкой или отменена, а также когда готов пакет, чтобы вашему бэкенду не приходилось опрашивать статус вручную. Зарегистрируйте публичный HTTPS-адрес. Конечная точка получает события по задачам, созданным с API-ключами её владельца, и по всем пакетам этого владельца в рабочем пространстве - как из приложения, так и через API.

GET/v1/webhooks
POST/v1/webhooks
GET/v1/webhooks/{webhook_id}
PATCH/v1/webhooks/{webhook_id}
DELETE/v1/webhooks/{webhook_id}
POST/v1/webhooks/{webhook_id}/test

Поддерживаемые события: webhook.test,job.completed,job.failed,job.cancelled, и batch.completed. События задач содержат идентификатор задачи, возвращённый при запуске обработки, а batch.completed передаёт идентификатор пакета.

{
  "event": "job.completed",
  "eventId": "uuid",
  "createdAt": "2026-07-15T10:15:23Z",
  "data": {
    "id": "api_edit_uuid",
    "tool": "ai-shadows",
    "status": "completed",
    "resultUrl": "https://storage.example.com/signed-result-url",
    "thumbnailUrl": "https://storage.example.com/signed-thumbnail-url",
    "expiresAt": "2026-07-15T11:15:23Z"
  }
}

Проверка подлинности каждого запроса

Каждый запрос содержит заголовки PhotoFig-Webhook-Timestamp и PhotoFig-Webhook-Signature. Вычислите HMAC-SHA256 от строки из метки времени, точки и необработанного тела запроса с использованием секрета конечной точки и сравните хеш со значением после v1=. Отклоняйте метки времени старше нескольких минут. Секрет показывается только при создании конечной точки.

import crypto from 'node:crypto';

// rawBody is the request body exactly as received, before JSON parsing.
export function verifyPhotoFigWebhook(headers, rawBody, secret) {
  const timestamp = headers['photofig-webhook-timestamp'];
  const signature = headers['photofig-webhook-signature'] ?? '';
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = 'v1=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return signature.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Ответьте любым кодом 2xx в течение 10 секунд. При любом другом ответе доставка повторится через 1 минуту, 5 минут, 30 минут, 2 часа и 12 часов. Заголовок PhotoFig-Webhook-Id сохраняется при повторах - используйте его для защиты от дублирования. Ссылки на скачивание в теле уведомления подписываются заново для каждой попытки и перестают работать по истечении срока хранения результата.

Ошибки

Ответы с ошибками содержат стабильный машиночитаемый код и понятное описание. В логике клиента опирайтесь именно на поле кода.

{
  "code": "invalid_request",
  "message": "imageUrl or uploadSessionId is required"
}

Основные коды ошибок

invalid_request
Отсутствует обязательный параметр или передано недопустимое значение; подробности указаны в сообщении.
api_key_not_allowed
API-ключ использован на маршруте за пределами публичного API.
api_access_disabled
Тариф рабочего пространства не включает доступ к API.
insufficient_funds
Недостаточно ИИ-кредитов для этого инструмента.
api_cutouts_exhausted
Лимит API-обтравок на текущий расчётный период исчерпан; он обновится в начале нового периода, либо подключите API-блок.
rate_limit_exceeded
Исчерпан минутный лимит запросов; повторите попытку через время из Retry-After.
too_many_jobs
В очереди или в работе слишком много задач; повторите запрос, когда завершатся предыдущие.
tool_unavailable
Обработчики инструмента временно недоступны; повторите запрос чуть позже.
webhook_limit_reached
Владелец ключа достиг лимита конечных точек вебхуков в этом рабочем пространстве.

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

Завершённые задачи API остаются видны через GET /v1/jobs и GET /v1/jobs/{job_id}. Пока файлы доступны, ответ со статусом содержит подписанные ссылки resultUrl и thumbnailUrl.

Файлы API хранятся отдельно от загрузок и дизайнов веб-приложения и не отображаются в библиотеке.

Записи о задачах API, а также исходные файлы, результаты и миниатюры хранятся 24 часа после перехода задачи в статус completed, failed или cancelled. В поле expiresAt указано время планового удаления.

Вызывайте DELETE /v1/jobs/{job_id} после скачивания результатов, которые больше не нужны. Этот запрос по возможности отменяет незавершённую обработку и сразу удаляет запись о задаче вместе с её файлами, не дожидаясь автоочистки.

Блог

Руководства на английском языке Все руководства