홈 / 학습 / Anthropic Python SDK: 설치, base_url 설정, 스트리밍 및 오류 처리
Python의 Claude. 우아한 리본 모양의 뱀 곡선이 코드 페이지를 감싸며 작은 API 소켓에 연결됩니다.

Anthropic Python SDK: 설치, base_url 설정, 스트리밍 및 오류 처리

이 anthropic 패키지는 Claude API용 Anthropic 공식 Python 클라이언트입니다. 인증, 재시도, 스트리밍 및 타입별 오류를 처리하며, Anthropic 호환 엔드포인트에서도 변경 없이 작동합니다. 다음을 설정하세요: base_url (또는 ANTHROPIC_BASE_URL). 나머지 코드는 그대로 유지됩니다.

설치

터미널
pip install anthropic

1.x 릴리스는 다음 환경에서 실행됩니다: httpx2 그리고 Python 3.10 이상이 필요합니다. 자체 HTTP 클라이언트를 전달하는 경우 SDK의 다음 항목을 사용하세요: DefaultHttpxClient 그러면 기본 타임아웃과 연결 한도가 유지됩니다.

클라이언트 생성

app.py
import anthropic

client = anthropic.Anthropic(
    api_key="your_key",   # default: ANTHROPIC_API_KEY
    base_url="https://aiprimetech.io",    # default: ANTHROPIC_BASE_URL, else https://api.anthropic.com
)

base_url 는 호스트 루트입니다. SDK가 다음 경로를 추가합니다: /v1/messages 자체적으로 추가하므로 https://aiprimetech.io/v1 를 사용하면 다음이 생성됩니다: /v1/v1/messages 및 404 page not found. 두 변수가 모두 환경에 설정되어 있으면 anthropic.Anthropic() 에는 인수가 전혀 필요하지 않습니다:

터미널
export ANTHROPIC_API_KEY=your_key
export ANTHROPIC_BASE_URL=https://aiprimetech.io

메시지 보내기

app.py
message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarise TCP slow start in two sentences."}],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

print(message.usage.input_tokens, message.usage.output_tokens)
print(message._request_id)   # log this with any failure report

content 는 블록(텍스트, 사고, 도구 사용)의 목록이므로 다음을 확인하세요: block.type 다음을 읽는 대신 content[0].text 무작정 읽지 마세요.

응답 스트리밍

stream.py
with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Write a short story about a lighthouse."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()

입력이 길거나 출력이 길거나 다음 값이 큰 경우에는 스트리밍을 사용하세요: max_tokens: 단일 비스트리밍 요청은 타임아웃 내에 완료되어야 하지만, 스트리밍은 그렇지 않습니다. messages.create(..., stream=True) 는 헬퍼가 필요하지 않을 때 원시 이벤트 이터레이터를 제공합니다.

비동기 클라이언트

async_app.py
import asyncio, anthropic

client = anthropic.AsyncAnthropic(base_url="https://aiprimetech.io")
limit = asyncio.Semaphore(3)   # stay within your key's concurrency

async def ask(question: str) -> str:
    async with limit:
        msg = await client.messages.create(
            model="claude-haiku-4-5",
            max_tokens=512,
            messages=[{"role": "user", "content": question}],
        )
        return next(b.text for b in msg.content if b.type == "text")

async def main():
    answers = await asyncio.gather(*(ask(q) for q in ["What is DNS?", "What is BGP?"]))
    print(answers)

asyncio.run(main())

세마포어는 중요합니다. 다음을 사용해 수백 개의 요청을 한꺼번에 보내는 것은 asyncio.gather 다음 오류의 가장 흔한 원인입니다: Concurrency limit exceeded Python 클라이언트에서 관찰되는 오류입니다.

시간 제한 및 재시도

기본값: 요청당 10분의 타임아웃과 지수 백오프를 적용한 2회의 자동 재시도입니다. SDK는 연결 오류, 408, 409, 429 및 5xx 응답을 재시도합니다. 타임아웃도 재시도하므로 최악의 경우 실제 경과 시간은 타임아웃에 시도 횟수를 곱한 값입니다.

app.py
client = anthropic.Anthropic(base_url="https://aiprimetech.io", timeout=60.0, max_retries=4)

# override for one call only
client.with_options(timeout=300.0).messages.create(
    model="claude-opus-5-5",
    max_tokens=4000,
    messages=[{"role": "user", "content": "Review this design doc..."}],
)

오류 처리

상태 예외 재시도 여부
400anthropic.BadRequestError아니요: 요청을 수정하세요
401anthropic.AuthenticationError아니요: 키가 잘못되었거나 누락되었습니다
403anthropic.PermissionDeniedError아니요
404anthropic.NotFoundError아니요: 모델 ID 또는 URL을 확인하세요
429anthropic.RateLimitError예, 잠시 기다린 후
5xx, 529 과부하 포함anthropic.InternalServerError예
네트워크 장애anthropic.APIConnectionError예
타임아웃anthropic.APITimeoutError예, 또는 스트리밍 사용
errors.py
try:
    message = client.messages.create(model="claude-sonnet-5", max_tokens=1024,
                                      messages=[{"role": "user", "content": "Hi"}])
except anthropic.NotFoundError as e:
    print("Bad model ID or URL:", e.message)
except anthropic.RateLimitError as e:
    print("Rate limited, retry after", e.response.headers.get("retry-after"))
except anthropic.APIStatusError as e:
    print(e.status_code, e.type, e.message)
except anthropic.APIConnectionError:
    print("Network problem")

구체적인 예외 클래스부터 처리하고 APIStatusError 는 마지막에 처리하세요. 포괄적인 단일 except 는 재시도할 만한 오류와 코드 변경이 필요한 오류의 차이를 가립니다. e.type 는 API의 오류 유형 문자열을 제공합니다. 예를 들면 rate_limit_error 또는 overloaded_error.

모델 ID

모델 ID 권장 용도
claude-sonnet-5코딩과 에이전트 작업의 기본 선택: 빠르고 성능이 뛰어나며 가격은 중간 수준입니다.
claude-opus-5-5더 어려운 추론, 대규모 리팩터링, 장시간 에이전트 실행.
claude-fable-5-1성능이 가장 뛰어나고 가격도 가장 높습니다. 가장 어려운 작업에 사용하세요.
claude-haiku-4-5저렴하고 빠름: 제목, 요약, 분류, 간단한 단계.

client.models.list() 는 엔드포인트가 제공하는 모델을 반환하므로 사용 전에 ID를 확인할 수 있습니다. ID는 표기된 그대로 사용하세요. 날짜 접미사는 붙이지 마세요.

게이트웨이 문제 해결

표시되는 내용 원인 해결 방법
NotFoundError 다음으로 바꾸세요: 404 page not found/v1 에서 base_url호스트 루트 사용
AuthenticationError프로세스에 키가 설정되지 않았거나 공백이 포함된 채 붙여넣어짐출력 len(os.environ["ANTHROPIC_API_KEY"])
RateLimitError: Concurrency limit exceeded for user동시에 처리 중인 요청이 너무 많음다음 항목: asyncio.Semaphore 위와 같이
APITimeoutError 장시간 작업에서비스트리밍 요청이 타임아웃을 초과함스트리밍을 사용하거나 다음 값을 늘리세요: timeout
InternalServerError: No available accounts일시적인 업스트림 용량 문제SDK가 재시도하도록 두세요. 다음 값을 늘리세요: max_retries
Insufficient account balance잔액 없음충전

모델 측 오류에 대한 자세한 내용: Claude API 오류 가이드.

자주 묻는 질문

Anthropic Python SDK는 어떻게 설치하나요?
pip install anthropic을 실행하세요. 1.x 버전은 Python 3.10 이상이 필요합니다.
Anthropic Python SDK에서 사용자 지정 기본 URL은 어떻게 설정하나요?
anthropic.Anthropic()에 base_url을 전달하거나 ANTHROPIC_BASE_URL을 설정하세요. 호스트 루트를 사용하세요. SDK가 /v1/messages를 추가합니다.
기본 타임아웃과 재시도 횟수는 어떻게 되나요?
요청당 10분이며, 연결 오류, 408, 409, 429 및 5xx에 대해 지수 백오프를 적용하여 2회 재시도합니다.
Python SDK에서 스트리밍은 어떻게 사용하나요?
with client.messages.stream(...) as stream:을 사용하고 stream.text_stream을 순회하세요. stream.get_final_message()는 전체 메시지를 반환합니다.
몇 분 만에 Claude 사용 시작하기

API 키를 발급받으세요 — Anthropic 계정이나 대기자 명단 등록이 필요하지 않습니다.

API 키 발급받기

AI Prime Tech는 독립적인 API 게이트웨이입니다. Anthropic과 제휴 관계가 없으며, Anthropic의 보증을 받거나 Anthropic의 리셀러로 활동하지 않습니다. Claude 및 관련 모델 이름은 각 소유자의 상표입니다.

더 많은 Claude API 가이드

Claude API 키 발급 방법Claude API 요금 해설Claude API를 가장 저렴하게 사용하는 방법Claude API로 Cursor 무제한 사용Claude Code 무제한 이용Claude API 게이트웨이와 Anthropic 직접 이용 비교OpenAI 호환 API를 통해 Claude 사용하기Claude 모델 해설: Claude Opus, Sonnet, Haiku, Fable 비교 — 모든 Claude API 모델, Anthropic 모델 이름 및 가격 (2026)암호화폐로 Claude API 요금 결제하기대기 명단 없이 Claude API 이용하기Claude 토큰 사용량을 줄이는 방법Claude API로 Cline 무제한 사용Claude API로 Roo Code 무제한 사용JetBrains IDE에서 Claude 무제한 사용Claude API로 Aider 무제한 사용하기VS Code에서 Claude 무제한 사용Claude용 OpenCode 구성: opencode.json 설정, 모델 및 일반적인 오류Claude에서 Hermes 에이전트 무제한 실행하기Claude에서 OpenClaw 무제한 실행하기Anthropic 호환 API의 의미Claude Code API 키 — ANTHROPIC_API_KEY: 발급 및 설정 방법과 대신 claude setup-token을 사용해야 하는 경우Claude Code API 비용 — 요금과 절감 방법Claude API 오류 설명: 서버 오류 500, 과부하 529, 사용량 제한 429, 잘못된 요청 400 — 각 오류의 해결 방법Claude API 크레딧 구매 방법 — 그리고 Claude 크레딧이 어떤 "Claude 계정 구매" 상품보다 나은 이유Claude 무료 API: 무료 Claude API 키가 있나요? 2026년에 실제로 무료인 것은 무엇인가요?Claude API와 Claude Pro/Max 구독 — 어떤 것을 선택할까요Claude에서 Codex CLI 실행하기Claude를 n8n에 연결하기LiteLLM을 Claude로 라우팅하기Kilo Code에서 Claude 사용하기GitHub Copilot에 Claude 연결하기게이트웨이를 통해 Zed를 Claude에 연결하기Cherry Studio를 Claude에 연결하기LangChain의 ChatAnthropic: 가져오기, base_url, 스트리밍, 도구 및 오류Vercel AI SDK로 Claude 사용하기: createAnthropic baseURL, 스트리밍 및 문제 해결Claude로 Factory Droid 실행하기Claude Code API 이해하기애플리케이션에 Claude API 통합하기Claude를 무제한으로 사용하는 방법 — 그리고 "Claude Code 크랙 버전"이 없는 이유

Claude API 가이드 더 보기

Anthropic 호환 API의 의미Claude API 크레딧 구매 방법Claude API를 가장 저렴하게 사용하는 방법Claude API 오류 설명: 서버 오류 500, 과부하 529, 사용량 제한 429, 잘못된 요청 400 — 각 오류의 해결 방법Claude 무료 API: 무료 Claude API 키가 있나요? 2026년에 실제로 무료인 것은 무엇인가요?애플리케이션에 Claude API 통합하기Claude 모델 해설: Claude Opus, Sonnet, Haiku, Fable 비교 — 모든 Claude API 모델, Anthropic 모델 이름 및 가격 (2026)Claude API 요금 해설Claude API 게이트웨이와 Anthropic 직접 이용 비교Claude API와 Claude Pro/Max 구독 — 어떤 것을 선택할까요암호화폐로 Claude API 요금 결제하기대기 명단 없이 Claude API 이용하기Claude Code API 이해하기Claude Code API 비용 — 요금과 절감 방법Claude Code API 키 — ANTHROPIC_API_KEY: 발급 및 설정 방법과 대신 claude setup-token을 사용해야 하는 경우Claude를 무제한으로 사용하는 방법Claude API 키 발급 방법Claude 토큰 사용량을 줄이는 방법OpenAI SDK로 Claude 사용하기: OpenAI 호환 엔드포인트, 스트리밍, 도구 및 제한게이트웨이를 통해 Claude와 함께 사용하는 Hermes Agent: 사용자 지정 제공업체 설정, 비용 관리 및 문제 해결Claude에서 OpenClaw 무제한 실행하기Claude API 무제한 액세스의 의미무제한 Claude API 키를 발급받는 방법Claude Code 무제한 사용 — 토큰 제한 없음Claude Opus 4.8 무제한 이용Claude 무제한 사용 — 요금제 및 가격게이트웨이를 통해 Claude와 함께 사용하는 Aider: ANTHROPIC_API_BASE, 구성 파일, architect 모드 및 문제 해결Cherry Studio를 Claude에 연결하기Claude Code 무제한 이용Claude API로 Cline 무제한 사용사용자 지정 제공업체와 함께 사용하는 Codex CLI: config.toml, GPT 및 Claude 모델, IDE 확장 프로그램 및 문제 해결Claude 무제한 이용으로 Cursor 실행하기Claude로 Factory Droid 실행하기게이트웨이를 통해 Claude와 함께 사용하는 GitHub Copilot Chat: Custom Endpoint 설정, 에이전트 모드 및 문제 해결JetBrains IDE에서 Claude 무제한 사용Kilo Code에서 Claude 사용하기LangChain의 ChatAnthropic: 가져오기, base_url, 스트리밍, 도구 및 오류LiteLLM을 Claude로 라우팅하기Claude를 n8n에 연결하기Claude용 OpenCode 구성: opencode.json 설정, 모델 및 일반적인 오류Claude API로 Roo Code 무제한 사용Vercel AI SDK로 Claude 사용하기: createAnthropic baseURL, 스트리밍 및 문제 해결VS Code에서 Claude 무제한 사용게이트웨이를 통해 Zed를 Claude에 연결하기