claude-api

Claude API

Anthropic Claude API와 SDK로 애플리케이션을 만들 때 사용하는 스킬입니다.

활성화 시점

• Claude API를 호출하는 애플리케이션을 만들 때
• 코드에 anthropic 또는 @anthropic-ai/sdk가 등장할 때
• 사용자가 Claude API 패턴, tool use, streaming, vision을 물을 때
• Claude Agent SDK 기반 agent workflow를 구현할 때
• API 비용, 토큰 사용량, 지연 시간을 최적화할 때

모델 선택

Model	ID	Best For
Opus 4.1	claude-opus-4-1	복잡한 추론, 아키텍처, 리서치
Sonnet 4	claude-sonnet-4-0	균형 잡힌 코딩, 대부분의 개발 작업
Haiku 3.5	claude-3-5-haiku-latest	빠른 응답, 대량 처리, 비용 민감 작업

기본은 Sonnet 4입니다.

Python SDK

설치

pip install anthropic

기본 메시지

import anthropic

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-sonnet-4-0",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain async/await in Python"}]
)

Streaming

with client.messages.stream(...) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

System Prompt

message = client.messages.create(
    model="claude-sonnet-4-0",
    system="You are a senior Python developer. Be concise.",
    messages=[...]
)

TypeScript SDK

설치

npm install @anthropic-ai/sdk

기본 메시지

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const message = await client.messages.create({
  model: "claude-sonnet-4-0",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Explain async/await in TypeScript" }],
});

Streaming

const stream = client.messages.stream({...});
for await (const event of stream) {
  ...
}

Tool Use

도구를 정의하고 Claude가 호출하게 할 수 있습니다.

핵심 흐름:

1. tool schema 정의
2. messages.create(... tools=...) 호출
3. 응답의 tool_use 블록 감지
4. 실제 도구 실행
5. tool_result와 함께 후속 메시지 전송

Vision

이미지를 base64로 보내 분석할 수 있습니다.

Extended Thinking

복잡한 추론 작업에는 thinking budget을 켤 수 있습니다.

Prompt Caching

큰 system prompt나 컨텍스트는 cache_control로 캐싱해 비용을 줄일 수 있습니다.

Batches API

대량 비동기 처리에는 batch API를 사용합니다. 반복 요청을 묶어 비용을 줄이고, 완료 시 결과를 회수합니다.

실전 원칙

• production에서는 alias보다 pin된 snapshot model ID를 선호합니다
• 도구 스키마는 엄격하게 유지합니다
• streaming은 UX를 개선하지만 취소/오류 처리를 반드시 둡니다
• vision 입력은 크기와 토큰 비용을 의식합니다
• prompt caching은 큰 고정 프롬프트에만 적용합니다
• 배치는 고지연 허용, 대량 처리에서만 가치가 큽니다