Token 관리 API

API 개요

Token 관리 API를 사용하면 콘솔에서 키를 하나씩 클릭해 관리하는 대신, 코드로 API 키의 전체 수명 주기를 관리할 수 있습니다. 가장 일반적인 사용 사례는 일괄 발급입니다. 각 팀원, 다운스트림 고객 또는 프로젝트에 각각 고유한 키를 제공하고, 각 키에 사용할 수 있는 금액, 호출할 수 있는 모델, 유효 기간을 개별적으로 설정할 수 있습니다. 예약 작업과 함께 사용하면 각 키에 자동으로 재설정되는 일일 예산을 설정할 수도 있습니다.

쿼터 한도

remain_quota 이 키가 사용할 수 있는 총액을 제한합니다

모델 제한

models 허용 목록을 설정하며, 목록에 없는 항목에 대한 호출은 거부됩니다

만료 제한

expired_time 만료 시각을 설정하며, 이 시각이 지나면 키가 작동하지 않습니다

키가 한두 개만 필요하다면 콘솔을 사용하는 편이 더 빠릅니다. API 키 생성 방법을 참고하세요. 이 API는 자동 발급, 예약된 키 로테이션 또는 자체 시스템에 키 관리를 통합하는 용도를 위한 것입니다.

개인 액세스 Token 발급 방법

Token 관리 API는 개인 액세스 token(nap_로 시작)으로 인증하며, 이는 API 키와 동일하지 않습니다.

개인 액세스 Tokens 열기

api.apiyi.com/account/profile의 프로필 페이지로 이동합니다. 계정 옵션에서 개인 액세스 Tokens → Token 생성을 클릭합니다.

필요한 Model keys 권한 선택

세 가지 권한은 독립적입니다. 사용하는 권한만 선택하십시오:

수행하려는 작업	선택할 권한
API 키 목록 조회 또는 가져오기	Model keys · Read
API 키 생성, 업데이트, 비활성화 또는 삭제	Model keys · Write
새 API 키의 일반 텍스트 조회(외부 전달용)	Model keys · Reveal secret

대량 발급 스크립트에는 세 가지가 모두 필요합니다. 사용량 모니터링 스크립트에는 Read 권한만 필요합니다.

만료 기간 및 IP 허용 목록 설정

기본 만료 기간은 30일이므로 더 긴 기간으로 설정하는 것을 권장합니다. 발급 스크립트가 고정 IP를 사용하는 서버에서 실행되는 경우 IP 허용 목록을 설정하는 것을 강력히 권장합니다. 허용 목록은 생성 후 수정할 수 없으므로, 먼저 허용 목록 없이 스크립트가 정상 작동하는지 확인한 다음 허용 목록이 포함된 별도의 프로덕션 token을 생성하십시오.

개인 액세스 token 생성: 이름, 만료 기간, IP 허용 목록 및 권한

Write 및 Reveal secret 권한이 있는 token은 모델을 호출할 수 있는 API 키를 생성할 수 있습니다. 계정 비밀번호처럼 안전하게 관리하십시오.개인 액세스 token 자체는 모델을 호출할 수 없지만, 모델을 호출할 수 있는 키를 발급할 수 있습니다. 이러한 token에는 IP 허용 목록을 지정하고, 코드 대신 시크릿 관리자에 저장하며, 저장소에 절대 커밋하지 말고 만료되기 전에 교체하십시오.

기존 시스템 tokens는 2026-11-11 (UTC+8)에 폐기될 예정입니다. “계정 옵션 - 시스템 Token”에서 생성된 AccessTokens는 해당 시점까지 계속 작동합니다. 해당 날짜 이후에는 401 ACCESS_TOKEN_LEGACY_RETIRED를 반환합니다. 사용량을 검토하여 일정을 연장할 수도 있지만, 지금 개인 액세스 token으로 전환하는 것을 권장합니다. 전환 시 스크립트도 확인하십시오. 생성 엔드포인트는 이제 마스킹된 key를 반환합니다. 일반 텍스트를 가져오려면 아래 설명된 대로 POST /api/token/{id}/key를 호출하십시오. 개인 액세스 Token이란 무엇인가요?를 참조하십시오.

엔드포인트

모든 엔드포인트는 동일한 방식으로 인증합니다: 개인 액세스 token을 Authorization 헤더에 입력합니다. Bearer 접두사는 선택 사항입니다.

메서드	경로	목적	권한
`GET`	`/api/token/?p=0&page_size=100`	계정의 모든 tokens 목록 조회(`key`는 마스킹 처리됨)	읽기
`GET`	`/api/token/{id}`	단일 token 조회	읽기
`POST`	`/api/token/`	token 생성(응답의 `key`는 마스킹 처리됨)	쓰기
`POST`	`/api/token/{id}/key`	키의 평문 조회	시크릿 공개
`PUT`	`/api/token/`	token 수정(전체 객체 필요)	쓰기
`PUT`	`/api/token/?status_only=true`	활성화/비활성화 상태만 전환	쓰기
`DELETE`	`/api/token/{id}`	token 삭제	쓰기

기본 URL은 https://api.apiyi.com입니다.

token 생성

요청 예시

export APIYI_SYS_TOKEN='nap_YOUR_PERSONAL_ACCESS_TOKEN'   # personal access token

curl --compressed -s -X POST 'https://api.apiyi.com/api/token/' \
  -H "Authorization: $APIYI_SYS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "team-alice",
    "remain_quota": 500000,
    "unlimited_quota": false,
    "group": "default",
    "models": "gpt-5.6,deepseek-chat",
    "expired_time": -1
  }'

요청 필드

필드	타입	설명
`name`	String	식별을 위한 token 이름
`remain_quota`	Integer	크레딧 단위의 쿼터 상한, 500,000 = $1.00
`unlimited_quota`	Boolean	쿼터 무제한 여부, 기본값은 `false`
`group`	String	token이 바인딩된 그룹 식별자(예: `default`)
`models`	String	모델 허용 목록, 쉼표로 구분. 제한이 없는 경우 생략
`expired_time`	Integer	Unix 초 단위 만료 타임스탬프, `-1`은 만료되지 않음을 의미

unlimited_quota의 기본값은 false이고 remain_quota의 기본값은 0입니다. 둘 다 생략하면 쿼터가 0인 token이 생성되어 사용할 수 없습니다. remain_quota을 명시적으로 설정하거나 unlimited_quota을(를) true(으)로 설정하십시오.

모델 허용 목록에는 models 필드를 사용하십시오.응답 구조에는 model_limits, model_limits_enabled 및 allow_ips도 포함되어 있습니다. 이 값들을 전달해도 오류가 발생하지 않으며 엔드포인트는 여전히 200을 반환하지만, 현재는 아무런 효과가 없으며 token을 다시 조회하면 설정되지 않은 것으로 나타납니다. 사용 가능한 모델을 제한하려면 models을(를) 사용하십시오. 소스 IP 제한은 현재 직접 구현해야 합니다.

응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "id": 119431,
    "user_id": 80778,
    "key": "K1RP**********4b75",
    "status": 1,
    "name": "team-alice",
    "group": "default",
    "models": "gpt-5.6,deepseek-chat",
    "remain_quota": 500000,
    "unlimited_quota": false,
    "used_quota": 0,
    "expired_time": -1,
    "created_time": 1785599000
  }
}

응답의 key은 마스킹되어 있어 직접 사용할 수 없습니다. 평문을 확인하려면 응답의 id을(를) 사용하여 평문 조회 엔드포인트를 호출하십시오.

키 일반 텍스트 조회

curl --compressed -s -X POST 'https://api.apiyi.com/api/token/119431/key' \
  -H "Authorization: $APIYI_SYS_TOKEN"

{
  "success": true,
  "message": "",
  "data": {
    "key": "K1RPzapuXLfBU4kDC5D9C0E70b1841AeAa542186B2F54b75"
  }
}

개인 액세스 토큰에 Model keys · Reveal secret 권한이 필요하며, 그렇지 않으면 403 ACCESS_TOKEN_SCOPE_DENIED이 반환됩니다.
반환된 key에는 sk- 접두사가 포함되지 않습니다. 직접 앞에 추가해야 합니다. 위 예시에서 실제 API 키는 sk-K1RPzapu…입니다.
즉시 저장하고 안전한 채널을 통해 배포하십시오. 응답 본문을 로그 파일에 남겨두지 마십시오.

일괄 생성

서버 측 일괄 생성 엔드포인트는 제공되지 않습니다 — 요청 본문에 count와 같은 값을 전달해도 적용되지 않으며 단일 token만 생성됩니다. 일괄 발급은 클라이언트에서 반복 실행하여 수행합니다.

단일 사용자는 최대 1,000개의 tokens를 보유할 수 있습니다. 이는 계정 전체에 적용되는 상한선이며, 삭제되지 않고 비활성화된 tokens도 포함됩니다. 상한선에 도달하면 생성 엔드포인트 호출이 실패하므로, 더 이상 사용하지 않는 tokens를 삭제하여 슬롯을 확보하십시오.일괄 작업을 실행하기 전에 GET /api/token/?p=0&page_size=100을(를) 페이지별로 조회하여 이미 보유한 개수를 확인하십시오. 키를 교체할 때는 “새 키 생성 → 트래픽 전환 → 이전 키 비활성화 → 남은 호출이 없을 때 삭제”의 마지막 단계까지 확실하게 완료하십시오. 삭제하지 않고 비활성화만 해 두면 슬롯이 계속 점유되므로, 몇 번의 교체 주기만 거쳐도 상한선에 도달하게 됩니다.

Python
Node.js
cURL

import json
import os
import time

import requests

BASE = "https://api.apiyi.com"
HEADERS = {"Authorization": os.environ["APIYI_SYS_TOKEN"],
           "Content-Type": "application/json"}
QUOTA_PER_USD = 500_000


def create_token(name, quota_usd=None, group="default", models=None, days=0):
    """Create one token. quota_usd=None means unlimited; days=0 means never expires."""
    body = {
        "name": name,
        "group": group,
        "unlimited_quota": quota_usd is None,
        "remain_quota": 0 if quota_usd is None else int(quota_usd * QUOTA_PER_USD),
        "expired_time": -1 if not days else int(time.time()) + days * 86400,
    }
    if models:
        body["models"] = models

    resp = requests.post(f"{BASE}/api/token/", headers=HEADERS, json=body, timeout=30)
    resp.raise_for_status()
    data = resp.json()["data"]          # key here is masked

    # Retrieve the plaintext: needs "Model keys · Reveal secret"
    resp = requests.post(f"{BASE}/api/token/{data['id']}/key", headers=HEADERS, timeout=30)
    resp.raise_for_status()
    key = resp.json()["data"]["key"]
    return {"id": data["id"], "name": data["name"], "key": "sk-" + key}


if __name__ == "__main__":
    names = ["team-alice", "team-bob", "team-carol"]
    created = [
        create_token(n, quota_usd=1, group="default", models="gpt-5.6", days=30)
        for n in names
    ]
    for row in created:
        print(f"{row['name']:16s} id={row['id']} {row['key']}")

    # keys.json holds plaintext keys: store and distribute carefully, delete when done
    with open("keys.json", "w") as f:
        json.dump(created, f, ensure_ascii=False, indent=1)

const BASE = "https://api.apiyi.com";
const HEADERS = {
  Authorization: process.env.APIYI_SYS_TOKEN,
  "Content-Type": "application/json",
};
const QUOTA_PER_USD = 500_000;

async function createToken(name, { quotaUsd = null, group = "default",
                                   models = null, days = 0 } = {}) {
  const body = {
    name,
    group,
    unlimited_quota: quotaUsd === null,
    remain_quota: quotaUsd === null ? 0 : Math.round(quotaUsd * QUOTA_PER_USD),
    expired_time: days ? Math.floor(Date.now() / 1000) + days * 86400 : -1,
  };
  if (models) body.models = models;

  const resp = await fetch(`${BASE}/api/token/`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify(body),
  });
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  const { data } = await resp.json();   // key here is masked

  // Retrieve the plaintext: needs "Model keys · Reveal secret"
  const r2 = await fetch(`${BASE}/api/token/${data.id}/key`, { method: "POST", headers: HEADERS });
  if (!r2.ok) throw new Error(`HTTP ${r2.status}`);
  const { data: secret } = await r2.json();
  return { id: data.id, name: data.name, key: `sk-${secret.key}` };
}

const names = ["team-alice", "team-bob", "team-carol"];
for (const name of names) {
  const row = await createToken(name, { quotaUsd: 1, models: "gpt-5.6", days: 30 });
  console.log(row.name, row.id, row.key);
}

export APIYI_SYS_TOKEN='nap_YOUR_PERSONAL_ACCESS_TOKEN'   # personal access token

for NAME in team-alice team-bob team-carol; do
  ID=$(curl --compressed -s -X POST 'https://api.apiyi.com/api/token/' \
    -H "Authorization: $APIYI_SYS_TOKEN" \
    -H 'Content-Type: application/json' \
    -d "{\"name\":\"$NAME\",\"remain_quota\":500000,\"unlimited_quota\":false,\"group\":\"default\",\"expired_time\":-1}" \
    | jq -r '.data.id')
  KEY=$(curl --compressed -s -X POST "https://api.apiyi.com/api/token/$ID/key" \
    -H "Authorization: $APIYI_SYS_TOKEN" | jq -r '.data.key')
  printf '%s\tsk-%s\n' "$NAME" "$KEY"
done

세 가지 제한 사용

쿼터 제한

remain_quota은 token이 사용할 수 있는 금액을 제한합니다. 환산 기준은 잔액 조회 API와 일치합니다.

환산 규칙

쿼터 500,000 = $1.00 USD

예를 들어, 하위 고객에게 $10 한도가 설정된 키를 발급하려면 remain_quota을 5000000로 설정하고 unlimited_quota은 false로 설정합니다. 현재까지의 사용량은 token의 used_quota 필드에서 확인할 수 있습니다. remain_quota은 일회성 총액이며 자동으로 충전되지 않습니다. 일일 예산을 설정하려면 아래의 시나리오: 키별 일일 한도를 자동으로 초기화를 참조하세요.

모델 제한

models은 쉼표로 구분된 허용 목록입니다. 설정하면 목록에 없는 모델을 호출할 때 요청이 거부됩니다.

{
  "error": {
    "message": "This token is not authorized to use model: deepseek-chat"
  }
}

응답은 HTTP 403이며 과금되지 않습니다. models을 생략하면 제한이 적용되지 않습니다.

만료 제한

expired_time은 Unix 초 단위 타임스탬프이며, -1은 만료되지 않음을 의미합니다. 예를 들어, 30일 후 만료되는 키는 다음과 같습니다.

import time
expired_time = int(time.time()) + 30 * 86400

Token 목록 조회

curl --compressed -s 'https://api.apiyi.com/api/token/?p=0&page_size=100' \
  -H "Authorization: $APIYI_SYS_TOKEN" | jq '.data[] | {id, name, status, remain_quota, used_quota, models}'

주요 필드:

필드	설명
`id`	Token ID이며, 업데이트 및 삭제에 사용됩니다
`key`	마스킹된 키입니다. 평문은 “키 평문 조회”를 참조하십시오
`status`	`1` = 활성화됨, `2` = 비활성화됨
`remain_quota` / `used_quota`	잔여 쿼터 / 사용된 쿼터
`unlimited_quota`	쿼터 무제한 여부입니다
`models`	모델 허용 목록이며, 비어 있으면 제한이 없음을 의미합니다
`expired_time`	만료 타임스탬프이며, `-1`은(는) 만료 없음을 의미합니다

Token 업데이트하기

업데이트 엔드포인트는 전체 객체를 필요로 합니다 — 패치가 아닙니다.올바른 흐름은 다음과 같습니다: GET 전체 token 객체를 가져와서, 변경하려는 필드를 수정한 뒤 PUT 전체 객체를 다시 보냅니다. 변경된 필드만 보내면 나머지 값이 지워집니다.

import os
import requests

BASE = "https://api.apiyi.com"
HEADERS = {"Authorization": os.environ["APIYI_SYS_TOKEN"],
           "Content-Type": "application/json"}

# 1. fetch the complete object
token = requests.get(f"{BASE}/api/token/119431", headers=HEADERS, timeout=30).json()["data"]

# 2. change only what you need, leaving everything else as-is
token["remain_quota"] = 2_500_000     # raise the cap to $5
token["models"] = "gpt-5.6,gemini-3-pro"

# 3. PUT the whole object back
resp = requests.put(f"{BASE}/api/token/", headers=HEADERS, json=token, timeout=30)
print(resp.json()["success"])

시나리오: 매일 자동으로 초기화되는 키별 한도

회사에서 워크플로, 팀 구성원 또는 다운스트림 프로젝트에 키를 제공할 때 흔히 필요한 사항은 “각 키의 일일 사용 금액은 최대 $5이며, 다음 날 한도가 복구됩니다”입니다. 워크플로가 예상치 못하게 실행되더라도 피해는 하루 예산으로 제한됩니다. 플랫폼에는 아직 기본 제공되는 “일일 쿼터” 필드가 없지만, 위의 업데이트 엔드포인트와 자정에 한 번 실행되는 예약 작업을 함께 사용하면 됩니다. 매일 키의 remain_quota을 일일 한도로 되돌립니다. 키 자체는 변경되지 않으므로 팀 구성원은 계속 같은 키를 사용합니다. 하루 예산을 모두 사용한 키의 요청은 거부되며 과금되지 않습니다. 자정에 초기화된 후에는 다시 사용할 수 있습니다.

개인 액세스 토큰 준비

모델 키 · 읽기 및 모델 키 · 쓰기 권한을 부여합니다. 비밀 키 표시는 필요하지 않습니다. 스크립트가 고정 IP를 사용하는 서버에서 실행된다면 토큰에 IP 허용 목록을 설정합니다.

제한할 키와 일일 한도 목록 작성

목록 조회 엔드포인트를 사용해 각 키의 id을 조회하고, 아래 스크립트의 DAILY_BUDGET_USD에 입력합니다.

매일 00:00 (UTC+8)에 스크립트 실행

cron, 클라우드 함수 타이머 또는 원하는 스케줄러를 사용하면 됩니다. 자세한 내용은 아래를 참조하세요.

초기화 스크립트

"""Run once a day at 00:00 (UTC+8): reset the listed tokens' quota to the daily cap."""
import json
import os
from datetime import datetime, timedelta, timezone
from pathlib import Path

import requests

BASE = "https://api.apiyi.com"
HEADERS = {"Authorization": os.environ["APIYI_SYS_TOKEN"],
           "Content-Type": "application/json"}
QUOTA_PER_USD = 500_000

# token ID -> daily cap (USD)
DAILY_BUDGET_USD = {
    119431: 5,     # team-alice
    119432: 5,     # team-bob
    119433: 20,    # workflow-prod
}
CARRY_OVERDRAFT = True   # deduct yesterday's overspend from today's budget

TZ = timezone(timedelta(hours=8))   # a "day" is measured in UTC+8
STATE = Path(__file__).with_name("daily_quota_state.json")


def main():
    today = datetime.now(TZ).date().isoformat()
    state = json.loads(STATE.read_text()) if STATE.exists() else {}

    for token_id, usd in DAILY_BUDGET_USD.items():
        last = state.get(str(token_id), {})
        if last.get("date") == today:
            continue                     # already reset today; don't hand out a second day's budget

        # 1. fetch the complete object
        token = requests.get(f"{BASE}/api/token/{token_id}",
                             headers=HEADERS, timeout=30).json()["data"]
        remain = token["remain_quota"]
        if "quota" in last:
            spent = (last["quota"] - remain) / QUOTA_PER_USD
            print(f"{token['name']}: spent ${spent:.2f} last period")

        # 2. change only the quota fields, leaving everything else as-is
        quota = int(usd * QUOTA_PER_USD)
        if CARRY_OVERDRAFT and remain < 0:
            quota = max(quota + remain, 0)
        token["remain_quota"] = quota
        token["unlimited_quota"] = False

        # 3. PUT the whole object back
        resp = requests.put(f"{BASE}/api/token/", headers=HEADERS,
                            json=token, timeout=30).json()
        if not resp.get("success"):
            raise RuntimeError(f"failed to reset token {token_id}: {resp.get('message')}")

        # save after each token, so a rerun after a mid-way failure skips the ones already done
        state[str(token_id)] = {"date": today, "quota": quota}
        STATE.write_text(json.dumps(state, indent=1))
        print(f"{token['name']}: today's budget ${quota / QUOTA_PER_USD:.2f}")


if __name__ == "__main__":
    main()

스크립트는 다음 세 가지 작업도 추가로 수행합니다.

중복 초기화 방지: 하루에 두 번 실행되더라도(스케줄러의 누락 작업 보정 실행이나 수동 재실행 등) 하루치 예산을 다시 지급하지 않습니다.
초과 사용분 이월: 쿼터는 소프트 캡이므로(아래 참조), 어제 초과 사용한 금액을 오늘 차감하여 시간이 지나도 일일 평균이 캡 이내로 유지됩니다. 이 기능을 원하지 않으면 CARRY_OVERDRAFT를 False로 설정합니다.
어제 사용 금액 출력: 실행할 때마다 이전 기간에 각 키가 사용한 금액을 로그에 기록하므로, 로그를 간단한 일일 보고서로도 활용할 수 있습니다.

예약 실행

토큰을 본인만 읽을 수 있는 환경 파일에 저장한 다음, cron으로 스크립트가 매일 실행되도록 설정합니다.

# /opt/apiyi-quota/env (chmod 600)
export APIYI_SYS_TOKEN='nap_YOUR_PERSONAL_ACCESS_TOKEN'

# crontab -e
# server time zone is UTC+8:
0 0 * * * . /opt/apiyi-quota/env && python3 /opt/apiyi-quota/reset_daily_quota.py >> /opt/apiyi-quota/reset.log 2>&1
# server time zone is UTC: 00:00 (UTC+8) = 16:00 (UTC), so start the line with 0 16 * * *

다른 시간대에서 “하루”의 기준을 정하려면 cron 시간과 스크립트의 TZ를 모두 변경합니다.

이를 사용하기 전에 알아둘 점

쿼터는 정확한 차단선이 아니라 소프트 캡입니다. 쿼터 확인은 요청이 시작될 때 이루어지므로 여러 요청이 동시에 실행되면 모두 쿼터를 통과할 수 있으며, 비용이 많이 드는 단일 요청(동영상, 4K 이미지, 매우 긴 컨텍스트)은 한 번에 한도를 초과해 잔액이 마이너스가 될 수 있습니다. 동시 실행 수와 단가가 높을수록 초과 폭도 커집니다. 스크립트는 초과 지출을 다음 날로 이월해 차감합니다. 절대로 한도를 초과해서는 안 되는 키가 있다면 자체적으로 해당 키의 동시 실행 수를 제어하거나, models 허용 목록을 사용해 비용이 많이 드는 모델을 제외하세요.

초기화는 예산을 더하는 것이 아니라 덮어씁니다: 사용하지 않은 예산은 다음 날로 이월되지 않습니다. 콘솔에서 이 키들의 쿼터를 수동으로 변경해도 다음 초기화 때 덮어써집니다
자정을 전후해 처리 중인 요청: 자정 전에 보냈지만 자정 이후에 완료된 요청은 새 날짜의 예산에서 과금될 수 있습니다. 대개 소액입니다
스크립트가 실행되지 않으면 키는 소진된 상태로 유지됩니다: 호출은 일시적으로 차단되지만 추가 비용은 발생하지 않습니다. 예약 작업에 실패 알림을 추가하세요
계정 잔액이 여전히 전체 한도입니다: 키의 일일 한도를 모두 합한 금액이 계정 잔액보다 크면 잔액이 먼저 소진되고 모든 키가 중지됩니다
오늘 특정 키에 조금 더 할당해야 하나요? 업데이트 엔드포인트를 사용해 해당 키의 remain_quota를 늘리세요. 다음 날에는 평소처럼 한도로 초기화됩니다

비활성화 및 삭제

비활성화(기록은 유지됨)

비활성화되면 키는 즉시 작동을 멈춥니다 — 이를 사용한 호출은 401을 반환합니다 — 그러나 token 기록과 사용 내역은 유지됩니다.

token = requests.get(f"{BASE}/api/token/119431", headers=HEADERS, timeout=30).json()["data"]
token["status"] = 2      # 1 = enabled, 2 = disabled

requests.put(f"{BASE}/api/token/", headers=HEADERS,
             params={"status_only": "true"}, json=token, timeout=30)

삭제(되돌릴 수 없음)

curl --compressed -s -X DELETE 'https://api.apiyi.com/api/token/119431' \
  -H "Authorization: $APIYI_SYS_TOKEN"

일괄 삭제도 마찬가지로 클라이언트 측 루프입니다:

for token_id in [119431, 119432, 119433]:
    requests.delete(f"{BASE}/api/token/{token_id}", headers=HEADERS, timeout=30)

삭제는 되돌릴 수 없습니다. 키를 일시적으로 중단하려는 경우에는 대신 비활성화하십시오 — 사용 기록은 대조를 위해 계속 확인할 수 있습니다.

자주 묻는 질문

생성 시 반환된 키가 작동하지 않는 이유는 무엇입니까?

생성 엔드포인트는 마스킹된 key(중간에 *이 연속해서 들어 있음)를 반환하므로 바로 사용할 수 없습니다. 반환된 id로 POST /api/token/{id}/key을 호출해 평문을 가져온 다음(비밀 정보 표시 권한 필요), sk-을 앞에 붙이십시오. 이전 스크립트에서 생성 응답의 key을 바로 사용하고 있다면 개인 액세스 token으로 전환할 때 이 단계를 추가하십시오.

새로 생성한 token에 쿼터가 부족하다고 표시되는 이유는 무엇입니까?

생성 시 remain_quota을 설정하지 않았거나 unlimited_quota을 true로 설정하지 않았을 가능성이 큽니다. 이 기본 조합으로 생성하면 쿼터가 0인 token이 만들어집니다. 두 항목 중 하나를 명시적으로 지정하여 다시 생성하십시오.

model_limits 또는 allow_ips가 적용되지 않는 이유는 무엇입니까?

현재 이 필드와 model_limits_enabled은 적용되지 않습니다. 해당 값을 전달해도 오류는 발생하지 않지만 저장되지 않습니다. 사용 가능한 모델을 제한하려면 models을 사용하십시오. 현재 소스 IP 제한은 직접 처리해야 합니다.

한 번의 요청으로 여러 token을 생성할 수 있습니까?

서버 측 일괄 처리 엔드포인트는 없으며, 요청 본문에 count과 같은 값을 전달해도 적용되지 않습니다. 대신 클라이언트에서 생성 호출을 반복하십시오. 위의 일괄 생성 섹션을 참조하십시오.

계정 하나에 token을 몇 개까지 보유할 수 있습니까?

사용자당 최대 1,000개이며, 비활성화했지만 삭제하지 않은 token도 총 개수에 포함됩니다. 한도에 도달하면 더 이상 필요하지 않은 token을 삭제할 때까지 생성할 수 없습니다. 키를 교체할 때는 삭제 단계까지 완료해야 합니다. 비활성화만 하면 해당 자리가 계속 차지됩니다.

각 키의 일일 지출 한도를 설정하고 다음 날 초기화할 수 있습니까?

기본 제공되는 일일 쿼터 필드는 없지만 예약 작업으로 처리할 수 있습니다. 매일 00:00 (UTC+8)에 업데이트 엔드포인트를 호출해 해당 키의 remain_quota을 일일 한도로 다시 설정하십시오. 키 자체는 변경되지 않습니다. 키의 예산을 다 쓰면 호출은 거부되고 과금되지 않으며, 다음 날 다시 사용할 수 있습니다. 전체 스크립트와 주의 사항은 위의 시나리오: 키별 일일 한도 자동 초기화를 참조하십시오.

업데이트 후 다른 필드가 초기화되었습니다

업데이트 엔드포인트에는 전체 객체가 필요합니다. 먼저 전체 객체를 GET한 다음 수정하고, 변경된 필드만 전송하는 대신 전체 객체를 다시 PUT하십시오.

비활성화와 삭제의 차이는 무엇입니까?

비활성화(status: 2)하면 키가 즉시 작동을 중지하지만 레코드와 사용량 기록은 유지되며, 언제든지 1로 되돌릴 수 있습니다. 삭제는 되돌릴 수 없으며 레코드가 제거됩니다. 일시적으로 사용을 중단하려면 비활성화를 권장합니다.

각 키의 지출액을 확인하려면 어떻게 해야 합니까?

token의 used_quota 필드에는 해당 키의 누적 지출액이 표시됩니다(÷ 500,000 = USD). 기간별 내역이나 호출 단위 상세 정보를 보려면 콘솔 로그 페이지에서 token 이름으로 필터링하십시오. 호출 기록을 확인하는 방법을 참조하십시오.

중요 참고 사항

개인 액세스 token은 API 키가 아니며, 두 항목은 서로 대체할 수 없습니다

API 키(sk-(으)로 시작)는 /v1/* 추론 엔드포인트 전용입니다
개인 액세스 token(nap_(으)로 시작)은 /api/* 관리 엔드포인트 전용이며 모델을 호출할 수 없습니다

오류 참조: 401 ACCESS_TOKEN_LEGACY_RETIRED은(는) 사용 중단된 레거시 시스템 token을 여전히 사용하고 있음을 의미합니다. 401 This access token may not be used from the current IP address.은(는) 해당 token의 허용 목록 외의 IP에서 요청이 전송되었음을 의미합니다. 403 ACCESS_TOKEN_SCOPE_DENIED은(는) 해당 token에 이 엔드포인트에 필요한 권한이 없음을 의미합니다(엔드포인트 표 참조).

일반 텍스트 키를 주의 깊게 다루십시오일반 텍스트 조회 엔드포인트는 모델을 직접 호출할 수 있는 키를 반환합니다. 따라서 다음 사항을 준수하십시오:

key이(가) 포함된 응답 본문을 로그 파일에 기록하거나 저장소에 커밋하지 마십시오
단체 채팅방이 아닌 안전한 채널을 통해 팀원에게 키를 배포하십시오
이 일반 텍스트에는 sk- 접두사가 포함되어 있지 않으므로 일반적인 시크릿 스캐너가 감지하지 못할 수 있습니다 — 자동화된 검사에만 의존하지 마십시오

운영 팁

대량 생성 시에는 순간적인 동시 실행 수가 급증하는 것을 방지하기 위해 호출 간에 적절한 지연 시간을 두십시오
나중에 로그에서 token_name별 사용량을 추적할 수 있도록 각 키에 의미 있는 name(예: team-alice 또는 prod-webhook)을(를) 지정하십시오
키 교체 시: 새 키를 생성하고, 트래픽을 전환한 후, 이전 키를 비활성화하고 잠시 모니터링한 다음, 더 이상 호출이 발생하지 않는 것을 확인한 후에만 삭제하십시오

기초

기본 API

이미지 API (공식)

동영상 API (공식)

멀티모달 이해 API

텍스트 생성

음성 API (공식)

검색 및 안전

API 개요

쿼터 한도

모델 제한

만료 제한

개인 액세스 Token 발급 방법

엔드포인트

token 생성

요청 예시

요청 필드

응답 예시

키 일반 텍스트 조회

일괄 생성

세 가지 제한 사용

쿼터 제한

환산 규칙

모델 제한

만료 제한

Token 목록 조회

Token 업데이트하기

시나리오: 매일 자동으로 초기화되는 키별 한도

초기화 스크립트

예약 실행

이를 사용하기 전에 알아둘 점

비활성화 및 삭제

비활성화(기록은 유지됨)

삭제(되돌릴 수 없음)

자주 묻는 질문

중요 참고 사항

관련 문서

​API 개요

쿼터 한도

모델 제한

만료 제한

​개인 액세스 Token 발급 방법

​엔드포인트

​token 생성

​요청 예시

​요청 필드

​응답 예시

​키 일반 텍스트 조회

​일괄 생성

​세 가지 제한 사용

​쿼터 제한

환산 규칙

​모델 제한

​만료 제한

​Token 목록 조회

​Token 업데이트하기

​시나리오: 매일 자동으로 초기화되는 키별 한도

​초기화 스크립트

​예약 실행

​이를 사용하기 전에 알아둘 점

​비활성화 및 삭제

​비활성화(기록은 유지됨)

​삭제(되돌릴 수 없음)

​자주 묻는 질문

​중요 참고 사항

관련 문서

API 개요

개인 액세스 Token 발급 방법

엔드포인트

token 생성

요청 예시

요청 필드

응답 예시

키 일반 텍스트 조회

일괄 생성

세 가지 제한 사용

쿼터 제한

모델 제한

만료 제한

Token 목록 조회

Token 업데이트하기

시나리오: 매일 자동으로 초기화되는 키별 한도

초기화 스크립트

예약 실행

이를 사용하기 전에 알아둘 점

비활성화 및 삭제

비활성화(기록은 유지됨)

삭제(되돌릴 수 없음)

자주 묻는 질문

중요 참고 사항