Saat membuat Message, Anda dapat mengatur "stream": true untuk secara bertahap melakukan streaming respons menggunakan server-sent events (SSE).

Streaming dengan SDK

SDK Python dan Typescript kami menawarkan beberapa cara streaming. SDK Python memungkinkan streaming sinkron dan asinkron. Lihat dokumentasi di setiap SDK untuk detailnya.

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-3-opus-20240229",
) as stream:
  for text in stream.text_stream:
      print(text, end="", flush=True)

Jenis event

Setiap server-sent event mencakup jenis event bernama dan data JSON terkait. Setiap event akan menggunakan nama event SSE (misalnya event: message_stop), dan menyertakan type event yang sesuai dalam datanya.

Setiap stream menggunakan alur event berikut:

  1. message_start: berisi objek Message dengan content kosong.
  2. Serangkaian blok konten, yang masing-masing memiliki event content_block_start, satu atau lebih event content_block_delta, dan event content_block_stop. Setiap blok konten akan memiliki index yang sesuai dengan indeksnya dalam array content Message akhir.
  3. Satu atau lebih event message_delta, menunjukkan perubahan tingkat atas pada objek Message akhir.
  4. Event message_stop terakhir.

Event ping

Stream event juga dapat menyertakan sejumlah event ping.

Event error

Kami mungkin sesekali mengirim error dalam stream event. Misalnya, selama periode penggunaan tinggi, Anda mungkin menerima overloaded_error, yang biasanya sesuai dengan HTTP 529 dalam konteks non-streaming:

Example error
event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

Event lainnya

Sesuai dengan kebijakan versioning kami, kami mungkin menambahkan jenis event baru, dan kode Anda harus menangani jenis event yang tidak dikenal dengan baik.

Jenis delta

Setiap event content_block_delta berisi delta dari jenis yang memperbarui blok content pada index tertentu.

Delta teks

Delta blok konten text terlihat seperti:

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

Delta JSON input

Blok delta JSON input adalah bagian dari beta penggunaan tool.

Delta untuk blok konten tool_use sesuai dengan pembaruan untuk bidang input dari blok tersebut. Untuk mendukung granularitas maksimum, delta adalah string JSON parsial, sedangkan tool_use.input akhir selalu berupa objek.

Anda dapat mengakumulasi delta string dan mengurai JSON setelah menerima event content_block_stop, dengan menggunakan library seperti Pydantic untuk melakukan penguraian JSON parsial, atau dengan menggunakan SDK kami, yang menyediakan pembantu untuk mengakses nilai inkremental yang diurai.

Delta blok konten tool_use terlihat seperti:

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

Catatan: Model kami saat ini hanya mendukung mengeluarkan satu properti kunci dan nilai lengkap dari input pada satu waktu. Dengan demikian, saat menggunakan tool, mungkin ada penundaan antara event streaming saat model sedang bekerja. Setelah kunci dan nilai input terakumulasi, kami mengeluarkannya sebagai beberapa event content_block_delta dengan json parsial yang dipecah sehingga format dapat secara otomatis mendukung granularitas yang lebih halus di model masa depan.

Respons Stream HTTP Mentah

Kami sangat menyarankan agar menggunakan SDK klien kami saat menggunakan mode streaming. Namun, jika Anda membangun integrasi API langsung, Anda perlu menangani event ini sendiri.

Respons stream terdiri dari:

  1. Event message_start
  2. Berpotensi beberapa blok konten, yang masing-masing berisi: a. Event content_block_start b. Berpotensi beberapa event content_block_delta c. Event content_block_stop
  3. Event message_delta
  4. Event message_stop

Mungkin ada event ping yang tersebar di seluruh respons juga. Lihat Jenis event untuk detail lebih lanjut tentang formatnya.

Permintaan streaming dasar

Request
curl https://api.anthropic.com/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: messages-2023-12-15" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --data \
'{
  "model": "claude-3-opus-20240229",
  "messages": [{"role": "user", "content": "Hello"}],
  "max_tokens": 256,
  "stream": true
}'
Response
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-3-opus-20240229", "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"}

Permintaan streaming dengan penggunaan tool

Dalam permintaan ini, kami meminta Claude untuk menggunakan tool untuk memberi tahu kami cuaca.

Request
  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" \
    -H "anthropic-beta: tools-2024-05-16" \
    -d '{
      "model": "claude-3-opus-20240229",
      "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
    }'
Response
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"}