API 레퍼런스
이 페이지에는 엔드포인트들이 공통으로 쓰는 내용을 모았습니다. Base URL, 인증, 여러 엔드포인트가 함께 받는 파라미터, 응답 형식, 스트리밍, 게이트웨이가 반환하는 에러와 적용하는 제한입니다. 아래 각 엔드포인트 페이지에는 그 엔드포인트에만 해당하는 내용만 두고, 나머지는 이 페이지를 참조합니다.
Base URL
https://api.bricksum.com/v1아래의 모든 경로는 이 Base URL 기준입니다. Anthropic SDK는 /v1을 직접 붙이므로 https://api.bricksum.com을 지정하세요.
인증
API 키를 Authorization 헤더에 Bearer 토큰으로 보내세요. x-api-key 헤더는 Authorization이 없을 때만 읽습니다. 둘 다 있으면 Authorization을 사용하며, Authorization 값이 Bearer 토큰 형식이 아니면 x-api-key로 넘어가지 않고 거부합니다. 사용할 수 있는 키가 없는 요청은 엔드포인트에 도달하기 전에 401로 거부됩니다.
게이트웨이는 anthropic-version과 anthropic-beta 헤더를 읽지 않으므로, 이 헤더가 있든 없든 요청을 같은 방식으로 처리하며 ?beta=true 같은 쿼리 문자열도 수락합니다. 위 규칙의 예외는 GET /key 하나입니다. 이 경로는 Kiln API가 처리하고 키를 Bearer 토큰으로만 받으며, 해당 페이지에 따로 정리했습니다. 인증
엔드포인트
현재 제공하는 엔드포인트입니다. 클라이언트가 이미 쓰는 형식에 맞춰 고르세요. 게이트웨이는 모두 같은 방식으로 계측합니다.
| 엔드포인트 | 형식 | 스트리밍 | 쓰임 |
|---|---|---|---|
| POST/chat/completions | OpenAI | data: 청크 | 대화와 툴 호출에 사용합니다. 대부분의 OpenAI 클라이언트가 쓰는 엔드포인트입니다. |
| POST/completions | OpenAI | data: 청크 | 프롬프트에 이어지는 텍스트를 생성합니다. 대화와 툴 호출은 지원하지 않습니다. |
| POST/responses | OpenAI | 타입이 있는 이벤트 | Responses 형식입니다. Codex CLI가 사용합니다. 상태를 저장하지 않으므로 매번 전체 대화를 input에 담아 보냅니다. |
| POST/messages | Anthropic | 타입이 있는 이벤트 | Anthropic Messages 형식입니다. Claude Code가 사용합니다. chat completions로 변환해 같은 방식으로 계측합니다. |
| POST/messages/count_tokens | Anthropic | 없음 | Messages 요청의 입력 토큰 수를 셉니다. 추론을 실행하지 않으며 과금되지 않습니다. |
| GET/models | OpenAI | 없음 | 게이트웨이가 지금 서빙할 수 있는 모델 ID 목록입니다. 과금되지 않습니다. |
| GET/key | Kiln | 없음 | 호출에 사용한 키의 프로젝트, 상태, 지출 한도, 만료, 사용액입니다. 게이트웨이가 아니라 Kiln API가 처리합니다. |
공통 요청 파라미터
여러 엔드포인트가 함께 받는 요청 파라미터입니다. 여기에 한 번만 정리했으며, 각 엔드포인트 페이지에는 이름과 그 엔드포인트에서 다른 점만 적었습니다.
지원 상태
- 지원
- 게이트웨이가 처리하거나, 공개된 실측에서 동작이 확인된 항목입니다.
- 전달만 함
- 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
- 무시됨
- 200으로 수락되지만 적용되지 않습니다. 응답의 나머지는 정상입니다.
- 미지원
- 에러로 거부되거나, 설명에 적힌 모델에서 동작하지 않습니다.
modelstring지원모델 ID입니다(예: qwen3-32b). 보낼 수 있는 ID는 GET /models로 조회합니다. 카탈로그에 없는 ID는 모델에 도달하기 전에 거부됩니다. OpenAI 형식 엔드포인트는 404(model_not_found), Anthropic 형식 엔드포인트는 404(not_found_error)로 응답합니다.
messagesarray필수지원지금까지의 대화입니다. 오래된 메시지부터 순서대로 넣습니다. 배열이 비어 있거나 없으면 400으로 거부되며 과금되지 않습니다. 메시지는 role과 content로 이루어지며, content가 가질 수 있는 형태는 OpenAI 형식과 Anthropic 형식 엔드포인트가 서로 다르므로 각 엔드포인트 페이지에 정리했습니다.
max_tokensinteger지원생성할 최대 토큰 수입니다. reasoning 토큰도 포함되므로 여유 있게 설정하세요. 상한에 걸렸을 때의 동작과 이 필드가 없을 때의 동작은 엔드포인트마다 다릅니다.
streamboolean지원true이면 응답이 하나의 JSON 본문 대신 server-sent events 스트림이 됩니다. JSON boolean으로 보내세요. OpenAI 형식 엔드포인트는 data: 줄을 보내고 data: [DONE]으로 스트림을 끝내며, Anthropic 형식의 Messages 엔드포인트는 타입이 있는 이벤트를 보냅니다.
- 기본값
- false
toolsarray지원모델이 호출할 수 있는 함수 정의입니다. 각 정의에는 이름, description, 인자의 JSON Schema가 필요하며, 필드 이름은 두 형식이 서로 다릅니다. 어느 모델이 어떤 툴 선택 방식을 적용하는지는 모델 페이지의 지원 기능 표에 있습니다.
tool_choicestring | object지원모델이 툴을 호출해야 하는지 지정합니다. 자동 툴 선택은 모델이 결정합니다. 강제 툴 선택은 모든 모델에서 적용되지는 않으며, 어느 모델이 어떤 방식을 적용하는지는 모델 페이지의 지원 기능 표에 있습니다. qwen3-32b에서는 강제 툴 선택이 명확한 에러 없이 실패합니다(2026-09-26 실측). tool_choice를 "required"로 보내면 본문이 평문 "Internal Server Error"인 HTTP 500이 오고, 함수를 지정하면 arguments가 빈 200(finish_reason "stop")이 옵니다. 둘 다 4xx가 아니므로 재시도로 해결되지 않습니다. tool_choice는 "auto"만 보내세요.
어느 엔드포인트가 이 파라미터들을 받는지, 그 엔드포인트에서 필수인지는 해당 엔드포인트 페이지에 있습니다. 엔드포인트 페이지에 없는 파라미터는 보낸 값 그대로 모델 서버로 전달되며, Kiln이 동작을 검증하지 않았습니다.
응답 형식
요청이 성공하면 해당 엔드포인트 형식의 JSON 본문과 함께 200으로 응답합니다. 계측 대상 엔드포인트에서 공통인 항목은 두 가지입니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| usage | object | 이 요청의 토큰 수입니다. 필드 이름은 엔드포인트 형식을 따르며 각 엔드포인트 페이지에 정리했습니다. 크레딧에서 차감되는 금액(USD)인 usage.cost는 OpenAI 형식의 JSON 응답과 Chat completions·Completions 스트림의 마지막 청크에 게이트웨이가 추가합니다. Responses의 스트림 이벤트와 Messages 응답에는 토큰 수만 담기고 cost 필드는 없습니다. |
| X-Neocloud-Generation-Id | header | 이 요청의 usage 이벤트 ID를 담은 응답 헤더입니다. 로그와 함께 저장하세요. 추론을 실행하지 않는 GET /models와 POST /messages/count_tokens는 usage 이벤트를 발행하지 않으므로 이 헤더도 보내지 않습니다. |
스트리밍
stream: true이면 응답이 server-sent events 스트림이 됩니다. OpenAI 형식 엔드포인트는 청크마다 data: 줄을 하나씩 보내고 data: [DONE]으로 끝내며, Responses와 Messages는 event: 줄과 이어지는 data: 줄로 이루어진 타입이 있는 이벤트를 보냅니다. 어느 쪽이든 생성이 끝날 때까지 연결이 열려 있으므로, 긴 요청이 아래의 타임아웃에 걸리지 않습니다. 청크 필드와 이벤트 타입은 각 엔드포인트 페이지에 있습니다. 스트리밍
게이트웨이가 반환하는 에러
아래 에러는 요청이 엔드포인트에 도달하기 전에 게이트웨이가 반환하므로, 게이트웨이가 처리하는 모든 엔드포인트에서 같은 형태로 나타납니다. 메시지 문구가 아니라 HTTP 상태로 분기하세요. 잘못된 요청 본문, 없는 모델 ID, 잘못된 메서드처럼 엔드포인트가 직접 반환하는 에러는 각 엔드포인트 페이지에 있고, 전체 상태 코드는 에러 페이지에 있습니다. 에러
| 상태 | 원인 | 조치 |
|---|---|---|
| 401 | API 키가 없거나 형식이 잘못되었거나, 등록되지 않았거나 만료되었습니다. | x-api-key 또는 Authorization 헤더와 키 만료일을 확인하세요. |
| 402 | 크레딧이 소진되었거나, 조직이 월 예산에 도달했거나, 키가 지출 한도에 도달했습니다. | 충전하거나, 관리자에게 예산 또는 한도 상향을 요청하세요. |
| 403 | API 키가 정지되었거나 폐기되었습니다. | 콘솔에서 키를 다시 활성화하거나 새 키를 만드세요. |
| 429 | 조직의 분당 요청 수 또는 분당 토큰 수 한도를 초과했습니다. | x-ratelimit-reset 초만큼 기다린 뒤 재시도하세요. |
제한
- 컨텍스트 길이: 모델마다 다르며 프롬프트와 출력을 합친 값입니다. 모델별 값은 모델 페이지에 나옵니다. 이를 넘는 요청은 400으로 거부됩니다.
- 요청 본문: 게이트웨이는 앞에서부터 최대 8 MiB까지만 읽습니다. 본문을 그보다 작게 유지하세요.
- 타임아웃: 게이트웨이는 요청을 60분 뒤에 종료합니다. 비스트리밍 요청은 완료될 때까지 바이트를 보내지 않으며, 네트워크 엣지가 이런 연결을 약 100초 뒤에 끊을 수 있습니다. 긴 생성은 stream: true로 보내세요.
- 조직별 레이트 리밋: 기본 분당 60회 요청, 설정된 경우 분당 토큰 수 한도, 동시 요청 8개입니다.
429의 헤더와 재시도 방법은 레이트 리밋 페이지에 있습니다.
현재 서빙 스택은 모든 OpenAI 파라미터를 적용하지는 않습니다. 각 엔드포인트 페이지에 파라미터별 지원 상태를 표시했고, 알려진 제한은 OpenAI에서 옮겨오기 페이지 한 곳에 정리해 두었습니다.