토큰 관리 API: 코드로 API 키 발급·관리

토큰 관리 API는 콘솔의 토큰 페이지에서 하는 작업을 코드로 처리합니다. 하위 고객마다 한도가 있는 키를 자동으로 발급하거나, 프로젝트가 끝났을 때 키를 한꺼번에 비활성화하는 데 쓸 수 있습니다. 이 키로 한 호출은 내 계정 잔액에서 차감됩니다.

항목	내용
엔드포인트 접두사	`https://api.laozhang.ai/api/token/`
인증	계정 AccessToken. AccessToken 발급 참고
Quota	500,000 quota = 1 USD
응답 형식	`{"success": true, "message": "", "data": ...}`

AccessToken은 계정을 전부 제어할 수 있으므로 서버에만 보관하세요.

브라우저나 앱에 넣거나 고객에게 전달하지 마세요. 고객에게는 직접 만든 API 키만 줍니다.
잘못된 토큰도 HTTP 200과 success: false로 응답하므로 호출할 때마다 success를 확인하세요.

엔드포인트

작업	요청
키 목록	`GET /api/token/?p=0`
이름으로 검색	`GET /api/token/search?keyword=NAME&p=0`
키 하나 조회	`GET /api/token/{id}`
키 생성	`POST /api/token/`
전체 키 확인	`POST /api/token/{id}/key`
키 수정	`PUT /api/token/`
활성화 또는 비활성화	`PUT /api/token/?status_only=true`
키 삭제	`DELETE /api/token/{id}`

목록과 검색은 페이지당 키 10개를 반환하며 p는 0부터 시작합니다. 이 결과의 key는 일부가 가려져 있으므로, 모델 호출에 쓸 전체 키는 키 확인 엔드포인트로 가져옵니다.

새 키의 필드

필드	타입	설명
`name`	string	키 이름. 검색에 쓰이며 너무 길면 거부됨
`remain_quota`	integer	quota 단위의 사용 한도. `500000`이 1 USD
`unlimited_quota`	boolean	`true`이면 한도가 없으며 `remain_quota`는 무시됨
`expired_time`	integer	Unix 초 단위 만료 시각. `-1`은 만료 없음
`group`	string	토큰 그룹. 보통 `default`이며 다른 그룹은 과금과 가격에 정리되어 있음
`billing_type`	integer	과금 방식. `4` 사용량 우선(권장), `1` 사용량 과금, `2` 건당 과금
`models`	string	쉼표로 구분한 모델 ID 허용 목록. 빈 문자열이면 모든 모델 허용
`remark`	string	선택 사항인 메모

billing_type은 키가 호출할 수 있는 모델을 정합니다. 사용량 과금 키는 사용량 과금 모델만, 건당 과금 키는 건당 과금 모델만, 사용량 우선 키는 둘 다 호출합니다. 세 방식은 과금과 가격에서 설명합니다.

키 생성과 전체 키 확인

아래 스크립트는 한도 5 USD, 만료 30일, 허용 모델 2개인 키를 만든 뒤 전체 키를 확인합니다. requests가 필요합니다(python -m pip install requests).

import os
import time

import requests

BASE = "https://api.laozhang.ai"
HEADERS = {"Authorization": os.environ["LAOZHANG_ACCESS_TOKEN"]}


def call(method, path, **kwargs):
    response = requests.request(method, BASE + path, headers=HEADERS, timeout=30, **kwargs)
    response.raise_for_status()
    payload = response.json()
    if not payload.get("success"):
        raise RuntimeError(f"{path}: {payload.get('message')}")
    return payload.get("data")


created = call("POST", "/api/token/", json={
    "name": "customer-acme",
    "remain_quota": 5 * 500_000,
    "unlimited_quota": False,
    "expired_time": int(time.time()) + 30 * 86400,
    "group": "default",
    "billing_type": 4,
    "models": "gpt-5.4-mini,gemini-3.8-flash",
    "remark": "Acme 체험용",
})
token_id = created["id"]

key = call("POST", f"/api/token/{token_id}/key")["key"]
print(token_id, key[:6] + "...")

확인한 키는 sk- 접두사 유무와 관계없이 모델 API 키(Authorization: Bearer <key>)로 쓸 수 있습니다. 전달하기 전에 시크릿 매니저에 저장하세요. 키 확인 엔드포인트는 호출 제한이 엄격하므로 반복 호출하지 마세요.

수정, 비활성화, 삭제

수정은 키 객체 전체를 교체합니다. GET /api/token/{id}로 읽어 와서 필요한 필드만 바꾼 뒤 전체 객체를 PUT으로 다시 보내세요. 일부 필드만 보내면 나머지가 초기화될 수 있습니다.

token = call("GET", f"/api/token/{token_id}")
token.pop("key", None)
token["remain_quota"] += 10 * 500_000   # 10 USD 추가
token["models"] = "gpt-5.4-mini,gemini-3.8-flash,deepseek-v4-flash"
call("PUT", "/api/token/", json=token)

call("PUT", "/api/token/?status_only=true", json={"id": token_id, "status": 2})  # 비활성화
call("PUT", "/api/token/?status_only=true", json={"id": token_id, "status": 1})  # 다시 활성화

call("DELETE", f"/api/token/{token_id}")

변경은 즉시 적용됩니다.

비활성화했거나 삭제한 키로 모델을 호출하면 HTTP 401 Invalid token.이 반환됩니다.
허용 목록에 없는 모델을 호출하면 해당 토큰이 그 모델을 쓸 수 없다는 메시지와 함께 HTTP 403이 반환됩니다.

오류

증상	원인과 해결
HTTP 401과 `AUTH_REQUIRED`	`Authorization` 헤더가 없음
HTTP 200, `success: false`, “access token is invalid”	AccessToken이 틀렸거나 다시 발급되었음
HTTP 403과 “does not have write permission”	읽기 전용 토큰이라 키를 만들거나 수정, 삭제할 수 없음
`success: false`와 이름이 너무 길다는 메시지	`name`을 줄이세요
`GET /api/token/{id}`가 “record not found” 반환	키가 삭제되었거나 다른 계정의 키임

자주 묻는 질문

고객의 키는 누구의 잔액으로 결제되나요?

내 잔액입니다. 키마다 remain_quota를 지출 한도로 설정하세요. 키가 한도에 도달하면 작동을 멈추며 내 나머지 잔액을 끌어 쓰지 않습니다.

키별 사용량은 어떻게 보나요?

목록과 상세 응답의 used_quota가 해당 키의 누적 사용량입니다. 시간대나 모델별로 나누어 보려면 token_name을 지정한 로그 조회 API를 사용하세요.

`model_limits`를 설정했는데 왜 무시되나요?

모델 허용 목록은 models에서만 읽습니다. 허용할 모델 ID를 쉼표로 구분한 문자열로 models에 넣으세요.

시작하기

이미지 생성·편집 API

비디오 생성 API

텍스트 API

토큰 관리 API: 코드로 API 키 발급·관리

엔드포인트

새 키의 필드

키 생성과 전체 키 확인

수정, 비활성화, 삭제

오류

자주 묻는 질문

고객의 키는 누구의 잔액으로 결제되나요?

키별 사용량은 어떻게 보나요?

`model_limits`를 설정했는데 왜 무시되나요?

관련 문서

​엔드포인트

​새 키의 필드

​키 생성과 전체 키 확인

​수정, 비활성화, 삭제

​오류

​자주 묻는 질문

​고객의 키는 누구의 잔액으로 결제되나요?

​키별 사용량은 어떻게 보나요?

​model_limits를 설정했는데 왜 무시되나요?

​관련 문서

엔드포인트

새 키의 필드

키 생성과 전체 키 확인

수정, 비활성화, 삭제

오류

자주 묻는 질문

고객의 키는 누구의 잔액으로 결제되나요?

키별 사용량은 어떻게 보나요?

`model_limits`를 설정했는데 왜 무시되나요?

관련 문서