메시지를 생성할 때 "stream": true를 설정하여 서버 전송 이벤트(SSE)를 사용해 응답을 점진적으로 스트리밍할 수 있습니다.

​
SDK를 사용한 스트리밍

우리의 Python과 TypeScript SDK는 여러 가지 스트리밍 방법을 제공합니다. Python SDK는 동기 및 비동기 스트림을 모두 지원합니다. 자세한 내용은 각 SDK의 문서를 참조하세요.

​
이벤트 유형

각 서버 전송 이벤트는 명명된 이벤트 유형과 관련 JSON 데이터를 포함합니다. 각 이벤트는 SSE 이벤트 이름(예: event: message_stop)을 사용하고, 데이터에 일치하는 이벤트 type을 포함합니다.

각 스트림은 다음과 같은 이벤트 흐름을 사용합니다:

  1. message_start: 빈 content를 가진 Message 객체를 포함합니다.
  2. 일련의 콘텐츠 블록으로, 각각 content_block_start, 하나 이상의 content_block_delta 이벤트, 그리고 content_block_stop 이벤트를 가집니다. 각 콘텐츠 블록은 최종 Message content 배열에서의 위치에 해당하는 index를 가집니다.
  3. 하나 이상의 message_delta 이벤트로, 최종 Message 객체의 최상위 변경 사항을 나타냅니다.
  4. 최종 message_stop 이벤트.

​
Ping 이벤트

이벤트 스트림에는 여러 개의 ping 이벤트가 포함될 수 있습니다.

​
오류 이벤트

때때로 이벤트 스트림에서 오류가 전송될 수 있습니다. 예를 들어, 사용량이 많은 기간 동안에는 비스트리밍 컨텍스트에서 일반적으로 HTTP 529에 해당하는 overloaded_error를 받을 수 있습니다:

오류 예시
event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

​
기타 이벤트

우리의 버전 관리 정책에 따라 새로운 이벤트 유형이 추가될 수 있으며, 코드는 알 수 없는 이벤트 유형을 적절히 처리해야 합니다.

​
델타 유형

각 content_block_delta 이벤트는 주어진 index의 content 블록을 업데이트하는 유형의 delta를 포함합니다.

​
텍스트 델타

text 콘텐츠 블록 델타는 다음과 같습니다:

텍스트 델타
event: content_block_delta
data: {"type": "content_block_delta","index": 0,"delta": {"type": "text_delta", "text": "ello frien"}}

​
입력 JSON 델타

tool_use 콘텐츠 블록의 델타는 블록의 input 필드에 대한 업데이트에 해당합니다. 최대한의 세분화를 지원하기 위해 델타는 _부분 JSON 문자열_인 반면, 최종 tool_use.input은 항상 _객체_입니다.

Pydantic과 같은 라이브러리를 사용하여 부분 JSON 파싱을 하거나, 파싱된 증분 값에 접근하기 위한 헬퍼를 제공하는 우리의 SDK를 사용하여 문자열 델타를 누적하고 content_block_stop 이벤트를 받으면 JSON을 파싱할 수 있습니다.

tool_use 콘텐츠 블록 델타는 다음과 같습니다:

입력 JSON 델타
event: content_block_delta
data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}

참고: 현재 모델은 input에서 하나의 완전한 키와 값 속성만 방출하는 것을 지원합니다. 따라서 도구를 사용할 때 모델이 작업하는 동안 스트리밍 이벤트 사이에 지연이 있을 수 있습니다. input 키와 값이 누적되면, 향후 모델에서 더 세밀한 단위를 자동으로 지원할 수 있도록 여러 개의 content_block_delta 이벤트로 청크된 부분 json을 방출합니다.

​
사고 델타

확장된 사고를 스트리밍이 활성화된 상태로 사용할 때, thinking_delta 이벤트를 통해 사고 내용을 받게 됩니다. 이러한 델타는 thinking 콘텐츠 블록의 thinking 필드에 해당합니다.

사고 콘텐츠의 경우, content_block_stop 이벤트 직전에 특별한 signature_delta 이벤트가 전송됩니다. 이 서명은 사고 블록의 무결성을 확인하는 데 사용됩니다.

일반적인 사고 델타는 다음과 같습니다:

사고 델타
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

서명 델타는 다음과 같습니다:

서명 델타
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

​
Raw HTTP 스트림 응답

스트리밍 모드를 사용할 때는 우리의 클라이언트 SDK를 사용하는 것을 강력히 권장합니다. 하지만 직접 API 통합을 구축하는 경우에는 이러한 이벤트를 직접 처리해야 합니다.

스트림 응답은 다음으로 구성됩니다:

  1. message_start 이벤트
  2. 잠재적으로 여러 콘텐츠 블록이 포함되며, 각각은 다음을 포함합니다: a. content_block_start 이벤트 b. 잠재적으로 여러 content_block_delta 이벤트 c. content_block_stop 이벤트
  3. message_delta 이벤트
  4. message_stop 이벤트

응답 전체에 ping 이벤트가 분산되어 있을 수 있습니다. 형식에 대한 자세한 내용은 이벤트 유형을 참조하세요.

​
기본 스트리밍 요청

요청
curl https://api.anthropic.com/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --data \
'{
  "model": "claude-3-7-sonnet-20250219",
  "messages": [{"role": "user", "content": "Hello"}],
  "max_tokens": 256,
  "stream": true
}'
응답
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-3-7-sonnet-20250219", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

​
도구 사용이 포함된 스트리밍 요청

이 요청에서는 Claude에게 도구를 사용하여 날씨를 알려달라고 요청합니다.

요청
  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "claude-3-7-sonnet-20250219",
      "max_tokens": 1024,
      "tools": [
        {
          "name": "get_weather",
          "description": "Get the current weather in a given location",
          "input_schema": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              }
            },
            "required": ["location"]
          }
        }
      ],
      "tool_choice": {"type": "any"},
      "messages": [
        {
          "role": "user",
          "content": "What is the weather like in San Francisco?"
        }
      ],
      "stream": true
    }'
응답
event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-3-haiku-20240307","stop_sequence":null,"usage":{"input_tokens":472,"output_tokens":2},"content":[],"stop_reason":null}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Okay"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" let"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"'s"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" check"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" for"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Francisco"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" CA"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":":"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" Francisc"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":", "}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"unit\": \"fah"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"renheit\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}

event: message_stop
data: {"type":"message_stop"}

​
확장된 사고가 포함된 스트리밍 요청

이 요청에서는 Claude의 단계별 추론을 보기 위해 스트리밍과 함께 확장된 사고를 활성화합니다.

요청
curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 20000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is 27 * 453?"
        }
    ]
}'
응답
event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-3-7-sonnet-20250219", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "단계별로 풀어보겠습니다:\n\n1. 먼저 27 * 453을 분해합니다"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n3. 27 * 400 = 10,800"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n4. 27 * 50 = 1,350"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n5. 27 * 3 = 81"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n6. 10,800 + 1,350 + 81 = 12,231"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "27 * 453 = 12,231"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

Was this page helpful?

메시지 토큰 수 계산텍스트 완성에서 마이그레이션하기