# Panduan dasar penggunaan API untuk Claude

> Panduan ini dirancang untuk memberikan Claude dasar-dasar penggunaan API Claude. Panduan ini memberikan penjelasan dan contoh ID model/API pesan dasar, penggunaan alat, streaming, pemikiran diperpanjang, dan tidak ada yang lain.

# Panduan dasar penggunaan API untuk Claude

> Panduan ini dirancang untuk memberikan Claude dasar-dasar penggunaan API Claude. Panduan ini memberikan penjelasan dan contoh ID model/API pesan dasar, penggunaan alat, streaming, pemikiran diperpanjang, dan tidak ada yang lain.

## Model

```
Model terpintar: Claude Sonnet 4.5: claude-sonnet-4-5-20250929
Untuk tugas cepat dan hemat biaya: Claude Haiku 4.5: claude-haiku-4-5-20251001
```

## Memanggil API

### Permintaan dan respons dasar

```python  theme={null}
import anthropic
import os

message = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY")).messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Halo, Claude"}
    ]
)
print(message)
```

```json  theme={null}
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Halo!"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}
```

### Beberapa giliran percakapan

API Messages bersifat stateless, yang berarti Anda selalu mengirim riwayat percakapan lengkap ke API. Anda dapat menggunakan pola ini untuk membangun percakapan dari waktu ke waktu. Giliran percakapan sebelumnya tidak harus benar-benar berasal dari Claude — Anda dapat menggunakan pesan `assistant` sintetis.

```python  theme={null}
import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Halo, Claude"},
        {"role": "assistant", "content": "Halo!"},
        {"role": "user", "content": "Bisakah Anda menjelaskan LLM kepada saya?"}
    ],
)
print(message)
```

### Memasukkan kata-kata ke mulut Claude

Anda dapat mengisi sebagian respons Claude di posisi terakhir dari daftar pesan input. Ini dapat digunakan untuk membentuk respons Claude. Contoh di bawah ini menggunakan `"max_tokens": 1` untuk mendapatkan satu jawaban pilihan ganda dari Claude.

```python  theme={null}
message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {"role": "user", "content": "Apa bahasa latin untuk Semut? (A) Apoidea, (B) Rhopalocera, (C) Formicidae"},
        {"role": "assistant", "content": "Jawabannya adalah ("}
    ]
)
```

### Visi

Claude dapat membaca teks dan gambar dalam permintaan. Kami mendukung jenis sumber `base64` dan `url` untuk gambar, dan jenis media `image/jpeg`, `image/png`, `image/gif`, dan `image/webp`.

```python  theme={null}
import anthropic
import base64
import httpx

# Opsi 1: Gambar yang dikodekan Base64
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Apa yang ada di gambar di atas?"
                }
            ],
        }
    ],
)

# Opsi 2: Gambar yang direferensikan URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {
                    "type": "text",
                    "text": "Apa yang ada di gambar di atas?"
                }
            ],
        }
    ],
)
```

## Pemikiran diperpanjang

Pemikiran diperpanjang terkadang dapat membantu Claude dengan tugas yang sangat sulit. Ketika diaktifkan, temperature harus diatur ke 1.

Pemikiran diperpanjang didukung dalam model berikut:

* Claude Opus 4.1 (`claude-opus-4-1-20250805`)
* Claude Opus 4 (`claude-opus-4-20250514`)
* Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)

### Cara kerja pemikiran diperpanjang

Ketika pemikiran diperpanjang diaktifkan, Claude membuat blok konten `thinking` di mana ia mengeluarkan penalaran internalnya. Respons API akan menyertakan blok konten `thinking`, diikuti oleh blok konten `text`.

```python  theme={null}
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{
        "role": "user",
        "content": "Apakah ada jumlah tak terbatas bilangan prima sehingga n mod 4 == 3?"
    }]
)

# Respons akan berisi blok pemikiran yang dirangkum dan blok teks
for block in response.content:
    if block.type == "thinking":
        print(f"\nRingkasan pemikiran: {block.thinking}")
    elif block.type == "text":
        print(f"\nRespons: {block.text}")
```

Parameter `budget_tokens` menentukan jumlah maksimum token yang diizinkan Claude gunakan untuk proses penalaran internalnya. Dalam model Claude 4, batas ini berlaku untuk token pemikiran penuh, dan bukan untuk output yang dirangkum. Anggaran yang lebih besar dapat meningkatkan kualitas respons dengan memungkinkan analisis yang lebih menyeluruh untuk masalah kompleks. Satu aturan: nilai max\_tokens harus benar-benar lebih besar dari nilai budget\_tokens sehingga Claude memiliki ruang untuk menulis responsnya setelah pemikiran selesai.

## Pemikiran diperpanjang dengan penggunaan alat

Pemikiran diperpanjang dapat digunakan bersama dengan penggunaan alat, memungkinkan Claude untuk bernalar melalui pemilihan alat dan pemrosesan hasil.

Keterbatasan penting:

1. **Keterbatasan pilihan alat**: Hanya mendukung `tool_choice: {"type": "auto"}` (default) atau `tool_choice: {"type": "none"}`.
2. **Mempertahankan blok pemikiran**: Selama penggunaan alat, Anda harus mengirim kembali blok `thinking` ke API untuk pesan assistant terakhir.

### Mempertahankan blok pemikiran

```python  theme={null}
# Permintaan pertama - Claude merespons dengan pemikiran dan permintaan alat
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "Bagaimana cuaca di Paris?"}
    ]
)

# Ekstrak blok pemikiran dan blok penggunaan alat
thinking_block = next((block for block in response.content
                      if block.type == 'thinking'), None)
tool_use_block = next((block for block in response.content
                      if block.type == 'tool_use'), None)

# Permintaan kedua - Sertakan blok pemikiran dan hasil alat
continuation = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "Bagaimana cuaca di Paris?"},
        # Perhatikan bahwa thinking_block dikirim masuk serta tool_use_block
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {"role": "user", "content": [{
            "type": "tool_result",
            "tool_use_id": tool_use_block.id,
            "content": f"Suhu saat ini: {weather_data['temperature']}°F"
        }]}
    ]
)
```

### Pemikiran berselang-seling

Pemikiran diperpanjang dengan penggunaan alat dalam model Claude 4 mendukung pemikiran berselang-seling, yang memungkinkan Claude untuk berpikir di antara panggilan alat. Untuk mengaktifkan, tambahkan header beta `interleaved-thinking-2025-05-14` ke permintaan API Anda.

```python  theme={null}
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    messages=[{
        "role": "user",
        "content": "Berapa total pendapatan jika kita menjual 150 unit produk A dengan harga $50 masing-masing?"
    }],
    betas=["interleaved-thinking-2025-05-14"]
)
```

Dengan pemikiran berselang-seling dan HANYA dengan pemikiran berselang-seling (bukan pemikiran diperpanjang biasa), `budget_tokens` dapat melebihi parameter `max_tokens`, karena `budget_tokens` dalam hal ini mewakili total anggaran di semua blok pemikiran dalam satu giliran assistant.

## Penggunaan Alat

### Menentukan alat klien

Alat klien ditentukan dalam parameter tingkat atas `tools` dari permintaan API. Setiap definisi alat mencakup:

| Parameter      | Deskripsi                                                                                                          |
| :------------- | :----------------------------------------------------------------------------------------------------------------- |
| `name`         | Nama alat. Harus cocok dengan regex `^[a-zA-Z0-9_-]{1,64}$`.                                                       |
| `description`  | Deskripsi teks biasa yang rinci tentang apa yang dilakukan alat, kapan harus digunakan, dan bagaimana perilakunya. |
| `input_schema` | Objek [JSON Schema](https://json-schema.org/) yang mendefinisikan parameter yang diharapkan untuk alat.            |

```json  theme={null}
{
  "name": "get_weather",
  "description": "Dapatkan cuaca saat ini di lokasi tertentu",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "Kota dan negara bagian, misalnya San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Satuan suhu, baik 'celsius' atau 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}
```

### Praktik terbaik untuk definisi alat

**Berikan deskripsi yang sangat rinci.** Ini adalah faktor terpenting dalam kinerja alat. Deskripsi Anda harus menjelaskan setiap detail tentang alat, termasuk:

* Apa yang dilakukan alat
* Kapan harus digunakan (dan kapan tidak boleh)
* Apa arti setiap parameter dan bagaimana pengaruhnya terhadap perilaku alat
* Peringatan atau keterbatasan penting apa pun

Contoh deskripsi alat yang baik:

```json  theme={null}
{
  "name": "get_stock_price",
  "description": "Mengambil harga saham saat ini untuk simbol ticker tertentu. Simbol ticker harus berupa simbol yang valid untuk perusahaan yang diperdagangkan secara publik di bursa saham utama AS seperti NYSE atau NASDAQ. Alat ini akan mengembalikan harga perdagangan terbaru dalam USD. Ini harus digunakan ketika pengguna bertanya tentang harga saat ini atau terbaru dari saham tertentu. Ini tidak akan memberikan informasi lain tentang saham atau perusahaan.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Simbol ticker saham, misalnya AAPL untuk Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}
```

## Mengontrol output Claude

### Memaksa penggunaan alat

Anda dapat memaksa Claude untuk menggunakan alat tertentu dengan menentukan alat dalam bidang `tool_choice`:

```python  theme={null}
tool_choice = {"type": "tool", "name": "get_weather"}
```

Ketika bekerja dengan parameter tool\_choice, kita memiliki empat opsi yang mungkin:

* `auto` memungkinkan Claude untuk memutuskan apakah akan memanggil alat yang disediakan atau tidak (default).
* `any` memberi tahu Claude bahwa ia harus menggunakan salah satu alat yang disediakan.
* `tool` memungkinkan kita untuk memaksa Claude untuk selalu menggunakan alat tertentu.
* `none` mencegah Claude menggunakan alat apa pun.

### Output JSON

Alat tidak harus berupa fungsi klien — Anda dapat menggunakan alat kapan saja Anda ingin model mengembalikan output JSON yang mengikuti skema yang disediakan.

### Rantai pemikiran

Ketika menggunakan alat, Claude akan sering menunjukkan "rantai pemikirannya", yaitu penalaran langkah demi langkah yang digunakannya untuk memecah masalah dan memutuskan alat mana yang akan digunakan.

```json  theme={null}
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Untuk menjawab pertanyaan ini, saya akan: 1. Menggunakan alat get_weather untuk mendapatkan cuaca saat ini di San Francisco. 2. Menggunakan alat get_time untuk mendapatkan waktu saat ini di zona waktu America/Los_Angeles, yang mencakup San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}
```

### Penggunaan alat paralel

Secara default, Claude dapat menggunakan beberapa alat untuk menjawab kueri pengguna. Anda dapat menonaktifkan perilaku ini dengan mengatur `disable_parallel_tool_use=true`.

## Menangani blok konten penggunaan alat dan hasil alat

### Menangani hasil dari alat klien

Respons akan memiliki `stop_reason` dari `tool_use` dan satu atau lebih blok konten `tool_use` yang mencakup:

* `id`: Pengenal unik untuk blok penggunaan alat tertentu ini.
* `name`: Nama alat yang digunakan.
* `input`: Objek yang berisi input yang diteruskan ke alat.

Ketika Anda menerima respons penggunaan alat, Anda harus:

1. Ekstrak `name`, `id`, dan `input` dari blok `tool_use`.
2. Jalankan alat sebenarnya dalam basis kode Anda yang sesuai dengan nama alat tersebut.
3. Lanjutkan percakapan dengan mengirim pesan baru dengan `tool_result`:

```json  theme={null}
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 derajat"
    }
  ]
}
```

### Menangani alasan berhenti `max_tokens`

Jika respons Claude terpotong karena mencapai batas `max_tokens` selama penggunaan alat, coba lagi permintaan dengan nilai `max_tokens` yang lebih tinggi.

### Menangani alasan berhenti `pause_turn`

Ketika menggunakan alat server seperti pencarian web, API dapat mengembalikan alasan berhenti `pause_turn`. Lanjutkan percakapan dengan mengirim kembali respons yang dijeda apa adanya dalam permintaan berikutnya.

## Memecahkan masalah kesalahan

### Kesalahan eksekusi alat

Jika alat itu sendiri menimbulkan kesalahan selama eksekusi, kembalikan pesan kesalahan dengan `"is_error": true`:

```json  theme={null}
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: API layanan cuaca tidak tersedia (HTTP 500)",
      "is_error": true
    }
  ]
}
```

### Nama alat tidak valid

Jika upaya Claude untuk menggunakan alat tidak valid (misalnya parameter yang diperlukan hilang), coba permintaan lagi dengan nilai `description` yang lebih rinci dalam definisi alat Anda.

## Streaming Messages

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

### Streaming dengan SDK

```python  theme={null}
import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Halo"}],
    model="claude-sonnet-4-5",
) 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 stream menggunakan alur event berikut:

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

**Peringatan**: Jumlah token yang ditampilkan dalam bidang `usage` dari event `message_delta` bersifat *kumulatif*.

### Jenis delta blok konten

#### Delta teks

```json  theme={null}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": { "type": "text_delta", "text": "Halo teman" }
}
```

#### Delta JSON input

Untuk blok konten `tool_use`, delta adalah *string JSON parsial*:

```json  theme={null}
{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}
```

#### Delta pemikiran

Ketika menggunakan pemikiran diperpanjang dengan streaming:

```json  theme={null}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "thinking_delta",
    "thinking": "Biarkan saya menyelesaikan ini langkah demi langkah..."
  }
}
```

### Contoh permintaan streaming dasar

```json  theme={null}
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-5", "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: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Halo"}}

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"}
```
