Изменить свой API-ключ

PATCHhttps://api.souz.ai/v1/keys/{id}

Полная замена редактируемых полей — null у spend_limit_micro/expires_at снимает ограничение, пропущенный spend_limit_reset — none. Держатель ключа не меняется. Разработчик — только свои ключи (чужой — 404), администратор и владелец — любые. Разработчик и выше. Ключ управления не меняется: его отзывают и создают новый.

Авторизация

ManagementKey

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

ClientSession

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

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

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

Id ключа

Тело запроса обязательно

Новые значения

application/json

Схема UpdateAPIKeyRequest

expires_atstring | null

RFC 3339; null — ключ бессрочный.

Пример: "2026-12-31T00:00:00Z"

namestring

Пример: "production"

spend_limit_microinteger | null · int64

null — без потолка.

Пример: 1000000

spend_limit_resetstring

none | daily | monthly; без поля — none.

Значения: none, daily, monthly

Пример: "monthly"

Ответы

200OK

application/json

Схема APIKeyEntry

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

Ключ заблокирован службой поддержки — отдельно от enabled: включить его снова нельзя, запросы по нему получают 403 key_blocked. Снять блокировку — через поддержку.

Пример: false

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

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

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

Автор ключа — только он открывает секрет (GET /v1/keys/{id}/secret); null — автор неизвестен или удалён из аккаунта, секрет не открыть.

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

Пример: true

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

RFC 3339; null — ключ бессрочный.

Пример: "2026-12-31T00:00:00Z"

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

Пример: "key_1a2b3c4d5e6f7890"

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

user — обычный ключ, management — ключ управления: модели не запускает, потолка трат нет.

Значения: user, management

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

Когда ключ последний раз прошёл проверку; null — ещё ни разу.

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

Держатель ключа — его автор: траты ключа идут в его лимит, при его удалении ключ отзывается; null — ключ аккаунта, выданный до того, как ключи стали личными.

namestring

Пример: "production"

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

Можно ли показать секрет снова (GET /v1/keys/{id}/secret); false — показать нельзя (ответ 409 secret_unavailable), создайте новый ключ.

Пример: true

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

Подсказка секрета: приставка, первые 4 и последние 4 знака — узнать ключ, не открывая его; null — секрет не сохранён.

Пример: "sk_9f3a…c1d2"

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

Потолок трат ключа в микроединицах валюты; null — без потолка.

Пример: 1000000

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

Как часто обновляется потолок: none — на весь срок ключа; daily / monthly — spent_micro считается с 00:00 UTC текущего дня / с 1-го числа текущего месяца.

Значения: none, daily, monthly

Пример: "monthly"

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

Списано по запросам ключа в текущем окне потолка (при none — за весь срок), в микроединицах; только завершённые запросы.

Пример: 250000

400Запрос отклонён; `error.detail[]` называет поля и допустимые значения.

application/json

Error

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

415Тип тела не тот, что принимает метод: `Content-Type: application/json` (у загрузки файла и транскрибации — `multipart/form-data`). В `detail[]` — `{"path": "body", "reason": "unsupported_format"}` и принимаемые типы.

application/json

Error

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

application/json

Error

503Плановые работы (`maintenance`): новые запросы приостановлены до `error.ends_at`,

Плановые работы (maintenance): новые запросы приостановлены до error.ends_at, причина — в error.reason. Повторите после этого времени (или через Retry-After секунд, чтобы узнать, не закончились ли работы раньше); принятые задачи доделываются, переключаться никуда не нужно. Состояние — GET /v1/status.

application/json

Error

Запрос

curl -X PATCH 'https://api.souz.ai/v1/keys/{id}' \
  -H "Authorization: Bearer $SOUZ_MANAGEMENT_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "name": "production"
}'

import os
import requests

response = requests.patch(
    "https://api.souz.ai/v1/keys/{id}",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_MANAGEMENT_KEY']}"},
    json={
        "name": "production",
    },
)
print(response.json())

const response = await fetch("https://api.souz.ai/v1/keys/{id}", {
  method: "PATCH",
  headers: { Authorization: `Bearer ${process.env.SOUZ_MANAGEMENT_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "production"
  }),
});
console.log(await response.json());

Ответ

{
  "error": {
    "code": "capability_mismatch",
    "detail": [
      {
        "allowed": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "path": "aspect_ratio",
        "reason": "unsupported_value"
      }
    ],
    "message": "the model does not support this value",
    "type": "invalid_request_error"
  }
}

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

{
  "error": {
    "code": "maintenance",
    "ends_at": "2026-10-04T14:15:00+03:00",
    "message": "scheduled maintenance: new requests are paused until ends_at; retry after it, accepted jobs finish afterwards and nothing needs to change on your side",
    "reason": "Обновление сервиса",
    "type": "model_error"
  }
}