API 키 수정 | ToAPIs Documentation

PATCH

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

중국 본토 사용자 안내: 중국 본토 사용자는 https://api.toapis.cn 를 API 엔드포인트(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 객체여야 하며 알 수 없거나 중복된 필드와 쿼리 매개변수는 거부합니다. 본문 읽기 제한 시간은 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본문

남은 크레딧의 절대값을 설정하며 추가하지 않습니다. 최종 unlimited=false이면 음수가 아닌 십진 문자열만 허용하며 true이면 생략 또는 null만 허용합니다. 생략하면 저장된 잔액을 유지하고, null이어도 무제한 키에 저장된 잔액은 지워지지 않습니다.

allow_ipsarray본문

이 모델 API Key의 출발지 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": []
  }
}