모델 고르기
모델 및 가격에서 Endpoints 열에 Anthropic Messages가 포함된 모델을 쓰세요. 2026년 10월 18일 기준 공개 가격표에서는 다음 모델이 해당됩니다.- Claude 모델:
claude-sonnet-5-5,claude-opus-5-5등 11개이며default토큰 그룹에 올라 있습니다. 전체 목록과 가격은 모델 및 가격의 Anthropic 항목을 참고하세요. glm-5.2: 이 페이지의 예제에서 사용합니다.default토큰 그룹에 올라 있으며, 이 프로토콜에서는 공식 Messages API와 매우 비슷하게 동작합니다.deepseek-v4-prodeepseek-v4-flash
Claude 모델은 2026년 10월 18일부터 다시 제공됩니다. 전환하기 전에 아래 Claude 모델 제한을 읽고, 자세한 내용은 공지를 확인하세요.
Claude 모델 제한
Claude 모델은 스트리밍, 도구 사용, 적응형 사고(adaptive thinking), 5분·1시간 수명의 프롬프트 캐싱, 이미지 입력을 지원합니다. Anthropic 자체 API와 다르게 동작하는 부분이 몇 가지 있습니다.- 출력 길이: 응답 하나는 32,768토큰으로 제한됩니다. 더 큰
max_tokens는 이 한도로 줄어듭니다. - PDF와 문서:
document콘텐츠 블록은 지원하지 않습니다. 텍스트를 먼저 추출해text블록으로 보내세요. - 서버 도구:
web_search,web_fetch,code_execution같은 Anthropic 서버 도구는 지원하지 않으며, 이를 선언한 요청은 400을 반환합니다. - 그 밖의 엔드포인트:
/v1/messages/count_tokens, Message Batches, Files API는 사용할 수 없습니다. - 중단 시퀀스: 중단 시퀀스가 일치하면
stop_reason은end_turn,stop_sequence는null입니다. - 긴 Haiku 프롬프트:
claude-haiku-5-5프롬프트가 캐시 읽기와 쓰기를 포함해 100,000토큰을 넘으면, 요청 전체가 카탈로그의 구간별 가격에 표시된 긴 컨텍스트 요금으로 과금됩니다.
메시지 보내기
토큰 관리에서 과금 방식을 사용량 우선(콘솔 표시: 按量优先, 권장) 또는 사용량 과금(按量计费)으로 설정해 API 키(콘솔에서는 ‘토큰’이라고 부릅니다)를 만들고, 터미널에서 환경 변수로 설정하세요.- cURL
- Python
connected여야 합니다.
SDK가 API 키와 anthropic-version 헤더를 대신 보내고 base URL 뒤에 /v1/messages를 붙이므로, base_url에는 /v1을 넣지 마세요.
시스템 지시문은 system 역할의 메시지가 아니라 최상위 system 필드에 넣습니다.
messages는 user와 assistant 턴이 번갈아 나옵니다. 대화를 이어 가려면 이전 턴들을 보낸 다음 새 user 메시지를 추가하세요.
응답 읽기
읽어야 할 필드만 줄인 응답 예시입니다.content는 블록 목록이며 하나의 답변에 여러 블록이 들어 있을 수 있습니다. content[0]이 텍스트라고 가정하지 말고 type별로 읽으세요.
stop_reason은 답변이 끝난 이유를 알려 줍니다.
end_turn: 답변이 완결되었습니다.max_tokens: 출력 제한 때문에 잘렸습니다.tool_use: 모델이 도구 결과를 기다리고 있습니다.
usage에 있고, 요청별 청구 금액은 호출 로그에서 확인합니다.
응답 스트리밍
"stream": true를 추가하면 답변을 서버 전송 이벤트(SSE)로 받습니다.
텍스트는 delta.type이 text_delta인 content_block_delta 이벤트로 도착하며, 스트림은 message_stop 이벤트로 끝납니다.
- cURL
- Python
-N은 cURL의 출력 버퍼링을 꺼서 각 이벤트가 도착하는 즉시 출력되게 합니다.- 블록
index별로text_delta조각을 이어 붙이면 답변이 됩니다. - 추론과 도구 입력은 다른 delta 타입을 쓰고 스트림에
ping이벤트가 들어갈 수도 있으므로, 처리하지 않는 이벤트 타입은 건너뛰세요. - Python의
text_stream은 텍스트만 반환하고message_stop뒤에 끝납니다. message_stop전에 연결이 닫히면 답변이 불완전한 것으로 처리하세요.
도구 사용
tools 배열에 정의한 도구는 LaoZhang API가 아니라 내 애플리케이션에서 실행됩니다. 답변이 stop_reason: "tool_use"로 끝나면 다음 순서로 처리합니다.
- 각
tool_use블록의id,name,input을 읽습니다. - 코드에서 해당하는 함수를 실행합니다.
- 어시스턴트 턴을 그대로 둔 채, 호출마다
tool_result블록 하나씩을 담은user턴을 이어 붙여 다음 요청을 보냅니다. 각tool_use_id는 응답하는 호출의id와 일치해야 합니다.
messages 배열은 다음과 같습니다.
tools를 보내고, 어시스턴트 턴은 반환된 그대로 유지하세요.
web_search_*, code_execution_* 같은 Anthropic 서버 도구 타입은 게이트웨이가 실행하지 않습니다. Claude 모델은 이를 선언한 요청을 400 오류로 거부합니다. 다른 모델은 검색이나 코드 실행 없이 호출을 일반 tool_use 블록으로 반환합니다. 이런 호출은 클라이언트 도구처럼 애플리케이션에서 처리하거나, 요청에서 해당 도구를 빼세요.
Claude Code에서 사용하기
Claude Code는 Anthropic Messages 형식을 사용합니다.ANTHROPIC_BASE_URL을https://api.laozhang.ai(/v1이 없는 호스트 루트)로 설정합니다.- Endpoints에 Anthropic Messages가 포함된 모델을 고르세요.
claude-sonnet-5-5,glm-5.2가 있으며 둘 다default토큰 그룹에서 쓸 수 있습니다. - 과금 방식이 사용량 우선인
default그룹의 키를 쓰세요. 이전에Claude Code그룹(구 claude_code)에서 만든 키는 계속 작동하며, 새 키는 그 그룹이 필요하지 않습니다.
~/.claude/settings.json 예시는 LaoZhang API로 Claude Code 설정하기를 참고하세요. Claude Code가 400 ValidationException을 반환한다면 Claude Code 400 ValidationException 해결을 보세요.
오류 해결
- 401:
Authorization: Bearer헤더를 확인하고, 계정 AccessToken이 아니라 토큰 관리의 모델 API 키를 사용하세요. max_tokens가 언급된 400:max_tokens를 추가하세요. Chat Completions와 달리 Messages 요청에는 필수입니다.- 요청 URL에
/v1/v1/messages가 있음: SDK base URL이/v1로 끝납니다.https://api.laozhang.ai로 설정하세요. - 404 또는 모델을 찾을 수 없음: 정확한 모델 ID를 확인하고, 모델 및 가격에서 내 토큰 그룹에 Anthropic Messages가 표시되어 있는지 확인하세요.
- Claude Code가
400 ValidationException또는Extra inputs are not permitted를 반환: Claude Code 400 ValidationException 해결을 따르세요. - Claude 모델에서
web_search등 서버 도구를 선언한 뒤 400:tools에서 서버 도구를 빼세요. 검색은 애플리케이션에서 실행하고 결과를tool_result블록으로 돌려주세요. - 업스트림 혼잡 메시지가 있는 529: 피크 시간에 용량이 부족한 경우입니다. 잠시 기다렸다가 다시 시도하세요. Anthropic SDK는 기본적으로 529를 자동 재시도합니다.