Обновить API-ключ | ToAPIs Documentation

PATCH

/api/v1/api-keys/{api_key_id}

Для пользователей из материкового Китая: используйте https://api.toapis.cn в качестве эндпоинта (Base URL). Замените https://api.toapis.com на https://api.toapis.cn во всех примерах этого документа.

Поведение

Изменяет настройки указанного ключа — например, имя, лимиты, статус или срок действия. В теле запроса должно быть хотя бы одно поле: имя, список моделей, дневной/месячный лимиты, unlimited, остаток квоты, статус, срок действия; непереданные поля сохраняют текущие значения.

Включение и статус

Одно изменение настроек не включает ключ.
Если в том же запросе явно передан status=enabled, обновлённые срок действия, unlimited и квота проверяются вместе: истёкший ключ или ключ с исчерпанным лимитом включить нельзя, возвращается 409.
Отозванный ключ возвращает 404.
Если status опущен, сохранённый статус не меняется: ключи disabled/expired/exhausted не восстанавливаются от обновления других полей; у ключа enabled читаемый статус вычисляется из квоты и срока, поэтому после обновления он может вернуться в enabled.

Проверка и запись

Поля сумм проверяются как при создании: JSON-числа и значения без точной конверсии отклоняются.
model_limits равный [] снимает ограничение моделей; дневной/месячный лимиты null или "0" снимают лимит без сброса счётчиков использования.
Установка remaining_credits перезаписывает сохранённый в базе остаток; дальнейшие списания и возвраты идут от нового значения, а уже возникшие, но ещё не записанные пакетные списания применятся позже.
Обновление не меняет накопленное использование и баланс аккаунта.
Если любое поле не проходит проверку, запрос не записывается целиком — частичного обновления не бывает. Обновление выполняется в транзакции с проверкой итоговой конфигурации и записывает только явно переданные поля.
Инвалидация кэша и границы применения для выполняющихся запросов прежние.

Аутентификация

Authorizationstringзаголовокобязательно

Используйте Bearer YOUR_SYSTEM_ACCESS_TOKEN. Ключ модели не подходит, X-User-Id не нужен. См. правила доступа.

Параметры запроса

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

Десятичный строковый ID собственного обычного ключа, не секрет sk-.

Непустое тело требует Content-Type: application/json и ограничено 16384 байтами. Верхний уровень должен быть JSON-объектом. Неизвестные и повторные поля, а также query-параметры отклоняются. Срок чтения тела записи составляет 10 секунд.

statusstringтело

Только enabled или disabled. expired, exhausted и deleted доступны только для чтения.

expires_atstring | nullтело

Будущее время RFC 3339, дробные секунды округляются вверх. null или пропуск при создании означает бессрочно; пропуск при обновлении сохраняет значение.

namestringтело

При передаче имя обрезается по краям и должно быть непустым, не более 50 байт UTF-8. Пропуск сохраняет имя.

model_limitsarrayтело

Заменяет весь список моделей. [] снимает ограничения; null запрещен. Уберите пробелы по краям элементов, исключите пустые строки и запятые, удалите повторы с сохранением порядка. После объединения запятыми максимум 1024 байта UTF-8.

daily_limit_creditsstring | nullтело

Дневной лимит credits, null или строка "0" снимают лимит.

monthly_limit_creditsstring | nullтело

Месячный лимит credits, null или строка "0" снимают лимит.

unlimitedbooleanтело

Логическое значение; null запрещен. При переключении в false без remaining_credits сохраняется записанный остаток, который может быть уже исчерпан. Ключ автоматически не включается.

remaining_creditsstring | nullтело

Устанавливает абсолютный остаток credits, а не прибавляет его. При итоговом unlimited=false допустима только неотрицательная десятичная строка; при true только пропуск или null. Пропуск сохраняет записанный остаток; null не обнуляет остаток, записанный у безлимитного ключа.

allow_ipsarrayтело

Список IP источника только для этого ключа модели. Массив отдельных IPv4/IPv6 адресов с удалением пробелов, нормализацией и удалением повторов. [] снимает ограничение; null и неверный адрес дают 400. CIDR, имена хостов, порты и IPv6 zone не поддерживаются. Пропуск в PATCH сохраняет значение.

Примеры запросов

Пример запроса

curl --request PATCH \
  --url 'https://api.toapis.com/api/v1/api-keys/43' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"status": "disabled"}'

import requests

response = requests.patch(
    "https://api.toapis.com/api/v1/api-keys/43",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    json={'status': 'disabled'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/api-keys/43", {
  method: "PATCH",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({"status": "disabled"}),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Поля ответа

Примеры содержат вымышленные данные. Метаданные описаны в деталях ключа, общий контракт и ошибки в подключении.

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

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

{
  "code": 0,
  "message": "",
  "data": {
    "id": "43",
    "name": "Example Key",
    "key_hint": "****xyz9",
    "status": "disabled",
    "created_at": "2026-11-01T08:00:00Z",
    "expires_at": "2027-01-01T00:00:00Z",
    "unlimited": false,
    "remaining_credits": "500",
    "daily_limit_credits": null,
    "monthly_limit_credits": null,
    "model_limits": [],
    "allow_ips": []
  }
}