claude-api

name	claude-api
description	Python과 TypeScript용 Anthropic Claude API 패턴입니다. Messages API, streaming, tool use, vision, extended thinking, batches, prompt caching, Claude Agent SDK를 다룹니다.
origin	ECC

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은 큰 고정 프롬프트에만 적용합니다
• 배치는 고지연 허용, 대량 처리에서만 가치가 큽니다