변경 내역
공개 API의 호환을 위해 유지되는 기존 경로, 이전 엔드포인트 대체 관계 및 마이그레이션 차이점
2026-11-12
이번 업데이트로 공개 API 문서를 재정비했습니다: 페이지를 계정, API 키, 사용량, 작업, 결제, 요금으로 분류하고 키 수명주기 (생성, 수정, 폐기, 교체), 키 잔액, 모델 요금 문서를 보강했습니다. 기존 "계정" 그룹의 페이지 5개는 삭제되었고 이전 문서 URL은 대응하는 새 페이지로 리다이렉트됩니다.
문서 구조만 바뀌었을 뿐 운영 중인 API 동작은 변하지 않습니다.
호환을 위해 유지되는 기존 경로
아래 10개의 기존 GET 경로는 계속 사용할 수 있으며 동작은 오른쪽 새 경로와 완전히 동일합니다. 호환성을 위해서만 유지되며 이후 버전에서 제거되므로 빨리 마이그레이션하세요. 신규 연동은 새 경로를 직접 사용하세요.
참고로 /api/v1/account와 /api/v1/account/balance 자체가 새 경로이므로 목록에 없습니다.
| 기존 경로 | 새 경로 |
|---|---|
/api/v1/account/api-keys | /api/v1/api-keys |
/api/v1/account/api-keys/{api_key_id} | /api/v1/api-keys/{api_key_id} |
/api/v1/account/usage/records | /api/v1/usage/records |
/api/v1/account/usage/summary | /api/v1/usage/summary |
/api/v1/account/tasks | /api/v1/tasks |
/api/v1/account/tasks/{task_id} | /api/v1/tasks/{task_id} |
/api/v1/account/billing/topups | /api/v1/billing/topups |
/api/v1/account/billing/topups/{trade_no} | /api/v1/billing/topups/{trade_no} |
/api/v1/account/billing/payment-method | /api/v1/billing/payment-method |
/api/v1/account/billing/auto-topup | /api/v1/billing/auto-topup |
키 생성, 수정, 폐기, 교체, 키 잔액, Webhook, 요금, Stripe 청구서에는 /account 접두사가 붙은 기존 경로가 없고 평탄한 새 경로만 있습니다.
기존 계정 API 마이그레이션
아래 표는 기존 엔드포인트와 새 엔드포인트의 기능 대응 관계이며 그대로 치환 가능한 호환 경로가 아닙니다. 자격 증명, 파라미터, 응답 구조가 다르므로 호출 코드도 함께 수정하세요. 기존 잔액 및 생성 API는 모델 키로 인증했지만 새 API는 시스템 액세스 토큰을 사용합니다.
기존 사용량 API에 필요했던 X-User-Id 헤더는 새 API에서 필요하지 않습니다.
| 기존 API | 새 API | 마이그레이션 조건 |
|---|---|---|
GET /v1/balance, /balance | GET /api/v1/api-keys/{api_key_id}/balance | 조회할 키 자체로 인증하지 않고 시스템 액세스 토큰과 키 ID를 사용합니다. 무제한 잔액은 -1 대신 null입니다. |
GET /api/usage/tokens/requests | GET /api/v1/usage/records | 아래 표에 따라 필드와 매개변수를 변경합니다. 캐시 읽기 및 쓰기 수는 usage 안에 반환됩니다. |
GET /api/usage/tokens/summary | GET /api/v1/usage/summary?group_by=api_key | group_by=api_key를 명시합니다. record_count는 로그 행 개수이며 전체 요청 수나 최종 순지출이 아닙니다. |
GET /v1/user/balance, /user/balance | GET /api/v1/account/balance | 자신의 계정 잔액 또는 하위 계정 예산을 읽습니다. 십진 문자열로 USD와 credits를 구분합니다. |
GET /v1/pricing | GET /api/v1/pricing?api_key_id={api_key_id} | api_key_id로 키 컨텍스트를 지정합니다. after/next_after가 cursor/next_cursor로 바뀌고 code/message/data 형식을 사용하므로 같은 프로토콜이 아닙니다. |
POST /v1/tokens | POST /api/v1/api-keys | 새 생성 필드와 유형을 따르세요. group, cross_group_retry, Webhook 설정은 지원하지 않아 기존 기능 전체를 대체하지 않습니다. |
기존 allow_ips의 줄바꿈 구분 문자열이 ["192.0.2.10","2001:db8::1"] 같은 문자열 배열로 바뀝니다. 생성과 수정 모두 지원하며 []로 제한을 해제하고 null이나 유효하지 않은 주소는 400을 반환합니다. 단일 IP 주소만 지원하며 CIDR 범위는 지원하지 않습니다.
사용량 필드 및 페이지 변경
시간 파라미터가 Unix 초 start_timestamp/end_timestamp에서 시간대가 있는 from/to로 바뀌며, 페이지를 넘겨도 같은 범위가 유지됩니다. token_id는 api_key_id 문자열로, page_size는 limit으로 바뀌고 기존 커서는 재사용할 수 없습니다.
캐시 필드: 기존 cache_tokens는 usage.cache_read_tokens, cache_creation_tokens는 usage.cache_write_tokens에 대응합니다.
새 API는 5분 및 1시간 쓰기 분해도 추가로 반환하지만 cache_write_tokens에 이미 포함되므로 중복으로 더하면 안 됩니다. 누락되거나 유효하지 않은 값은 null, 명시적으로 기록된 0은 0을 반환합니다.
파라미터 오류의 HTTP 상태가 422에서 400으로 바뀌고 오류 응답은 숫자 code를 사용합니다. 기존 quota는 내부 단위였지만 새 recorded_credits는 credits로 환산된 값이므로 필드 이름만 바꾸지 말고 금액 의미도 조정하세요.
| 기존 필드 | 새 필드 | 설명 |
|---|---|---|
log_id | id | 이름만 변경. |
token_id | api_key_id | 숫자 ID를 문자열로 전달. |
token_name | key_name | 이름만 변경. |
model_name | model | 이름만 변경. |
start_timestamp/end_timestamp | from/to | Unix 초 → 시간대가 있는 RFC 3339; 페이지 간 동일한 범위 유지. |
page_size | limit | 페이지당 항목 수. |
cost_usd | recorded_cost_usd | 로그 행의 기록된 USD 비용, 십진 문자열. |
quota | recorded_credits | 내부 쿼터 단위 → 환산된 credits. 기존 값을 그대로 쓸 수 없음. |
prompt_tokens | usage.input_tokens | usage 객체로 이동. |
completion_tokens | usage.output_tokens | usage 객체로 이동. |
reported_total_tokens | usage.reported_total_tokens | 업스트림 보고 총 토큰; usage 객체로 이동. |
cache_tokens | usage.cache_read_tokens | 캐시 읽기량; usage 객체로 이동. |
cache_creation_tokens | usage.cache_write_tokens | 캐시 쓰기 총량. 5분/1시간 분할이 이미 포함되어 있으므로 중복 합산 금지. |
request_count | record_count | 로그 항목 수. 전체 요청 수가 아님. |
data[] | data.items[] | 레코드 배열이 data.items로 이동. |
meta.has_more | data.has_more | 페이지네이션 정보가 data로 이동. |
meta.next_cursor | data.next_cursor | 페이지 커서. 기존 커서는 새 API에서 무효. |
키 생성 필드 변경
| 기존 필드 | 새 필드 | 설명 |
|---|---|---|
expired_time | expires_at | Unix 초 (-1은 만료 없음) → 시간대가 있는 RFC 3339; null 또는 생략은 만료 없음. |
remain_quota/remain_credits | remaining_credits | 십진 문자열 (정밀도 유지). |
daily_credits/monthly_credits | daily_limit_credits/monthly_limit_credits | null 또는 "0"은 제한 없음. |
unlimited_quota | unlimited | 불리언, null 불가; true이면 remaining_credits는 생략 또는 null만 가능. |
model_limits_enabled | — | 제거됨; model_limits 배열이 비어 있지 않으면 제한 활성화. |
model_limits | model_limits | 쉼표 구분 문자열 → 문자열 배열; 연결 후 최대 1024 UTF-8 바이트. |
allow_ips | allow_ips | 줄바꿈 구분 문자열 → 문자열 배열; 단일 IP만, CIDR 불가; []로 해제, null/무효는 400. |
동작 변경: 생성 성공 HTTP 상태는 200에서 201로 바뀌고 전체 비밀 키가 sk- 접두사를 포함한 data.key로 반환됩니다.
계속 구분해야 하는 기능
계정 작업 API는 작업 상태와 결제 메타데이터만 반환하며 생성 결과 조회를 대체하지 않습니다. billing과 usage의 의미는 실제 비용 및 작업 사용량을 참고하세요.
요금 카탈로그는 현재 요율만 나타내며 과거 청구를 다시 계산할 수 없습니다. 공개 API의 키 관리에서도 할당량 변경이나 폐기 키 복원은 지원하지 않습니다.
Webhook은 전용 설정 엔드포인트로 관리하며 일반 모델 키마다 하나의 설정을 가지고 키 생성, 수정과는 별도의 작업입니다. 자세한 내용은 Webhook 설정 조회를 참고하세요.