API 키 생성 | ToAPIs Documentation

POST

/api/v1/api-keys

중국 본토 사용자 안내: 중국 본토 사용자는 https://api.toapis.cn 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 https://api.toapis.com 을 https://api.toapis.cn 로 바꿔 주세요.

동작

새 모델 키를 생성하여 생성 API 호출에 사용합니다. 성공 시 HTTP 201과 전체 비밀 키를 반환합니다: 비밀 키는 이 응답에 한 번만 나타나고 이후 GET에서는 반환되지 않으니 즉시 저장하세요. 새 키는 계정의 기본 그룹을 사용하며 그룹 지정, 그룹 간 재시도, Webhook 설정은 불가합니다.

초기 할당량은 해당 키의 호출 상한이며 계정 잔액에서 선공제되지 않습니다.

금액 필드는 음이 아닌 십진 문자열만 받고 내부에서 사용하는 정수 할당량 단위로 정확히 환산되어야 하며 소수는 자동으로 절삭되지 않습니다. 계정당 삭제되지 않은 키는 최대 10000개이고 초과 시 409 (code=13004)를 반환합니다.

생성은 멱등하지 않습니다: 응답을 잃어버린 경우 재전송 전에 키 목록에서 생성 여부를 먼저 확인하고, 생성됐지만 비밀 키를 저장하지 못했다면 교체로 새 비밀 키를 얻을 수 있습니다.

인증

Authorizationstring헤더필수

Bearer YOUR_SYSTEM_ACCESS_TOKEN을 사용합니다. 모델 키는 허용하지 않으며 X-User-Id는 필요하지 않습니다. 공통 규칙은 시작하기를 참조하세요.

요청 매개변수

빈 본문이 아니면 Content-Type: application/json이 필요하며 최대 16384바이트입니다. 최상위는 JSON 객체여야 하며 알 수 없거나 중복된 필드와 쿼리 매개변수는 거부합니다. 본문 읽기 제한 시간은 10초입니다.

namestring본문필수

공백 제거 후 필수이며 최대 50 UTF-8바이트.

expires_atstring | null본문

미래 RFC 3339 시간, 소수 초는 올림. null 또는 생성 시 생략은 무기한, 수정 시 생략은 유지.

unlimitedboolean본문기본값: false

기본 false이며 null은 허용되지 않습니다. true이면 remaining_credits는 생략하거나 null이어야 하며, 값을 주면 400입니다.

remaining_creditsstring본문기본값: 0

초기 잔여 credits, 기본 문자열 "0".

daily_limit_creditsstring | null본문

일일 credits 한도. null 또는 문자열 "0"은 무제한.

monthly_limit_creditsstring | null본문

월간 credits 한도. null 또는 문자열 "0"은 무제한.

model_limitsarray본문기본값:

모델 ID 배열, 기본 []. 비어 있지 않으면 제한을 활성화합니다. 항목은 공백 제거 후 비어 있거나 쉼표를 포함할 수 없으며 최초 순서대로 중복을 제거하며 결합 길이는 최대 1024 UTF-8 바이트입니다.

allow_ipsarray본문기본값:

이 모델 API Key의 출발지 IP만 제한하는 문자열 배열입니다. 개별 IPv4/IPv6 주소의 공백을 제거하고 정규화하며 중복을 제거합니다. []는 제한 해제이고 null 또는 잘못된 주소는 400입니다. CIDR, 호스트 이름, 포트, IPv6 zone은 지원하지 않습니다.

요청 예제

요청 예시

curl --request POST \
  --url 'https://api.toapis.com/api/v1/api-keys' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"name": "Example Key", "expires_at": "2027-01-01T00:00:00Z", "unlimited": false, "remaining_credits": "500", "daily_limit_credits": null, "monthly_limit_credits": null, "model_limits": ["example-image-model"]}'

import requests

response = requests.post(
    "https://api.toapis.com/api/v1/api-keys",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    json={'name': 'Example Key', 'expires_at': '2027-01-01T00:00:00Z', 'unlimited': False, 'remaining_credits': '500', 'daily_limit_credits': None, 'monthly_limit_credits': None, 'model_limits': ['example-image-model']},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/api-keys", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({"name": "Example Key", "expires_at": "2027-01-01T00:00:00Z", "unlimited": false, "remaining_credits": "500", "daily_limit_credits": null, "monthly_limit_credits": null, "model_limits": ["example-image-model"]}),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

응답 필드

예제는 가상 데이터입니다. 메타데이터는 키 상세, 공통 응답과 오류는 시작하기를 참조하세요.

data.keystring

sk- 접두사가 포함된 전체 비밀 키로, 이번 생성 또는 교체 응답에서만 반환합니다.

응답 예제

응답 예시

{
  "code": 0,
  "message": "",
  "data": {
    "id": "43",
    "name": "Example Key",
    "key_hint": "****xyz9",
    "status": "enabled",
    "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,
    "key": "sk-example00000000000000000000000000000000000000xyz9",
    "model_limits": [
      "example-image-model"
    ],
    "allow_ips": []
  }
}