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

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

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

Обзор

Чтобы запускать сервисы Problembo прямо из ChatGPT, Claude, Cursor или другого ИИ-ассистента, подключите MCP-сервер.

Начало работы

Создание токена

Перейдите в Личный кабинет
Нажмите кнопку "Создать токен"
Введите описательное название для вашего токена
Выберите срок действия (или установите "Бессрочно")
Нажмите "Создать" для генерации токена
Важно: Скопируйте токен немедленно - вы больше не сможете его увидеть!

Безопасность токенов

Никогда не передавайте токены другим лицам
Не добавляйте токены в системы контроля версий (Git, SVN и т.д.)
Используйте переменные окружения для хранения токенов в приложениях
Регулярно обновляйте токены для повышения безопасности
Отзывайте скомпрометированные токены немедленно

Использование API

Базовый URL

https://problembo.com/apis/v1/client

Эндпоинты

POST /apis/v1/client/image-gen/tasks - Создание задачи генерации изображений
GET /apis/v1/client/tasks/{taskId} - Получение статуса и результата задачи
GET /apis/v1/client/operations/{taskId} - Получение статуса операции и результата задачи, созданной через POST /apis/v1/client/{contractId}/tasks
POST /apis/v1/client/{contractId}/quote - Цена задачи без её создания; тело то же, что у POST /apis/v1/client/{contractId}/tasks
GET /apis/v1/client/api-contracts/image-gen - Получение актуального контракта API генерации изображений
POST /apis/v1/client/prompt-enhance/image - Синхронное улучшение промпта изображения
POST /apis/v1/client/prompt-enhance/video - Синхронное улучшение промптов видео
GET /apis/v1/client/api-contracts/prompt-enhance-image - Контракт улучшения промпта изображения
GET /apis/v1/client/api-contracts/prompt-enhance-video - Контракт улучшения промптов видео
POST /apis/v1/client/files/upload-url-for-src - Получение presigned URL для загрузки source-файла по API token
POST /apis/v1/client/files/upload-complete - Подтверждение single-part загрузки source-файла по API token
POST /apis/v1/client/files/upload-multipart-complete - Подтверждение multipart загрузки source-файла по API token
POST /apis/v1/client/files/multipart-plan - Получение multipart plan для source-файла по API token

Эндпоинты сервисов

Каждый сервис принимает POST /apis/v1/client/{contractId}/tasks и возвращает taskId. Публичный контракт GET /apis/v1/client/api-contracts/{contractId} описывает поля запроса, аутентификацию и ответ сервиса. Для получения контракта токен не нужен.

Сервис	`contractId`
ИИ-редактор фото, расширение изображений	`image-edit`
ИИ-генератор изображений, генератор аниме	`image-gen`
ИИ-генератор видео	`video-gen`
Увеличение и улучшение фото	`image-upscale`
Улучшение видео: апскейл, FPS, стабилизация	`video-enhance`
Замена лица	`face-swap`
Удаление фона	`background-removal`
Удаление объектов	`object-removal`
Виртуальная примерка	`virtual-try-on`
Озвучка текста	`tts`
Генерация музыки	`music-generation`
Обучение модели изображений (LoRA)	`train-image`

⚠️ Сервис замены лица (face-swap) закрывается: на сайте он уже не принимает задачи, а API может быть отключено после 10 ноября 2026 года. Для замены лица по фото-референсу используйте ИИ-редактор фото (контракт image-edit).

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

Включите ваш API токен в заголовок Authorization каждого запроса:

Authorization: Bearer ВАШ_API_ТОКЕН

Структура запроса

Новые service-specific endpoints принимают payload сервиса напрямую. Для генерации изображений отправьте body, совместимый с PrImageGenRequest:

{
  "modelId": "waifu-studio-2.6",
  "prompt": "beautiful landscape",
  "imageCount": 1
}

Получение примеров JSON

💡 Важно: Примеры JSON для конкретных сервисов можно получить прямо в интерфейсе каждого сервиса через кнопку "Json for API". Это самый простой способ узнать правильную структуру запроса для нужного вам сервиса.

Работа с файлами

Если вашей задаче нужен входной файл, см. Самостоятельная загрузка файлов — там описаны url, fileId, presigned upload flow по API token и multipart-загрузка.

Регион хранилища

По умолчанию Problembo выбирает хранилище для результатов задачи по IP-адресу клиента. Чтобы задать его явно, добавьте необязательное поле storageRegion на верхний уровень body любого запроса POST /apis/v1/client/{contractId}/tasks:

Значение	Хранилище
`auto`	Выбирается по IP клиента (как без поля)
`ru`	Хранилище в России
`global`	Хранилище за пределами России

{
  "modelId": "waifu-studio-2.6",
  "prompt": "beautiful landscape",
  "imageCount": 1,
  "storageRegion": "global"
}

То же поле принимает POST /apis/v1/client/files/upload-url-for-src для входных файлов. Любое другое значение возвращает 400 с ключом PARSE_TASK. Используйте global, если ваши запросы идут через VPN, прокси или облачную сеть, а скачивание результатов зависает или идёт медленно.

Улучшение промптов

Для синхронного улучшения промптов изображений и видео см. Улучшение промптов через API. Руководство описывает оба payload, входные изображения, цены, ответы и ошибки.

Примеры запросов

Создание задачи генерации изображений (POST)

Запрос:

curl -X POST https://problembo.com/apis/v1/client/image-gen/tasks \
  -H "Authorization: Bearer ВАШ_API_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "waifu-studio-2.6",
    "prompt": "1girl, beautiful anime character",
    "negativePrompt": "nsfw, low quality",
    "imageCount": 1,
    "aspectRatio": "VERTICAL_16_9"
  }'

Допустимые значения aspectRatio: SQUARE, VERTICAL, HORIZONTAL, VERTICAL_16_9 и HORIZONTAL_16_9. Допустимые значения resolution: 1K, 2K и 4K; передавайте разрешение только тогда, когда оно указано для выбранной модели. Запросите GET /api/v1/image-gen/catalog?locale=ru и используйте поля supportedAspectRatios и supportedResolutions модели. При неверном или неподдерживаемом значении API вернет 400, не создавая и не тарифицируя задачу.

Ответ (успешное создание):

{
  "taskId": "00331b93-31bd-4e33-b28c-cc46793a911f"
}

Получение результата (GET)

Запрос:

curl -X GET https://problembo.com/apis/v1/client/tasks/00331b93-31bd-4e33-b28c-cc46793a911f \
  -H "Authorization: Bearer ВАШ_API_ТОКЕН"

Ответ (задача в процессе):

{
  "taskId": "00331b93-31bd-4e33-b28c-cc46793a911f",
  "status": "SEND",
  "ready": false
}

Ответ (задача завершена успешно):

{
  "taskId": "00331b93-31bd-4e33-b28c-cc46793a911f",
  "status": "END_SUCCESS",
  "ready": true,
  "completedAt": "2025-11-04T07:14:33Z",
  "result": {
    "taskResult": [
      {
        "origFilename": "problembo-result-20251104071432.jpg",
        "url": "https://prbo.gateway.storjshare.io/910e1b85-4677-49d4-abd3-41218733ab60.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&..."
      }
    ]
  }
}

Ответ (ошибка при выполнении):

{
  "taskId": "00331b93-31bd-4e33-b28c-cc46793a911f",
  "status": "END_INFO",
  "ready": true,
  "error": {
    "key": "SD_PROMPT_NOT_SAFE"
  }
}

Статусы задач

GET /apis/v1/client/tasks/{taskId} возвращает один из следующих статусов:

CREATE - Задача создана и ожидает отправки на обработку
SEND - Задача обрабатывается
END_SUCCESS - Задача успешно завершена
END_INFO - Задача завершена с ожидаемой ошибкой, например отказом модерации или некорректным входным файлом; причина в error.key
END_ERR - Задача завершена с непредвиденной ошибкой
END_TIMEOUT - Превышено время ожидания выполнения
CANCEL - Задача отменена

Поле ready показывает, завершена ли задача (независимо от результата). Пока задача выполняется, в ответе может быть поле progress.

GET /apis/v1/client/operations/{taskId} использует свои статусы: PENDING, RUNNING, SUCCEEDED, FAILED, TIMED_OUT, CANCELLED. Результат возвращается при SUCCEEDED, ошибка — в error.key. Объект billing показывает стоимость задачи: state — NONE (ещё ничего не зарезервировано), RESERVED (цена удерживается, пока задача выполняется), CHARGED или REFUNDED, а amountUsd — удержанная, списанная или возвращённая сумма.

Цена до запуска

POST /apis/v1/client/{contractId}/quote принимает то же тело, что и создание задачи, и возвращает цену, не создавая и не оплачивая задачу:

{
  "priceUsd": "0.050000",
  "estimatedSeconds": 25,
  "funds": {
    "checked": true,
    "canSubmit": true,
    "spendableBalanceUsd": "53.142110",
    "coveredRuns": 1062
  }
}

priceUsd — сумма, которую создание задачи зарезервирует на платном балансе с учётом ваших тарифов. Если баланса не хватает, funds.canSubmit равно false, а funds.shortfallUsd — сколько не хватает. Публичные URL входных файлов скачиваются для расчёта цены, как при создании задачи.

Полный workflow

Типичный сценарий работы с API:

# 1. Создать задачу генерации изображений
TASK_ID=$(curl -X POST https://problembo.com/apis/v1/client/image-gen/tasks \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modelId":"waifu-studio-2.6","prompt":"beautiful landscape","imageCount":1}' \
  | jq -r '.taskId')

echo "Task ID: $TASK_ID"

# 2. Опросить статус (polling)
while true; do
  RESPONSE=$(curl -s https://problembo.com/apis/v1/client/tasks/$TASK_ID \
    -H "Authorization: Bearer $API_TOKEN")

  STATUS=$(echo $RESPONSE | jq -r '.status')
  READY=$(echo $RESPONSE | jq -r '.ready')

  echo "Status: $STATUS"

  if [ "$READY" = "true" ]; then
    if [ "$STATUS" = "END_SUCCESS" ]; then
      echo "Task completed successfully!"
      echo $RESPONSE | jq '.result'
    else
      echo "Task failed!"
      echo $RESPONSE | jq '.error'
    fi
    break
  fi

  sleep 5
done

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

Переименование токенов

Давайте токенам осмысленные имена для идентификации их назначения:

продакшен-сервер
разработка-тестирование
мобильное-приложение-v2

Настройки срока действия

Выбирайте подходящий срок действия в зависимости от вашего случая:

30 дней: Тестирование и разработка
90 дней: Краткосрочные проекты
1 год: Долгосрочные приложения
Бессрочно: Критическая инфраструктура (обновляйте вручную)

Статус токена

Токены могут иметь следующие статусы:

Активен: Токен действителен и может использоваться
Отключён: Временно отключен, можно снова включить
Истёк: Прошел срок действия, не может использоваться
Отозван: Навсегда аннулирован

Ограничения частоты запросов (Rate Limiting)

API использует распределенное ограничение частоты запросов для защиты от перегрузки:

Лимиты по эндпоинтам

Опрос статуса (GET /apis/v1/client/tasks/{id}, GET /apis/v1/client/operations/{id}): 120 запросов в минуту на API-токен
Описания API-контрактов (/apis/v1/client/api-contracts/**): 300 запросов в минуту на IP
Остальные эндпоинты /apis/v1/client/** (отправка задач, загрузка файлов, улучшение промптов): общий лимит 60 запросов в минуту на API-токен и независимый лимит 120 запросов в минуту на IP

Ответ при превышении лимита

При превышении лимита вы получите HTTP статус 429 Too Many Requests:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "rate_limit_exceeded"
}

Заголовок Retry-After указывает, через сколько секунд можно повторить запрос.

Коды ошибок

HTTP статусы

200 OK - Запрос успешно обработан
400 Bad Request - Некорректный запрос или ошибка валидации
401 Unauthorized - Невалидный или отсутствующий токен
403 Forbidden - Выбранная модель недоступна вашему аккаунту
404 Not Found - Задача не найдена
429 Too Many Requests - Превышен лимит частоты запросов
500 Internal Server Error - Внутренняя ошибка сервера
503 Service Unavailable - Сервис временно перегружен, повторите запрос позже

Ошибки 400, 403 и 503 при отправке задачи возвращаются в стандартном Client API envelope: машиночитаемый код ошибки — в поле errorKey, текст для пользователя, если он есть, — в message.

Коды ошибок задач (error.key)

При ошибке выполнения задачи в ответе будет объект error, где key — один из этих кодов:

Ошибки доступа и биллинга

BILLING_ACCESS_DENIED - Недостаточно средств на балансе
IP_BILLING_ACCESS_DENIED - IP-адрес заблокирован
IP_BAN - IP-адрес забанен
ANONYMOUS_USER - Требуется аутентификация
NOT_PAID_USER - Функция доступна только платным пользователям

Ошибки валидации

PARSE_TASK - Ошибка парсинга JSON запроса
INVALID_INPUT_FILE - Некорректный входной файл
SD_EMPTY_PROMPT - Пустой промпт
SD_PROMPT_TOO_LONG - Промпт слишком длинный
SD_NO_LATIN_PROMPT - Промпт должен быть на латинице
SD_PROMPT_NOT_SAFE - Промпт содержит небезопасный контент

Лимиты

MAX_PARALLEL_TASKS_PER_IP - Превышен лимит параллельных задач
MAX_TASKS_PER_USER - Превышен лимит задач пользователя

Системные ошибки

SERVICE_DISABLED - Сервис временно отключен
MAINTENANCE - Технические работы
BUSY - Система перегружена
TIMEOUT - Превышено время выполнения задачи
NOT_FOUND - Задача не найдена
UNKNOWN_ERROR - Неизвестная ошибка

Лучшие практики

Используйте отдельные токены для разных приложений или окружений
Устанавливайте сроки действия, подходящие для вашего случая
Реализуйте polling с разумными интервалами (рекомендуется 3-5 секунд)
Обрабатывайте все возможные статусы задач в вашем коде
Реализуйте логику повторных попыток с экспоненциальной задержкой при rate limiting
Проверяйте баланс перед отправкой большого количества задач
Кешируйте результаты по возможности, чтобы не запрашивать их повторно
Обрабатывайте ошибки грамотно - логируйте error.key для отладки
Отслеживайте использование токенов в разделе статистики

Устранение неполадок

Токен не работает

Убедитесь, что токен активен и не истёк
Проверьте правильность формата заголовка: Authorization: Bearer TOKEN
Убедитесь, что на аккаунте достаточно кредитов
Проверьте, что токен начинается с префикса pbo_pat_

Ошибка 401 Unauthorized

Возможные причины:

Токен недействителен, истек или отозван
Неправильный формат заголовка Authorization
Лишние пробелы или символы в токене
Токен не скопирован полностью

Решение:

# Правильно
curl -H "Authorization: Bearer pbo_pat_..."

# Неправильно
curl -H "Authorization: pbo_pat_..."  # отсутствует "Bearer"
curl -H "Authorization: Bearer  pbo_pat_..."  # двойной пробел

Ошибка 429 Too Many Requests

Вы превысили лимит частоты запросов.

Решение:

Дождитесь времени, указанного в заголовке Retry-After
Реализуйте экспоненциальную задержку между повторными попытками
Оптимизируйте частоту опроса статуса задачи
Используйте батчинг для массовых операций

Ошибка BILLING_ACCESS_DENIED

Недостаточно средств на балансе.

Решение:

Проверьте баланс в личном кабинете
Пополните баланс
Убедитесь, что выбран правильный тарифный план

Ошибка SD_PROMPT_NOT_SAFE

Промпт содержит небезопасный или запрещенный контент.

Решение:

Проверьте промпт на наличие запрещенных слов
Используйте более нейтральные формулировки
Обратитесь в поддержку, если считаете, что промпт корректен

Задача долго не завершается

Задача выполняется дольше обычного.

Решение:

Продолжайте опрашивать статус - некоторые задачи могут выполняться до 5-10 минут
Проверьте статус системы на странице мониторинга
Если задача не завершается более 15 минут, обратитесь в поддержку с taskId

Скачивание результата зависает или обрывается по таймауту

Задача в статусе END_SUCCESS, но скачивание url результата останавливается на середине или обрывается по таймауту. Обычно это проблема сетевого маршрута между вашим клиентом и выбранным хранилищем, например когда трафик идёт через VPN, прокси или облачную сеть.

Решение:

Отправляйте новые задачи с "storageRegion": "global" (см. )
Передавайте то же поле при загрузке входных файлов через upload-url-for-src
Если скачивание всё равно не работает, обратитесь в поддержку с taskId

Примеры на других языках

JavaScript/TypeScript

const API_TOKEN = 'pbo_pat_ваш_токен'
const SUBMIT_URL = 'https://problembo.com/apis/v1/client/image-gen/tasks'
const TASKS_URL = 'https://problembo.com/apis/v1/client/tasks'

const headers = {
  Authorization: `Bearer ${API_TOKEN}`,
  'Content-Type': 'application/json',
}

// Создание задачи
async function createTask() {
  const response = await fetch(SUBMIT_URL, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      modelId: 'waifu-studio-2.6',
      prompt: 'beautiful landscape',
      imageCount: 1,
    }),
  })

  const data = await response.json()
  return data.taskId
}

// Опрос статуса
async function waitForTask(taskId: string) {
  while (true) {
    const response = await fetch(`${TASKS_URL}/${taskId}`, { headers })
    const data = await response.json()

    console.log(`Status: ${data.status}`)

    if (data.ready) {
      return data
    }

    await new Promise(resolve => setTimeout(resolve, 5000))
  }
}

// Использование
const taskId = await createTask()
console.log(`Task created: ${taskId}`)

const result = await waitForTask(taskId)
if (result.status === 'END_SUCCESS') {
  console.log('Success!', result.result)
} else {
  console.log('Failed!', result.error)
}

Поддержка

Нужна помощь? Свяжитесь с нашей службой поддержки:

Email: support@problembo.com
Telegram: @problembo_support

Последнее обновление: 19 октября 2026

Главная

Документация Problembo: руководства, инструкции и практические материалы по редактированию изображений, face swap, обучению моделей и другим AI-сервисам.

Самостоятельная загрузка файлов

Как загрузить исходный файл в Problembo File Store и использовать его в API задачах через `fileId` или прямой `url`.