Документация API
PhotoFig API
Ставьте в очередь обработку и изменение размеров фото товаров, запускайте шаблоны для целых пакетов, отслеживайте прогресс и получайте подписанные события вебхуков с помощью API-ключей.
Нужна машиночитаемая схема? Скачать OpenAPI JSON.
На этой странице
Быстрый старт
Создайте API-ключ в разделе Настройки. Замените YOUR_API_KEY ниже и сохраните тестовое фото под именем product.jpg.
Отправьте фото
Загрузите фото, чтобы добавить тень товара. В ответе придут идентификатор задачи и ссылка statusUrl.
curl https://api.photofig.com/v1/tools/ai-shadows/edit \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "image=@product.jpg"Проверьте статус задачи
Подставьте полученный statusUrl вместо STATUS_URL. Пока статус равен queued или processing, подождите перед следующей проверкой.
curl "STATUS_URL" \ -H "Authorization: Bearer YOUR_API_KEY"Скачайте результат
Когда статус сменится на 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. Повторный запрос с тем же ключом вернёт исходный ответ вместо запуска дублирующей задачи, поэтому генерируйте новый ключ для каждой отдельной операции.
Аккаунт
/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"
]
}Инструменты
/v1/tools/v1/tools/{tool_id}Каждый инструмент принимает обычное фото товара через imageUrl, uploadSessionId или multipart-загрузку. Вызывать mask заранее не нужно: ai-bg и ai-shadows сами удаляют фон.
mask
Удаляет фон и возвращает PNG с вырезанным товаром на прозрачном фоне. Используйте его, когда изолированный товар нужен для собственной вёрстки или публикации на маркетплейсе.
ai-shadows
Добавляет реалистичную тень товара и возвращает изображение, готовое к размещению на чистом фоне. Лучше всего работает на кадрах, где товар хорошо виден и не перекрыт пёстрым окружением.
ai-bg
Генерирует новый фон для товара по короткому описанию сцены, например тёплая дубовая столешница или минималистичная белая студия. Отправляйте исходное фото товара напрямую: отдельный запрос на удаление фона не требуется.

resize
Вписывает фото в точный размер холста, сохраняя исходный фон. Выберите режим вписывания или заполнения, положение кадра и заливку полей. Не расходует ИИ-кредиты.
Загрузка и обработка одним запросом
/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 или шаблон.
Сначала загрузка, потом обработка
/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 }
}"Запуск обработки
/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"
}
}'Задачи
/v1/jobs/v1/jobs/{job_id}/v1/jobs/{job_id}/cancel/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
}Шаблоны
/v1/templates/v1/templates/v1/templates/{template_id}/v1/templates/{template_id}/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.
Пакеты
/v1/batches/v1/batches/{batch_id}/uploads/v1/batches/{batch_id}/uploads/{upload_id}/complete/v1/batches/{batch_id}/process/v1/batches/{batch_id}/v1/batches/v1/batches/{batch_id}/cancel/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
}
}
]
}Скачивание результатов
/v1/batches/{batch_id}/items/{item_id}/download/v1/batches/{batch_id}/download-urlСкачивайте каждый полноразмерный результат в формате экспорта шаблона или весь пакет целиком одним ZIP-архивом. Скачивания уже включены в стоимость API-обтравки фотографии, сколько бы раз вы их ни запрашивали.
Публичная ссылка на результаты
/v1/batches/{batch_id}/share/v1/batches/{batch_id}/share/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.
/v1/webhooks/v1/webhooks/v1/webhooks/{webhook_id}/v1/webhooks/{webhook_id}/v1/webhooks/{webhook_id}/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} после скачивания результатов, которые больше не нужны. Этот запрос по возможности отменяет незавершённую обработку и сразу удаляет запись о задаче вместе с её файлами, не дожидаясь автоочистки.