글 (Anthropic 형식) — /v1/messages
Anthropic Messages API 원형 그대로. Claude 전용입니다.
Anthropic SDK 와 Claude Code 가 쓰는 문이에요. base_url 만 저희 쪽으로 바꾸시면 몸통은 손댈 게 없어요. 응답도 Anthropic 형식 그대로 돌려드려요.
이 문을 Anthropic SDK 로 부르시면 오류는 Python 이 except anthropic.APIStatusError as e: 에서 e.status_code · e.body["error"]["type"] · e.body["error"].get("reason"), Node 가 err.status · err.error.error.type · err.error.error.reason 으로 읽어요(봉투 전체가 오니 error 를 한 번 더 들어가요 · SDK 동작). 문서 맨 위 규칙의 openai SDK 문장(e.type · e.body.get("reason"))은 이 SDK 엔 맞지 않아요 — 아래 「스트리밍」 절의 오류 봉투를 보세요. 머리글은 Node Anthropic SDK 도 err.headers.get("retry-after") · err.headers.get("x-should-retry") 로 읽어요 — Headers 객체라 err.headers["retry-after"] 는 undefined 예요. Python 은 e.response.headers.get("retry-after") 예요(SDK 동작).
curl https://oneport.kr/v1/messages \
-H "x-api-key: $ONEPORT_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "안녕하세요"}]
}'요청 파라미터#
요청 본문 (JSON) — Anthropic Messages 그대로
| 파라미터 | 받는 값 | 저희가 하는 일 |
|---|---|---|
| model필수 | Claude 모델 id | Claude 가 아니면 400 으로 어느 문으로 가야 하는지 알려드려요. 없는 이름이면 404 와 함께 가까운 이름을 드려요. |
| max_tokens필수 | 정수 | Anthropic 이 필수로 받아요. 이 문은 몸통을 번역 없이 넘기니 저희가 채워드리지 않아요 — /v1/chat/completions 쪽은 안 보내시면 8,192 로 채워드려요. 부르기 전에 max_tokens 만큼의 출력과 입력 몫을 크레딧에서 잠시 잡아둬요. 입력 몫은 count_tokens 로 센 수가 아니라 보내신 몸통(JSON) 바이트를 3으로 나눈 수를 토큰으로 어림해서, 센 수보다 크게 잡힐 수 있어요(바이트는 저희가 받은 JSON 을 공백 없이 다시 쓴 UTF-8 크기예요 — SDK 가 한글을 \uXXXX 로 보내도 같고, 한글은 글자당 3바이트예요 · base64 그림은 그 글자를 바이트에서 빼고 한 장마다 (글자 수 ÷ 3)과 4,800 가운데 작은 쪽을 토큰으로 더해요). 주소(source.type "url")로 붙인 그림은 한 장마다 4,800 토큰, 주소로 붙인 문서는 몇 개든 요청 하나에 모델 창의 1.05배(Claude 는 105만 토큰)를 더해서 줄이거나 나눠도 같아요 — 잔액 · 키 한도가 모자라면 문서를 base64 로 넣어 보내세요(2026-11-01 부터 · 402 · 429 문장 끝도 그렇게 말해요 · 숫자 예는 「남은 한도」 장 「최대 몫」). 단가는 cache_control 이 없으면 입력 단가예요. system · tools · messages 어디든 cache_control 이 한 곳이라도 있으면 입력 전체(캐시로 읽힐 몫까지)를 캐시 쓰기 단가로 잡아요 — 표시한 부분만이 아니에요. 그 단가는 아래 system 줄의 캐시 쓰기 단가(상위 구간이면 pricing.tier 의 cache_write_credits_per_mtok)이고, ttl "1h" 가 하나라도 있으면 입력 전체를 1시간 단가로 잡아요. 셈 전체는 「남은 한도」 장의 「최대 몫」이에요. 다만 claude-sonnet-5 · claude-opus-5-5 에 content 가 글자인 user 메시지 하나를 스트림 없이 보내면(위 「가장 짧은 호출」이 이 꼴이에요 · 칸은 model · messages · system · max_tokens 만 · 글 앞뒤 공백 없이 · @ 없이 · 머리글은 anthropic-version 을 안 싣거나 2023-06-01 로만 · anthropic-beta · openai-beta 없이 — 새 판 SDK 가 싣는 2026-10-21 이면 보통 셈이에요 · 몸통 16KB(16,384바이트) 이하 · max_tokens 32,768 이하 · user 글이 / 로 시작하지 않고 · system 은 글자일 때만이에요(@ 없이 — 블록 배열이면 보통 셈) · stream: false 는 실어도 같아요 — 그림 · PDF 블록이나 thinking · output_config 가 하나라도 있으면 보통 셈이에요) 바이트를 3으로 나누지 않고 (몸통 바이트 + 16,384) 토큰 × 입력 단가 × 2 + max_tokens × 출력 단가를 잡아요 — 「안녕하세요」 한 줄에 max_tokens 1,024 면 claude-sonnet-5 로 약 70 크레딧이에요(10월 단가). 이때 402 문장엔 「stream: true 로 보내거나」가 붙고 max_tokens 를 줄여도 거의 안 줄어요 — stream: true 로 보내면 위 보통 셈으로 잡아요. 키 · 강좌 한도(429)는 이때도 보통 셈이에요(조건 전부는 「남은 한도」 장). 잔액이 그보다 적으면 402 insufficient_credit 이고, 보통은 max_tokens 를 줄이면 풀려요. 실제로는 쓴 만큼만 크레딧을 사용해요. PDF 는 그림과 달리 쪽 수가 아니라 base64 바이트 ÷ 3 으로 잡아서 실제보다 훨씬 크게 잡힐 수 있어요 — 원본 2MB PDF 면 약 90만 토큰 몫이라 claude-sonnet-5 로 약 1,600 크레딧(cache_control 을 실으면 약 2,000)을 잠시 잡아요(10월 단가). 실제 사용은 Anthropic 이 센 토큰만큼이에요. 입력 어림도 105만 토큰까지만 잡아서(Claude 의 창 — GET /v1/models 의 context_window — 이 10월 기준 20만이든 100만이든 같아요 · 웹 검색 같은 서버 도구를 실으면 안 잘라요) 원본 약 2.4MB 를 넘는 PDF 도 입력 몫이 그 이상 커지지 않아요. 잔액이나 키 한도가 그보다 작으면 max_tokens 를 줄여도 402 · 429 예요(문장에 「미리 잡는 몫 대부분이 입력」이 붙어요) — PDF 를 줄이거나 쪽을 나눠 보내거나 충전하세요. 대화 기록에 PDF 가 남아 있으면 턴마다 다시 잡아요. 긴 입력 구간이 있는 모델(GET /v1/models 의 pricing.tier 가 있는 모델 — 10월 기준 claude-haiku-5-5 · above_input_tokens 100,001)은 몸통 바이트 ÷ 3 이 그 수 이상이면 미리 잡는 몫도 상위 구간 단가(tier 의 입력 · 출력 · 캐시 쓰기)로 잡아요. 원본 PDF 가 약 220KB 를 넘으면 그래요. 실제 사용은 Anthropic 이 센 토큰으로 구간을 정해요. |
| messages필수 | role · content 배열 | 이 문은 번역이 없어서 보내신 모양 그대로 Anthropic 에 닿아요. 이미지·문서 블록도 그쪽 문서대로 쓰시면 돼요 — PDF 는 {"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": …}} 예요. 요청 한 번은 몸통 전체(PDF · 그림 base64 · 지시문 · 스키마를 다 더해 보내신 그대로의 바이트)가 4.5MB(10진수 · 11-01 실측으로 몸통 약 4,490,000바이트에서 끊겨요)까지이고 base64 는 원본보다 3분의 4배(약 1.33배)쯤 커서, 원본이 3MB 를 넘는 PDF 는 413 이 날 수 있어요. 이 413 은 저희 코드에 닿기 전에 호스팅이 끊은 거라 JSON 이 아니라 영어 글자(text/plain)이고 request-id 머리글도 없어요 — 머리글 x-vercel-error 에 FUNCTION_PAYLOAD_TOO_LARGE 가 와요(10-31 실측). 상태 코드로 가르세요(Python Anthropic SDK 면 e.body 가 글자라 e.status_code == 413 으로, Node 면 err.error 가 비어 있어 err.status === 413 으로 · SDK 동작). 파일을 미리 올리는 /v1/files 와 묶음 처리 /v1/messages/batches 는 없어요(404). 메시지 안의 file_id 블록(source.type "file" · 도구 결과 안의 블록도)은 받지 않아요 — 모델 회사로 보내기 전 · 잡아 두기 전에 400 invalid_request_error 「받지 않는 칸이에요: file_id. 요청에서 빼고 다시 보내 주세요.」이고 요금은 없어요(2026-11-01 부터). 저희 문엔 파일을 올리는 길이 없어서 file_id 로 부를 파일이 없어요 — PDF · 그림은 base64 로 싣거나 주소(source.type "url")로 붙여요(주소 문서 몫은 위 max_tokens 줄). 스페이스 전송 정책 키는 그보다 먼저 403 space_content_policy 예요. |
| system | 문자열 또는 블록 배열 | OpenAI 형식과 달리 messages 안이 아니라 별도 필드예요. 그대로 넘어가니 캐시 제어(cache_control)도 그쪽 문서대로 쓰실 수 있어요. 1시간 캐시(ttl: "1h")와 anthropic-beta 머리글도 그대로 넘어가요. 캐시 쓰기는 5분이면 입력 단가의 1.25배, 1시간이면 2배예요 — GET /v1/models 의 pricing.rates 의 cache_write 는 5분 쓰기 단가이고, 1시간 쓰기 줄은 따로 없으니 input_text × 2 로 셈하세요. 캐시 읽기 배수는 모델마다 달라서 0.1배로 박아 두지 말고 GET /v1/models 의 pricing.rates(cache_read · cache_write)를 읽으세요 — 10월 기준 claude-sonnet-5 는 입력 단가의 0.1배, claude-sonnet-5-5 · claude-opus-5-5 는 0.05배예요(sonnet 둘은 입력 · 출력 단가가 같아도 캐시 읽기는 5-5 가 절반이라, 같은 PDF 를 여러 번 물을 땐 이 칸으로 고르세요). cache_control 을 실은 요청은 같은 지갑 · 같은 모델이면 저희가 같은 경로로 보내서 캐시가 이어져요 — 그 경로가 잠시 막혀 다른 경로로 돌면 그 호출은 캐시를 새로 써요(cache_creation_input_tokens 가 다시 커지면 그 경우예요). |
| tools | Anthropic 형식 도구 배열 | 직접 정의한 도구와 손님 쪽에서 도는 도구(bash · 편집기 · computer use 등)는 그대로 넘겨요. web_search 는 검색 1회 9.2 크레딧, advisor 는 조언 모델 토큰을 그 모델 단가로 같이 빼요. compaction(요약) 토큰도 같은 모델 단가로 빼요. 혼자 쓰는 code_execution 과 저희가 모르는 서버 도구는 벤더로 보내기 전에 400 으로 돌려드려요. 웹 검색은 Anthropic 도구 모양 그대로 실어요 — {"type": "web_search_20250305", "name": "web_search", "max_uses": 5}. type 은 web_search_<날짜> 판이면 그대로 넘기고, code_execution 은 web_search · web_fetch 20260209 이후 판과 같이 보낼 때만 받아요. 학생 키는 웹 검색 · 웹 페이지 읽기가 403 student_key_blocked 예요. |
| speed | "standard" | 빠른 모드("fast")는 아직 열려 있지 않아 벤더로 보내기 전에 400 으로 돌려드려요. 빼고 보내시면 같은 모델이 표준 속도로 답해요. |
| service_tier | "auto" · "standard_only" | 둘 다 표준 등급으로 답해요. 그 밖의 값은 벤더로 보내기 전에 400 으로 돌려드려요. |
| fallbacks | — | 서버측 폴백(베타 헤더 server-side-fallback-…)은 아직 열려 있지 않아 벤더로 보내기 전에 400 으로 돌려드려요 — 다른 모델이 대신 답하면 그 몫을 저희가 셀 수 없거든요. fallbacks 와 그 베타 헤더를 빼고 보내시면 요청하신 모델이 그대로 답해요. |
| thinking | Anthropic 형식 그대로 | 손대지 않고 넘겨요. 지금 모델(claude-sonnet-5 · claude-opus-5-5 등)은 {"type": "adaptive"} 만 받아요 — budget_tokens 를 넣으면 Anthropic 이 400 으로 돌려보내고, 저희는 그 문장을 400 upstream_error 로 그대로 전해 드려요. 생각의 깊이는 output_config.effort(low · medium · high · xhigh · max)로 정해 주세요 — claude-sonnet-4-6 · claude-opus-4-6 은 xhigh 를 안 받고, claude-haiku-4-5 · claude-sonnet-4-5 는 effort 를 안 받아요(GET /v1/models 의 supports_effort). |
| output_config | Anthropic 형식 그대로 | 손대지 않고 넘겨요 — 생각 깊이는 effort(위 thinking 줄), 정해진 JSON 모양은 format 이에요: {"format": {"type": "json_schema", "schema": {…}}}. /v1/chat/completions 가 response_format 을 Claude 로 옮길 때 싣는 꼴과 같아서, 지금 켜진 Claude 모델로 저희가 재 봤어요(10월). thinking · PDF · 그림 · cache_control 과 같이 실어도 저희는 따로 막지 않아요. 모델이 못 받는 스키마면 Anthropic 이 거절해 400 upstream_error 로 와요(벤더 동작). SDK 판이 이 칸을 모르면 Python 은 extra_body={"output_config": …} 로 싣고, Node 는 params 에 그대로 넣어요(TypeScript 면 형 변환 · SDK 동작). |
| 그 밖의 파라미터 | Anthropic 문서에 있는 것 — 위에서 400 이라고 적은 것 빼고 | 이 문은 몸통을 손대지 않아요 — tool_choice · thinking · 프롬프트 캐싱까지 Anthropic 문서 그대로 쓰시면 돼요. |
| anthropic-version · anthropic-beta (머리글) | Anthropic 문서 그대로 | anthropic-version 을 안 보내시면 2023-06-01 로 채워 넘겨요. 보내신 값과 anthropic-beta 는 그대로 넘겨요. 같은 Idempotency-Key 로 다시 보낼 땐 이 머리글도 처음 값 그대로예요 — 바꾸면 조회 주소 없는 409 idempotency_conflict 예요. 새 판 SDK 는 2026-10-21 을 실어요 — 판마다 다른 점은 아래 「anthropic-version 판」이에요. |
| temperature · top_p · top_k | 숫자 | Claude 5 세대(claude-sonnet-5 · claude-opus-5-5 · claude-haiku-5-5 등)와 claude-opus-4-7 · claude-opus-4-8 은 이 값을 안 읽어서, 어느 판이든 저희가 빼고 넘기고 응답 머리글 x-gateway-ignored-params 에 적어요. 그 밖의 Claude 는 2023-06-01 이면 그대로 넘기고, 2026-10-21 판이면 보내기 전에 400 invalid_request_error 예요(요금 없음 · 아래 「anthropic-version 판」). |
응답#
Anthropic Messages 응답 그대로예요. content 가 블록 배열이라 글만 쓰실 때도 content[0].text 처럼 꺼내셔야 해요 — 생각(thinking)을 켜면 첫 블록이 글이 아닐 수 있으니 type 으로 골라 쓰시는 편이 안전해요. 몸통은 그대로지만 응답 머리글은 저희가 새로 써요 — Anthropic 의 anthropic-ratelimit-* 머리글은 넘어오지 않고, content-type 과 x-gateway-fallback-depth · x-gateway-source 가 와요(표본 칸을 뺐으면 x-gateway-ignored-params 도). x-gateway-ignored-params 는 뺀 칸 이름을 쉼표로 이은 글(예: temperature,top_p)이고, x-gateway-fallback-depth 는 다른 경로로 다시 보낸 횟수(0 이면 처음 건 경로에서 답했어요)예요. x-gateway-source 는 저희 기록용 값이라 코드에서 가르지 마세요. request-id 는 와요 — Anthropic 이 준 값이 아니라 저희가 짓는 요청 ID 예요(같은 값이 x-request-id 로도 와요 · 성공 · 실패 · 스트림 모두). Idempotency-Key 로 접수한 요청에서는 영속 요청 ID이고 usage 원장 ID와는 별개예요. x-gateway-status-url · Location · error.status_url 은 /v1/requests/<id> 꼴의 상대 주소예요 — 앞에 https://oneport.kr 를 붙여 같은 API 키(Authorization: Bearer · x-api-key 둘 다 받아요)로 GET 해요(요금 없음 · 다른 API 키로는 404 — 「새로 받기」로 바꾼 새 API 키는 읽혀요). x-gateway-status-url 은 Idempotency-Key 를 실어 접수된 요청의 응답에 늘 와요(200 · 오류 모두 · 409 request_already_exists 도). 그중 실패 응답(422 upstream_execution_unconfirmed · 409 포함)엔 같은 값이 Location 머리글에도 오고, 몸통이 JSON 오류면 error.status_url 에도 와요(성공 응답엔 머리글에만). Idempotency-Key 없이 부른 호출엔 조회 주소가 없어요. 그런 호출의 422 는 request-id 와 부른 시각으로 문의해요. 조회 응답의 칸(execution · result.state · settlement)은 「요청 상태」 장(https://oneport.kr/docs/reference/requests.md)에 있어요. 일반 요청 ID로 조회 주소를 만들지 마세요. Anthropic SDK 는 이 값을 message._request_id(Python) · 오류의 request_id 로 읽어요(SDK 동작) — 문의하실 땐 이 값과 부른 시각을 알려 주세요. 몸통의 id(msg_…)는 그대로예요.
{
"id": "msg_...",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-5",
"content": [{ "type": "text", "text": "안녕하세요!" }],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 12, "output_tokens": 8,
"cache_creation_input_tokens": 0, "cache_read_input_tokens": 0,
"cache_creation": { "ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0 },
"server_tool_use": { "web_search_requests": 0 },
"cost_credits": 0.1196
}
}이 호출에 쓴 값은 usage.cost_credits 예요(웹 검색 요금까지 · 스트림은 끝 message_delta 의 usage · 정산이 2초 안에 안 끝나면 그 칸 없이 와요). Anthropic SDK 로 읽는 법이에요(SDK 동작). Python 은 getattr(message.usage, "cost_credits", None)(모르는 칸도 받아 둬요) · 요청 ID 는 message._request_id 예요. Node 는 (message.usage as any).cost_credits(TS 타입엔 없는 칸이라 형 변환해 읽어요) · 요청 ID 는 message._request_id 예요. 스트림이면 마지막 message_delta 이벤트의 event.usage 에서 cost_credits 를 읽어요(흐름 중간 이벤트엔 없어요) — 끝난 메시지를 모아 주는 get_final_message()(Node finalMessage())의 usage 엔 이 칸이 안 옮겨져요. 스트림의 요청 ID 는 Python 이 stream.response.headers["request-id"](messages.stream() 이면 stream.request_id), Node 가 messages.stream() 의 stream.request_id 나 messages.create({ …, stream: true }).withResponse() 의 response.headers.get("request-id") 예요. 그 칸이 없어 직접 셀 땐 웹 검색 요금은 usage.server_tool_use.web_search_requests 횟수로, 1시간 캐시 쓰기는 cache_creation.ephemeral_1h_input_tokens 로 셈해요.
토큰 미리 세기 — /v1/messages/count_tokens#
보낼 몸통을 POST /v1/messages/count_tokens 로 보내면 입력 토큰 수({"input_tokens": …})만 돌려드려요. 몸통은 손대지 않고 Anthropic 토큰 세기로 넘기니(스페이스 전송 정책을 켠 키면 /v1/messages 와 같이 가린 뒤에 넘기고, 정책이 막는 글 · 도구 · 그림은 403 space_content_policy · 스페이스에서 끈 모델은 403 model_disabled_in_space 예요) 그쪽이 받는 칸(model · messages · system · tools · tool_choice · thinking)만 보내 주세요 — max_tokens · stream 은 빼 주세요. 키는 필요하고 anthropic-version 은 안 보내셔도 돼요. temperature · top_p · top_k 는 /v1/messages 와 같은 규칙이에요(값을 안 읽는 모델은 빼고 x-gateway-ignored-params · 2026-10-21 판에 값을 읽는 모델은 400). Claude 모델만 받아요(다른 모델은 400 · 목록에 없는 id 는 404 model_not_found). Anthropic 이 거절하면 /v1/messages 와 같이 상태 코드 그대로 upstream_error 로 와요. 웹 검색 결과로 나중에 붙는 토큰과 캐시 할인은 이 수에 안 들어가요. 무료이고 크레딧을 쓰지 않아요. 잔액이 0 이어도 셀 수 있지만, 크레딧을 산 적이 없는 지갑(다 환불한 지갑 포함)의 키는 /v1/messages 처럼 403 model_not_in_plan 이에요(모델 회사로 보내기 전 · 요금 없음). 일시 실패는 503 api_error(「지금 토큰을 셀 수 없어요 …」 · 키를 잠깐 못 읽었을 때도)나 429 rate_limit_error 로 와요 — 503 api_error 엔 /v1/messages 처럼 Retry-After: 2(초)가 붙고, 429 rate_limit_error 엔 Anthropic 이 알려 준 값(1~60초로 맞춰요 · 값이 없으면 저희가 5초로 채워 보내요)이 붙어요 — 그만큼 기다렸다 다시 보내세요(Anthropic SDK 재시도를 켜 두셨으면 SDK 가 그 값만큼 기다렸다 다시 보내요 · SDK 동작). 재시도를 끈 코드라면 이 실패도 잡아 주세요 — 안 잡으면 토큰 세기 한 번의 일시 실패로 프로그램이 멈춰요. Claude Code 는 이 문으로 /context 와 첨부 크기를 정확히 세요. Anthropic SDK 의 messages.countTokens() 도 이 문을 불러요.
anthropic-version 판#
| 부르는 쪽 | 싣는 anthropic-version |
|---|---|
| Python anthropic 2.x · TypeScript @anthropic-ai/sdk 1.x · Go v2 · Ruby 2.x · PHP 1.x · Java 3.x · C# 13.x · ant CLI 2.x | 2026-10-21 |
| 그 이전 판 SDK · CLI | 2023-06-01 |
| 머리글 없이 직접 부르기(curl · fetch) | 없음 — 저희가 2023-06-01 로 채워요 |
2026-10-21 판에서 Anthropic 이 바꾼 것 셋이에요(벤더 동작). ① temperature · top_p · top_k 가 없어져서 기본값(1)을 실어도 400 이에요 — 값을 안 읽는 모델(위 「요청 파라미터」의 temperature 줄)은 저희가 빼고 넘기고, 값을 읽는 모델이면 보내기 전에 400 invalid_request_error 로 막아요(요금 없음). 빼시거나, 그 값이 꼭 필요하면 anthropic-version: 2023-06-01 을 주세요. ② assistant 메시지에 바로 넣은 document 블록은 400 이에요 — user 메시지로 옮겨 주세요. ③ user 메시지 text 블록에 비지 않은 citations 를 실으면 400 이에요 — 빼 주세요. ②③ 은 Anthropic 이 거절해서 400 upstream_error 로 와요. 토큰 세기(count_tokens)도 같아요. 출처는 Anthropic 문서 platform.claude.com/docs/en/api/versioning · migration-2026-10-21 이에요.
const client = new Anthropic({
apiKey: process.env.ONEPORT_API_KEY,
baseURL: "https://oneport.kr",
defaultHeaders: { "anthropic-version": "2023-06-01" },
});스트리밍#
stream: true 면 Anthropic 이벤트를 그대로 흘려드려요 — message_start · content_block_start/delta/stop · message_delta · message_stop, 사이사이 ping. 정상 흐름에는 임의 진행 이벤트를 더하지 않아요. message_delta 의 usage 는 누적값이에요 — 끝까지 흐르면 마지막 message_delta 의 usage 에 저희가 cost_credits 한 칸을 더해요(이 호출에 쓴 값 · 정산이 2초 안에 안 끝나면 없어요). 첫 응답(모델 회사가 응답 머리글을 보낼 때까지 — 스트림이 아니면 답이 다 만들어져야 머리글이 와요) 120초(한 경로가 실행 전 429 · 완전한 응답 본문의 Anthropic overloaded_error(529 등)로 거절해 다른 경로로 돌면 합쳐 최대 4분 · 120초를 넘기면 다른 경로로 다시 보내지 않아요) · 조각 사이 침묵 120초 · 시작부터 약 12분 50초에서 끊겨요 — 직접 짠 HTTP 클라이언트의 첫 응답(머리글) 시간 제한은 4분보다 넉넉히 두세요. 저희 시간 제한이나 벤더 연결 끊김으로 끊길 때는 마지막에 event: error(type api_error · 문장 「처리 시간을 넘어 답이 도중에 끊겼어요 …」 · 「답을 받던 중 연결이 끊겼어요 …」)가 오고 흐름이 닫혀요. 이 api_error 는 상태 코드로 온 503 api_error(보내기 전 일시 장애 · Retry-After 2초 · 그대로 다시)와 달라요 — 스트림 도중 온 event: error 는 type 과 상관없이(overloaded_error 여도) 잘린 답이고 message_start 의 입력 · 캐시는 이미 사용했어요. 처음부터 다시 보내지 말고 받은 글을 assistant 메시지로, 이어 써 달라는 user 메시지를 그 뒤에 붙여 새 Idempotency-Key 로 이어 받아요 — assistant 로 끝내면 지금 목록의 Claude 대부분이 400 이에요(Python Anthropic SDK 는 이때 e.status_code 가 처음 받은 200 이고, Node Anthropic SDK 는 err.status 가 비어 있어요 · SDK 동작). 첫 응답 전에 모델 회사로 보낸 결과를 확인하지 못한 시간 초과는 422 upstream_execution_unconfirmed 로 와요. 저희는 529 상태만으로는 다른 경로로 넘기지 않아요. 손님 쪽 연결이 먼저 끊기면 오류 프레임을 받지 못할 수 있고, 클라이언트에 따라 읽기 오류로도, 정상 종료로도 보여요. 어느 쪽이든 message_stop 을 못 받았으면 잘린 답이고, 그때까지 센 토큰만큼 크레딧을 사용해요.
오류도 Anthropic 봉투예요 — {"type": "error", "error": {"type": …, "message": …, "request_id": …}, "request_id": …}(요청 ID 는 머리글 request-id 와 같은 값이에요). Anthropic 의 실행 전 거절이 확인된 4xx 는 상태 코드를 그대로 두고 type 을 upstream_error 로 바꿔 드려요(Anthropic 이 돌려보낸 429 만 rate_limit_error — 저희 한도 429 는 key_limit_exceeded · group_limit_exceeded 이고 x-should-retry: false 가 붙어요 — error.reason 이 held_by_others 인 429 만 x-should-retry: true · Retry-After: 5 예요 · 「에러」 장). 같은 400 도 type 이 둘이에요 — 저희가 보내기 전에 막은 것은 invalid_request_error, Anthropic 이 거절한 것은 upstream_error(예: budget_tokens)예요. 실행 전 과부하가 확인되면(Anthropic 이 overloaded_error 본문으로 거절하면) 같은 모델의 다른 경로로 보내요. 모두 과부하면 마지막 경로가 준 5xx(보통 529)를 type upstream_error 로, x-should-retry: false 없이 드려요(overloaded_error 는 저희가 확인에 쓰는 Anthropic 값이라 type 으로 오지 않아요). 그래서 x-should-retry: false 없이 온 529 · 5xx upstream_error 는 실행 전 거절이 확인된 것(과부하 · 모델 회사에 닿기 전 연결 실패)이라, 기다렸다 같은 요청을 보내도 돼요(Idempotency-Key 를 실었으면 같은 키로) — 실행했을 수 있는 실패는 늘 422 예요. 529 의 Retry-After 는 Anthropic 이 기다릴 시간을 알려 줬을 때만 그 값(1~60초로 맞춰요)으로 붙어요 — 없으면 간격은 직접 정해요. 모델 회사로 보낸 뒤 408 · 실행 전 거절이 확인되지 않은 5xx(529 상태만 있고 거절 본문은 확인하지 못한 경우 포함) · 연결 끊김 · 시간 초과와 성공 머리글 뒤 JSON 유실은 422 upstream_execution_unconfirmed 로 와요. x-should-retry: false 가 붙고 Retry-After 는 없어요. 실행 여부가 불명하므로 자동 재전송하지 마세요. Idempotency-Key 를 실어 보낸 요청이면 받은 x-gateway-status-url 을 같은 API 키로 GET 조회하세요. Idempotency-Key 없이 보낸 요청엔 조회 주소가 안 오고 요청 ID 로 만든 주소로는 조회가 안 돼요 — 요청 ID 와 부른 시각을 admin@schoolorder.kr 로 알려 주세요. 답이 흐르기 시작한 뒤 Anthropic 이 보낸 event: error 는 손대지 않고 그대로 넘겨서 type 이 overloaded_error 처럼 Anthropic 값 그대로예요(그때도 message_stop 이 없으니 잘린 답). 벤더로 보내기 전에 막히는 것도 있어요 — 403 model_not_in_plan · student_key_blocked(학생 키로 웹 검색 · 웹 페이지 읽기) · model_disabled_in_space(스페이스에서 끈 모델)는 다시 보내도 같고, 503 api_error 는 저희 쪽에서 키 · 잔액 · 예약을 잠깐 못 읽은 일시 장애라 Retry-After: 2(초)만큼 기다렸다 그대로 다시 보내면 돼요. 첫 응답이 120초를 넘은 경우도 위의 실행 불명이에요. 다른 경로로 넘기다 처리 시간(약 4분)이 다 지나 보내지 못하면 504 upstream_error · error.reason "timeout" · x-should-retry: false 로 와요 — 모델이 실행하지 않은 실패라 요금은 없고, 잠시 뒤 한 번 직접 다시 보내면 돼요(Idempotency-Key 를 실었으면 같은 키로). Retry-After(초)는 잠시 뒤 그대로 다시 보낼 실패에만 와요 — Anthropic 이 조인 429 rate_limit_error 는 Anthropic 이 알려 준 값(1~60초로 맞춰요 · 값이 없으면 저희가 5초로 채워 보내요), 529 는 Anthropic 이 값을 줬을 때만 그 값, 402 · 429 의 error.reason held_by_others 는 5초, 503 api_error 는 2초예요(토큰 세기 문도 같아요 — 503 api_error 2초 · 429 rate_limit_error 는 Anthropic 값 · 없으면 5초). Anthropic SDK 는 429 · 5xx 를 다시 보낼 때 이 값만큼 기다려요(SDK 동작). Retry-After 가 없는 402 는 기다리지 말고 충전하거나 max_tokens 를 줄여요. 글 문(/v1/chat/completions · /v1/messages · /v1/responses)에 Idempotency-Key 를 실은 요청도 접수된 뒤 실행 전에 막힌 실패는 키 없는 호출과 같은 머리글로 와요. x-should-retry: false 없이 온 402 · 429 의 held_by_others · 429 rate_limit_error · 503 api_error · 529 · 그 밖의 5xx upstream_error 는 Retry-After 만큼 기다렸다 같은 Idempotency-Key · 같은 본문으로 다시 보내요(없으면 간격은 직접) — 접수가 풀려 새 요청 ID 로 다시 실행되고, 두 번 실행되지 않아요. 400 · 403 · 404 · 그 밖의 402 는 x-should-retry: false 가 없어도 그대로 다시 보내면 같아요 — 고친 요청엔 새 Idempotency-Key 를 써요(같은 Idempotency-Key 로 본문을 바꾸면 409 idempotency_conflict · 충전하거나 한도가 다시 열린 뒤 같은 요청이면 같은 Idempotency-Key). x-should-retry: false 면 같은 요청을 자동으로 다시 보내지 마세요(422 upstream_execution_unconfirmed 는 받은 x-gateway-status-url 을 GET · 모델 회사가 거절한 4xx upstream_error 는 고친 요청엔 새 Idempotency-Key). 다만 504 error.reason "timeout"(모델 회사가 실행하기 전에 저희 처리 기한 4분이 끝난 것 · 요금 없음 — 보낸 뒤 첫 응답을 120초 안에 못 받은 건 422 예요)과 조회 주소와 같이 온 503 request_state_unavailable · request_store_unavailable(접수 뒤 기록을 잠깐 못 읽은 것 — 모델 회사로 보내기 전에 멈췄으면 새로 실행되고, 아니면 409)은 둘 다 x-should-retry: false 가 붙고 Retry-After 가 없어 SDK 는 다시 보내지 않아요 — 코드가 몇 초 뒤 한 번 같은 Idempotency-Key · 같은 본문으로 다시 보내요. 조회 주소 없이 온 503 — api_error(API 키를 잠깐 못 읽은 「지금 이 키를 확인하지 못했어요」) · request_state_unavailable · request_store_unavailable(접수 기록을 잠깐 못 읽은 것) — 은 접수 전 실패라 Retry-After: 2 로 오니 새 Idempotency-Key 로 바꾸지 말고 같은 Idempotency-Key · 같은 본문으로 다시 보내요. 같은 Idempotency-Key · 같은 본문에 409 request_already_exists 가 오면 새 Idempotency-Key 로 바꾸지 말고 그 응답의 x-gateway-status-url 을 GET 해요. 작업 문(/v1/tasks)은 「작업」 장, 영상 문(/v1/videos)은 「영상」 장 규칙을 따라요. 다시 보내기 전에 x-gateway-status-url 을 GET 해 봐도 돼요 — execution 이 not_started 면 실행 전에 막힌 거예요(2026-10-29 전에 접수된 요청은 started 로 남아 있어서 http_status 가 402 · 429 · 503 · 504 · 529 면 모델이 실행하지 않은 거예요).
event: message_start
data: {"type":"message_start","message":{"id":"msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY","type":"message","role":"assistant","content":[],"model":"claude-sonnet-5","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":25,"output_tokens":1}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: ping
data: {"type":"ping"}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"안녕"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"하세요!"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":15}}
event: message_stop
data: {"type":"message_stop"}event: message_start
data: {"type":"message_start","message":{"id":"msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY","type":"message","role":"assistant","content":[],"model":"claude-sonnet-5","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":25,"output_tokens":1}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"안녕"}}
event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}이 문이 받는 모델#
이 문으로 부를 수 있는 건 아래 Claude 모델뿐이에요. GET /v1/models 의 endpoint 칸에 POST /v1/chat/completions 로 적혀 있어도 Claude 모델은 이 문으로 불러요.
긴 입력에 더 비싼 구간이 붙는 모델이 있어요 — 표의 「입력 …토큰 이상이면 · 초과면」 줄이고, GET /v1/models 의 pricing.tier(above_input_tokens 부터 그 요청 전체에 붙어요 · {above_input_tokens, input_credits_per_mtok, output_credits_per_mtok, note} 꼴)예요. 「초과면」도 같은 말이에요 — above_input_tokens 가 100001 인 모델은 표에 「입력 100K 토큰 초과면」으로 적혀요(100,001 토큰 이상과 같아요). 그 길이에는 캐시 읽기 · 쓰기 토큰도 들어가요. 긴 문서를 실을 땐 이 줄로 어림하세요.
글
| 모델 | 입력100만 토큰당 크레딧 | 출력100만 토큰당 크레딧 |
|---|---|---|
| claude-fable-5-2Claude Fable 5.2 | 7,358 | 36,792 |
| claude-fable-5-1Claude Fable 5.1 | 9,198 | 45,990 |
| claude-fable-5Claude Fable 5 | 9,198 | 45,990 |
| claude-opus-5-5Claude Opus 5.5 | 3,679 | 18,396 |
| claude-opus-5Claude Opus 5 | 4,599 | 22,995 |
| claude-sonnet-5-5Claude Sonnet 5.5 | 1,840 | 9,198 |
| claude-sonnet-5Claude Sonnet 5 | 1,840 | 9,198 |
| claude-haiku-5-5Claude Haiku 5.5입력 100K 토큰 초과면 입력 460 · 출력 2,300 | 92 | 460 |
| claude-sonnet-4-5Claude Sonnet 4.5 | 2,759 | 13,797 |