Claude API로 긴 답변을 받을 때, 전부 완성될 때까지 빈 화면에서 기다리면 사용자 경험이 나빠지고 연결이 끊길 위험도 있습니다. 스트리밍은 응답을 만들어지는 대로 조각조각 받아 바로 보여주는 방식입니다. 이 글은 Claude API 스트리밍을 켜는 법과 이벤트 흐름을 정리합니다. (공식 문서: docs.claude.com · 기준 시점: 2026년 6월)
스트리밍이란, 왜 쓰나
스트리밍은 서버가 응답을 SSE(server-sent events)로 잘게 나눠 보내고, 클라이언트가 도착하는 대로 처리하는 방식입니다. 다음 상황에서 특히 유용합니다.
- 채팅 UI — 타이핑되듯 글자가 흐르면 체감 속도가 빨라집니다.
- 긴 출력 — 큰
max_tokens응답은 한 번에 기다리면 타임아웃·연결 끊김 위험이 있어, 스트리밍이 권장됩니다. - 중간 표시 — 진행 상황을 즉시 보여줘야 할 때.
켜는 법: stream true
요청에 "stream": true를 넣으면 됩니다. curl 예시:
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"<모델 ID>","max_tokens":256,"messages":[{"role":"user","content":"안녕"}],"stream":true}'모델 ID는 변동되므로 모델 ID와 버전 관리 글과 공식 문서로 확인하세요.
SDK로 더 쉽게
공식 Python·TypeScript SDK는 스트리밍 헬퍼를 제공합니다. Python 예시(텍스트만 흘려 받기):
import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
max_tokens=1024,
messages=[{"role": "user", "content": "안녕"}],
model="<모델 ID>",
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)조각을 직접 다룰 필요가 없다면, SDK가 내부적으로 스트리밍하면서 완성된 Message 객체를 돌려주는 방법도 있습니다(예: Python get_final_message(), TypeScript finalMessage()). SDK 기본기는 SDK 시작하기를 참고하세요.
이벤트 흐름 이해하기
직접 API를 연동한다면 이벤트를 스스로 처리해야 합니다. 한 번의 스트림은 대략 이렇게 흐릅니다.
message_start— 빈 내용의 Message 객체로 시작- 콘텐츠 블록들 — 각 블록은
content_block_start→content_block_delta(여러 번) →content_block_stop message_delta— 마무리 단계의 변경 정보message_stop— 종료
중간에 ping 이벤트가 섞일 수 있습니다. 텍스트는 content_block_delta 안의 델타로 도착하며, 도구 사용·확장 사고 등은 델타 종류가 다를 수 있으니(예: 부분 JSON, 사고 델타) 공식 이벤트 문서를 함께 확인하세요.
주의할 점
- 연결 끊김 — 일부 네트워크는 유휴 연결을 끊습니다. 긴 작업은 스트리밍을 쓰고, 재시도 로직을 준비하세요(공식 SDK는 재시도를 일부 자동 처리).
- 델타 종류 — 텍스트만 이어붙이면 도구 입력·사고 내용이 누락될 수 있으니, 필요한 델타를 구분해 처리하세요.
- 모델·이벤트 변동 — 모델 문자열과 이벤트 세부는 바뀔 수 있으니 공식 문서가 기준입니다.
관련 가이드
API 첫 호출은 Claude API 시작하기, 비용 절감(프롬프트 캐싱·배치)은 비용 줄이기, 도구 사용은 Tool Use 가이드를 함께 보세요.
타임아웃(504)·한도(429) 등 에러 처리와 재시도는 에러와 레이트리밋 다루기에서 함께 다룹니다.
추론 과정(thinking)을 켜는 방법은 확장 사고 가이드에서 다룹니다.
모델 ID·이벤트 종류 등 세부 사항은 변동될 수 있으며, 가장 정확한 정보는 공식 문서(docs.claude.com)에서 확인하시기 바랍니다. 본 사이트는 Anthropic 공식 사이트가 아닙니다.