Синхронный и асинхронный режимы

Konergy API поддерживает два режима получения результатов: синхронный (ожидание) и асинхронный (polling).

Синхронный режим (рекомендуется)

Добавьте заголовок Prefer: wait=N к запросу. Сервер будет держать соединение открытым до N секунд (максимум 45) и вернёт результат, как только обработка завершится.

bash

curl -X POST https://platform-api.konergy.ru/api/jobs/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=30" \
  -F "image=@photo.jpg"

# → 200 OK + Preference-Applied: wait
# {
#   "jobId": "...",
#   "status": "succeeded",
#   "result": { ... },
#   "error": null
# }

Если обработка не завершится за указанное время, сервер вернёт 202 Accepted с jobId. Вы можете продолжить ожидание через polling.

Асинхронный режим (polling)

Без заголовка Prefer сервер сразу возвращает 202 Accepted. Опрашивайте GET /api/jobs/{id} для получения результата.

bash

# Шаг 1: Отправка
curl -X POST https://platform-api.konergy.ru/api/jobs/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "image=@photo.jpg"
# → 202 Accepted { "jobId": "abc-123" }

# Шаг 2: Polling
curl https://platform-api.konergy.ru/api/jobs/abc-123 \
  -H "Authorization: Bearer $API_KEY"
# Повторять каждые 1-2 секунды, пока status != "succeeded" или "failed"

Когда что использовать

Сценарий	Режим	Почему
Простая интеграция, скрипты	`Prefer: wait=30`	Один запрос — один ответ, проще всего
SDK и библиотеки	`Prefer: wait=30`	Блокирующий вызов, чистый API
Массовая обработка (батчи)	Async + polling	Параллельная отправка без ожидания
Webhook-интеграция	Async	Результат приходит в callback
UI с прогресс-баром	Async + polling	Промежуточные статусы (queued → running)

Примеры на Python

python

import requests
from uuid import uuid4

API_KEY = "sk_konergy_..."

# Синхронный режим — одна строка
response = requests.post(
    "https://platform-api.konergy.ru/api/jobs/process",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": str(uuid4()),
        "Prefer": "wait=30",
    },
    files={"image": open("photo.jpg", "rb")},
)

if response.status_code == 200:
    result = response.json()["result"]
    print("Готово:", result)
elif response.status_code == 202:
    job_id = response.json()["jobId"]
    print("Обработка не завершилась, polling:", job_id)

Заголовки ответа

Заголовок	Значение	Когда
`Preference-Applied`	`wait`	Только если сервер применил синхронное ожидание
`X-Quota-Global-Remaining`	число	Всегда
`X-Quota-Period-End`	ISO 8601	Всегда

Обработка ошибок API Безопасность

Синхронный и асинхронный режимы

Konergy API поддерживает два режима получения результатов: синхронный (ожидание) и асинхронный (polling).

Синхронный режим (рекомендуется)

bash

curl -X POST https://platform-api.konergy.ru/api/jobs/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=30" \
  -F "image=@photo.jpg"

# → 200 OK + Preference-Applied: wait
# {
#   "jobId": "...",
#   "status": "succeeded",
#   "result": { ... },
#   "error": null
# }

Асинхронный режим (polling)

Без заголовка Prefer сервер сразу возвращает 202 Accepted. Опрашивайте GET /api/jobs/{id} для получения результата.

bash

# Шаг 1: Отправка
curl -X POST https://platform-api.konergy.ru/api/jobs/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "image=@photo.jpg"
# → 202 Accepted { "jobId": "abc-123" }

# Шаг 2: Polling
curl https://platform-api.konergy.ru/api/jobs/abc-123 \
  -H "Authorization: Bearer $API_KEY"
# Повторять каждые 1-2 секунды, пока status != "succeeded" или "failed"

Когда что использовать

Сценарий	Режим	Почему
Простая интеграция, скрипты	`Prefer: wait=30`	Один запрос — один ответ, проще всего
SDK и библиотеки	`Prefer: wait=30`	Блокирующий вызов, чистый API
Массовая обработка (батчи)	Async + polling	Параллельная отправка без ожидания
Webhook-интеграция	Async	Результат приходит в callback
UI с прогресс-баром	Async + polling	Промежуточные статусы (queued → running)

Примеры на Python

python

import requests
from uuid import uuid4

API_KEY = "sk_konergy_..."

# Синхронный режим — одна строка
response = requests.post(
    "https://platform-api.konergy.ru/api/jobs/process",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": str(uuid4()),
        "Prefer": "wait=30",
    },
    files={"image": open("photo.jpg", "rb")},
)

if response.status_code == 200:
    result = response.json()["result"]
    print("Готово:", result)
elif response.status_code == 202:
    job_id = response.json()["jobId"]
    print("Обработка не завершилась, polling:", job_id)

Заголовки ответа

Заголовок	Значение	Когда
`Preference-Applied`	`wait`	Только если сервер применил синхронное ожидание
`X-Quota-Global-Remaining`	число	Всегда
`X-Quota-Period-End`	ISO 8601	Всегда