Детали своего запроса

GEThttps://api.souz.ai/v1/usage/{id}

Итог запроса: цена price, параметры генерации, подписанная ссылка на результат и ошибка — что применимо. У чат-задач ещё и content: что ушло в модель и что она ответила (хранится до retention.chat_content_days дней из GET /v1/key; нет поля — содержимого нет). Читается и обычным API-ключом — только запросы, отправленные этим ключом, без предела частоты. Разработчику доступны только запросы по его ключам. Чужой id отвечает 404.

Авторизация

BearerAuth

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

ManagementKey

Ключ управления из кабинета souz.ai (выдают владелец и администратор аккаунта — себе или участнику). Даёт ровно то, что его держатель видит и может в кабинете: баланс, историю операций и запросов, расходы, обычные ключи, настройки аккаунта — с той же ролью, лимитами и цифрами. Модели не запускает. Обычный API-ключ здесь не подходит: 403 forbidden с detail[].reason: requires_management_key.

ClientSession

Сессия кабинета souz.ai в браузере — те же ручки, что у ключа управления.

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

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

Id запроса — job_… или, у чата, chatcmpl-… из его ответа.

Ответы

200OK

application/json

Схема JobDetailResponse

actionstring

Действие музыкального запроса. У старых запросов на создание песни — generate; у других типов запросов поля нет.

Пример: "lyrics"

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

Пример: "key_1a2b3c4d5e6f7890"

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

Значения: user, playground, agent

Пример: "user"

api_key_namestring

Пример: "production"

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

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

Пример: "gpt-5-nano"

channelChannelId | null

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

contentвсе варианты

Содержимое чата, пока оно хранится.

Вариант 1JobContentEntry

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

Пример: "2026-08-21T12:00:00Z"

duration_msinteger

Сколько шёл запрос целиком, от приёма до итога, — та же цифра, что в списке; есть у завершённого запроса.

Пример: 12400

errorвсе варианты

Есть у не удавшегося запроса.

Вариант 1JobErrorEntry

extra_resultsarray[File]

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

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

Пример: "job_abc123"

input_fileвсе варианты

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

Вариант 1File

input_textstring

Текст запроса на озвучку; хранится тот же срок, что содержимое чата. Голос и сведения о результате остаются в карточке.

Пример: "Привет!"

input_tokensinteger

Пример: 1978

last_frameFile

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

model_versionstring

Выбранная версия музыкальной модели, если она была указана в запросе.

Пример: "v6"

output_tokensinteger

Пример: 88

paramsвсе варианты

Параметры генерации — у изображений, видео, музыки и расшифровки.

Вариант 1GenerationParamsEntry

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

Пример: 5000

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

Пример: "req_1a2b3c"

resultвсе варианты

Результат успешной генерации — то же описание файла, что в GET /v1/jobs/{id}: подписанная ссылка, пока файл хранится, после — expired: true. last_frame — второй файл, если видео его вернуло.

Вариант 1File

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

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

Откуда пресет routing, в котором шёл запрос, — из запроса (request) или из настройки аккаунта (account).

Значения: request, account

Пример: "account"

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

terminal_codeTerminalCode

textstring

Расшифровка успешного запроса на транскрибацию; хранится тот же срок, что содержимое чата, потом поля нет.

Пример: "привет, это расшифровка"

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

Пример: "2026-08-21T12:00:02Z"

usageвсе варианты

Объём расшифровки; остаётся и после того, как текст перестал храниться.

Вариант 1JobUsageEntry

voicestring

Пример: "eve"

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/usage/{id}' \
  -H "Authorization: Bearer $SOUZ_API_KEY"

import os
import requests

response = requests.get(
    "https://api.souz.ai/v1/usage/{id}",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_API_KEY']}"},
)
print(response.json())

const response = await fetch("https://api.souz.ai/v1/usage/{id}", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}` },
});
console.log(await response.json());

Ответ

{
  "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"
  }
}