Очередь - Sunra.ai

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

Конечные точки очереди

Вы можете получить доступ ко всем функциям очереди через следующие конечные точки:

Конечная точка	Метод	Описание
api.sunra.ai/v1/queue/{идентификатор-модели}	POST	Добавляет запрос в очередь
api.sunra.ai/v1/queue/requests/{идентификатор-запроса}/status	GET	Получает статус запроса
api.sunra.ai/v1/queue/requests/{идентификатор-запроса}/status/stream	GET	Потоковая передача статуса до завершения
api.sunra.ai/v1/queue/requests/{идентификатор-запроса}	GET	Получает ответ на запрос
api.sunra.ai/v1/queue/requests/{идентификатор-запроса}/cancel	PUT	Отменяет запрос

Например, чтобы отправить запрос с помощью curl и добавить его в очередь:

curl -X POST \
  https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "Приморский городок в стиле студии Ghibli с разноцветными домами, развевающимся бельем и кошками, спящими на подоконниках."}'

Вот пример ответа, включающий request_id:

{
  "request_id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/cancel"
}

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

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

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

Использование конечной точки

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status

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

Когда ваш запрос находится в очереди, вы получите ответ, подобный этому:

{
  "status": "IN_QUEUE",
  "metrics": {},
  "queue_position": 0,
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/cancel"
}

Возможные статусы

Ваш запрос может находиться в одном из трех состояний:

IN_QUEUE: указывает, что запрос ожидает обработки.
- queue_position: показывает ваше место в очереди.
- response_url: URL-адрес для получения ответа после завершения обработки.
IN_PROGRESS: запрос в настоящее время обрабатывается.
- logs: подробные журналы (если включены), показывающие этапы обработки.
- response_url: где будет доступен окончательный ответ.
COMPLETED: обработка завершена.
- logs: журналы с подробным описанием всего процесса.
- response_url: прямая ссылка на ваш готовый ответ.

Включение журналов

Журналы предоставляют информацию об обработке запросов. По умолчанию они отключены, но их можно включить с помощью параметра запроса:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1

Каждая запись журнала включает:

message: описание события.
level: серьезность (например, INFO, ERROR).
source: источник журнала.
timestamp: время создания журнала.

Мониторинг в реальном времени

Для непрерывного обновления используйте потоковую конечную точку:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status/stream

Это обеспечивает обновление статуса в реальном времени в формате text/event-stream до завершения запроса.

Webhooks

Если вы предпочитаете получать уведомления вместо опроса, передайте параметр запроса webhook при отправке запроса. Sunra отправит окончательный результат POST-запросом на этот URL, как только запрос достигнет конечного состояния, поэтому вам не нужно держать соединение открытым или планировать опрос.

Включение Webhooks

Добавьте URL-кодированный параметр запроса webhook к эндпоинту отправки:

curl -X POST \
  "https://api.sunra.ai/v1/queue/black-forest-labs/flux-1.1-pro/text-to-image?webhook=https%3A%2F%2Fexample.com%2Fsunra-webhook" \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "Приморский городок в стиле Studio Ghibli с разноцветными домами, развевающимся бельём и кошками, спящими на подоконниках."}'

URL-кодируйте URL webhook (например, https%3A%2F%2F...) и убедитесь, что Sunra может до него достучаться; настоятельно рекомендуется использовать HTTPS. Ответ на отправку остаётся неизменным — вы по-прежнему получаете request_id и те же URL для статуса/отмены/ответа.

Когда срабатывает Webhook

Sunra вызывает ваш webhook только при конечных событиях:

succeeded — запрос завершён, и вывод включён в полезную нагрузку.
failed — запрос завершился с ошибкой, и детали ошибки включены в полезную нагрузку.

Промежуточные состояния (IN_QUEUE, IN_PROGRESS) не вызывают webhook. Если вам также нужны обновления прогресса, используйте webhook вместе с эндпоинтами стриминга или опроса, описанными выше.

Формат запроса

Sunra отправляет POST-запрос на ваш URL webhook со следующими заголовками:

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Sunra-AI-Webhook/1.0`

Ваш эндпоинт должен ответить кодом статуса 2xx в течение 5 секунд. Подтвердите быстро и перенесите тяжёлую работу в фоновое задание — медленные ответы считаются неудачными и вызывают повторные попытки.

Полезная нагрузка

Успешное событие:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "succeeded",
  "input": {
    "prompt": "Приморский городок в стиле Studio Ghibli..."
  },
  "output": {
    "images": [
      { "url": "https://..." }
    ]
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Неуспешное событие заменяет output на error. Точное содержимое error зависит от типа сбоя — пример ниже показывает одну из распространённых форм:

{
  "id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "object": "prediction",
  "model": "black-forest-labs/flux-1.1-pro",
  "model_endpoint": "text-to-image",
  "status": "failed",
  "input": {
    "prompt": "Приморский городок в стиле Studio Ghibli..."
  },
  "error": {
    "code": "EXAMPLE_ERROR_CODE",
    "message": "Понятное человеку сообщение об ошибке"
  },
  "created_at": "2026-04-28T12:00:00.000Z",
  "completed_at": "2026-04-28T12:00:08.123Z"
}

Поле	Описание
`id`	`request_id`, возвращённый при отправке. Используйте для дедупликации повторов.
`object`	Всегда `"prediction"`.
`model`	Владелец и имя модели (например, `black-forest-labs/flux-1.1-pro`).
`model_endpoint`	Слаг эндпоинта (например, `text-to-image`).
`status`	`"succeeded"` или `"failed"`.
`input`	Исходное тело запроса, которое вы отправили.
`output`	Присутствует при `succeeded`. То же тело ответа, которое возвращает эндпоинт результата.
`error`	Присутствует при `failed`. Объект, описывающий сбой; его структура зависит от типа сбоя.
`created_at`	Временная метка ISO 8601 создания запроса.
`completed_at`	Временная метка ISO 8601, когда запрос достиг конечного состояния.

Поведение повторов

Доставка webhook осуществляется по принципу хотя бы один раз. Если ваш эндпоинт превышает таймаут (5 с) или возвращает не-2xx статус, Sunra повторяет с экспоненциальной задержкой — до 3 повторов с задержками от 10 секунд и не более 30 секунд. После последнего повтора сбой регистрируется, и больше попыток не предпринимается. Поскольку повторы могут доставлять одно и то же событие несколько раз, ваш обработчик должен быть идемпотентным — используйте поле id в качестве ключа дедупликации.

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

Используйте HTTPS и проверьте, что трафик доходит до ожидаемого эндпоинта.
Отвечайте 2xx немедленно и обрабатывайте полезную нагрузку асинхронно.
Считайте доставку доставкой хотя бы один раз и дедуплицируйте по id.
Объединяйте webhook с эндпоинтами опроса или стриминга, если вам нужны обновления прогресса до конечного события.

Отмена запросов

Если ваш запрос все еще находится в очереди, вы можете отменить его с помощью:

curl -X PUT https://api.sunra.ai/v1/queue/requests/{request_id}/cancel

Получение ответов

Как только ваш запрос будет COMPLETED, получите ответ, используя:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}

Эта конечная точка также предоставляет журналы для просмотра.

Упрощенная интеграция с клиентом Sunra

Клиент Sunra автоматизирует отслеживание статуса, упрощая разработку приложений с функциями Sunra.

Ограничения скорости

Чтобы обеспечить справедливое использование и стабильность системы, наши конечные точки API подлежат следующим ограничениям скорости:

Тип конечной точки	Ограничение скорости	Предел всплеска
Отправить в очередь	10 запросов/секунду	100 запросов/минуту
Все остальные конечные точки	100 запросов/секунду	1800 запросов/минуту

Если вы превысите эти лимиты, вы получите ответ 403 Forbidden. Мы рекомендуем реализовать механизм повторных попыток с экспоненциальной задержкой для обработки таких случаев.

​Конечные точки очереди

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

​Использование конечной точки

​Пример ответа

​Возможные статусы

​Включение журналов

​Мониторинг в реальном времени

​Webhooks

​Включение Webhooks

​Когда срабатывает Webhook

​Формат запроса

​Полезная нагрузка

​Поведение повторов

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

​Отмена запросов

​Получение ответов

​Упрощенная интеграция с клиентом Sunra

​Ограничения скорости