Поток событий задачи

GEThttps://api.souz.ai/v1/jobs/{id}/events

text/event-stream: первым событием — текущее состояние, дальше — новый снимок при каждом изменении, в конце data: [DONE]; к завершённой задаче — снимок и сразу [DONE]. Раз в 15 с — комментарий : ping. Переподключаться можно в любой момент. Схема ниже описывает одно событие data: — объект задачи.

Авторизация

BearerAuth

API-ключ из кабинета souz.ai — запускает модели. Ключ управления здесь не подходит: 403 forbidden с detail[].reason: requires_api_key.

Параметры пути

idstringобязательно

Id задачи — job_…; у чата — chatcmpl-… из ответа.

Пример: "job_1a2b3c4d5e6f"

Ответы

200Поток снимков задачи.

text/event-stream

Схема Job

actionstring

Выполненное действие с аудио.

attempt_countAttemptCountобязательно

channelChannelId | null

Фактический цвет канала запроса: при успехе — канал, который выполнил запрос; пока запрос идёт — канал, которому он уже отправлен; при ошибке — последний вызванный канал. null — запрос ещё не отправлялся ни одному каналу или запись старше каналов. Название и HEX цвета — GET /v1/channels.

completed_atstring | null · date-timeобязательно

Когда задача завершилась; null, пока идёт.

createdinteger · int64обязательно

То же время, что created_at, в unix-секундах — как created у OpenAI.

created_atstring · date-timeобязательно

currencyCurrencyобязательно

dataarray[OutputFile]обязательно

Файлы результата; data[0] — сам результат. У музыкальной модели, которая за запрос даёт два варианта трека, оба — role: result, по порядку. Пустой, пока задача не завершена, и у чата.

durationnumber | null · double

Транскрибация — длительность звука в секундах.

errorErrorBody | nullобязательно

Почему задача не удалась; null, если не провалилась.

idstringобязательно

job_…; у чата — chatcmpl-… из его ответа.

Пример: "job_1a2b3c4d5e6f"

languageLanguageCode | null

Транскрибация — язык записи, код ISO 639-1 (ru, en) у любой модели: названный моделью или, если она его не назвала, из подсказки language запроса. Язык неизвестен — поля нет.

max_price_multiplierMaxPriceMultiplier | nullобязательно

Потолок цены, с которым задача принята: из запроса или из настроек аккаунта на момент приёма. null — без потолка.

modalityModalityобязательно

modelstringобязательно

Пример: "nano-banana-pro"

model_versionstring

Версия музыкальной модели; используйте её при продолжении исходного трека.

objectstringобязательно

Значение: "job"

persona_idstring

ID этой задачи для повторного использования созданной персоны.

priceinteger | null · int64обязательно

Итог в микроединицах currency — фактический объём × цены сработавшего канала на момент приёма; null, пока задача не завершена. У проваленной — 0.

Минимум: 0

resultMusicResult

routingRoutingобязательно

routing_optionsRoutingOptions | nullобязательно

Настройки каналов, с которыми задача принята: из запроса или из настроек аккаунта на момент приёма. null — каналы выбирает Авто-роутинг.

segmentsarray[TranscriptionSegment]

Транскрибация, verbose_json у модели с таймкодами — фразы: предложение или отрезок речи до паузы в секунду и дольше, не длиннее 30 с. Начало фразы — начало её первого слова, конец — конец последнего; одинаково у всех моделей.

statusJobStatusобязательно

textstring | null

Транскрибация — расшифровка; у остальных задач поля нет.

usageJobUsage | nullобязательно

Объём выполненного — токены, символы, секунды; null, где мерить нечего.

voice_idstring

ID этой задачи для повторного использования созданного голоса.

webhookJobWebhook

wordsarray[TranscriptionWord]

Транскрибация — слова с таймкодами, если запрошена детализация по словам.

401Нет ключа или ключ недействителен.

application/json

Error

403Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли

Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли участника нет права или подпись ссылки на файл не сходится. detail[].reason говорит, что именно: requires_api_key, requires_management_key, cabinet_only (только в кабинете), insufficient_role (в allowed — роли, которым можно), not_key_author (секрет ключа открывает только тот, кто его создал).

application/json

Error

404Нет такого объекта у этого аккаунта.

application/json

Error

429Слишком часто — повторите через `Retry-After` секунд. Запуск моделей, задачи и файлы результатов частотой не ограничены (их ограничивают баланс и лимиты трат); здесь 429 — на поток запросов с ключом, который сервер не знает, с одного адреса, и на потоки сверх 1000 одновременных на аккаунт (события задачи, чат с `stream: true`). Пределы — раздел «Лимиты» руководства.

application/json

Error

Запрос

curl -X GET 'https://api.souz.ai/v1/jobs/{id}/events' \
  -H "Authorization: Bearer $SOUZ_API_KEY"

import os
import requests

response = requests.get(
    "https://api.souz.ai/v1/jobs/{id}/events",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_API_KEY']}"},
    stream=True,
)
for line in response.iter_lines(decode_unicode=True):
    print(line)

const response = await fetch("https://api.souz.ai/v1/jobs/{id}/events", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}` },
});
for await (const chunk of response.body!.pipeThrough(new TextDecoderStream())) {
  process.stdout.write(chunk);
}

Ответ

{
  "error": {
    "code": "forbidden",
    "detail": [
      {
        "reason": "requires_api_key"
      }
    ],
    "message": "this endpoint takes an API key; a management key manages the account only",
    "type": "permission_error"
  }
}