Очередь

Для запросов, которые занимают больше нескольких секунд, что типично для приложений ИИ, мы разработали систему очередей. Эта система предлагает вам детальный контроль для управления всплесками трафика, отмены запросов при необходимости и мониторинга статуса вашего запроса в очереди. Она также устраняет необходимость обработки длительных 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. Мы рекомендуем реализовать механизм повторных попыток с экспоненциальной задержкой для обработки таких случаев.

Обзор

Multimodal

LLM

Клиентские библиотеки

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

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

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

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

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

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

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

Webhooks

Включение Webhooks

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

​Webhooks

​Включение Webhooks

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Webhooks

Включение Webhooks

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

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

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

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

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

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

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

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

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