

Panduan dasar penggunaan API untuk Claude

Panduan ini dirancang untuk memberikan Claude dasar-dasar penggunaan Claude API. Panduan ini memberikan penjelasan dan contoh tentang ID model/messages API dasar, penggunaan alat, streaming, thinking, dan tidak lebih dari itu.



Model

For complex agentic coding and enterprise work: Claude Opus 5: claude-opus-5
Previous Opus model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001



Memanggil API



Permintaan dan respons dasar

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}



Beberapa giliran percakapan

Messages API bersifat stateless, yang berarti Anda selalu mengirimkan 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.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)



Mengisi awal respons Claude

Anda dapat mengisi awal sebagian respons Claude di posisi terakhir dari daftar pesan input. Gunakan teknik ini untuk membentuk respons Claude. Contoh berikut menggunakan "max_tokens": 1 untuk mendapatkan satu jawaban pilihan ganda dari Claude.

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message.content[0].text)



Vision

Claude dapat membaca teks dan gambar dalam permintaan. Tipe sumber base64 dan url keduanya didukung untuk gambar, bersama dengan tipe media image/jpeg, image/png, image/gif, dan image/webp.

import anthropic
import base64
import httpx

# Opsi 1: Gambar yang dienkode Base64
image_url = "https://platform.claude.com/docs/images/vision-example.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-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(next(block.text for block in message.content if block.type == "text"))

# Opsi 2: Gambar yang direferensikan melalui URL
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(next(block.text for block in message_from_url.content if block.type == "text"))



Thinking

Thinking terkadang dapat membantu Claude dengan tugas yang sangat sulit. Mekanisme saat ini adalah adaptive thinking (thinking: {"type": "adaptive"}): Claude memutuskan kapan dan seberapa banyak untuk berpikir, dan Anda mengarahkan kedalaman berpikir dengan parameter effort alih-alih anggaran token. Adaptive thinking didukung pada model Claude 4.6 dan yang lebih baru serta Claude Mythos Preview. Pada model Claude 5 dan Claude Mythos Preview, thinking aktif secara default ketika parameter thinking dihilangkan.

Temperature harus diatur ke 1 (atau dibiarkan tidak diatur) setiap kali thinking diaktifkan, pada semua model. Pada model Claude 4.7 dan yang lebih baru serta Claude Mythos Preview, temperature sudah tidak digunakan lagi (deprecated) dan hanya nilai default-nya yang diterima, bahkan ketika thinking dimatikan.

Thinking didukung pada model-model berikut:

• Claude Opus 5 (claude-opus-5, hanya adaptive thinking, aktif secara default)
• Claude Sonnet 5 (claude-sonnet-5, hanya adaptive thinking, aktif secara default)
• Claude Opus 4.8 (claude-opus-4-8, hanya adaptive thinking)
• Claude Opus 4.7 (claude-opus-4-7, hanya adaptive thinking)
• Claude Opus 4.6 (claude-opus-4-6, adaptive atau legacy manual thinking)
• Claude Sonnet 4.6 (claude-sonnet-4-6, adaptive atau legacy manual thinking)
• Claude Opus 4.5 (claude-opus-4-5-20251101, hanya legacy manual thinking)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929, hanya legacy manual thinking)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001, hanya legacy manual thinking)



Cara kerja thinking

Ketika thinking aktif, Claude membuat blok konten thinking tempat ia menghasilkan penalaran internalnya. Respons API mencakup blok konten thinking, diikuti oleh blok konten text.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# Respons akan berisi blok pemikiran yang diringkas dan blok teks
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Pemikiran diperpanjang manual (thinking: {"type": "enabled", "budget_tokens": N}) adalah mekanisme legacy. Mekanisme ini hanya berfungsi pada model Claude 4 hingga 4.6 yang mendukung thinking; model Claude 4.7 dan yang lebih baru menolak type: enabled dengan error 400 dan menggunakan adaptive thinking sebagai gantinya. Dengan pemikiran diperpanjang manual, budget_tokens menetapkan jumlah maksimum token yang diizinkan Claude gunakan untuk proses penalaran internalnya; batas ini berlaku untuk token thinking penuh, bukan untuk output yang diringkas. Kecuali Anda menggunakan interleaved thinking, budget_tokens harus kurang dari max_tokens agar Claude memiliki ruang untuk menulis responsnya setelah thinking selesai.



Thinking dengan penggunaan alat

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

Batasan penting:

1. Batasan tool choice: Hanya mendukung tool_choice: {"type": "auto"} (default) atau tool_choice: {"type": "none"}.
2. Mempertahankan blok thinking: Selama penggunaan alat, Anda harus meneruskan blok thinking kembali ke API untuk pesan assistant terakhir.



Mempertahankan blok thinking

import anthropic

client = anthropic.Anthropic()

weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string", "description": "The city name."}},
        "required": ["location"],
    },
}

weather_data = {"temperature": 72}

# Permintaan pertama - Claude merespons dengan pemikiran dan permintaan alat
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather in 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-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # Perhatikan bahwa thinking_block diteruskan bersama dengan 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"Current temperature: {weather_data['temperature']}°F",
                }
            ],
        },
    ],
)

for block in continuation.content:
    if block.type == "text":
        print(block.text)



Interleaved thinking

Interleaved thinking memungkinkan Claude untuk berpikir di antara pemanggilan alat, bernalar tentang hasil alat sebelum memutuskan langkah berikutnya.

Pada model lama yang menggunakan pemikiran diperpanjang manual (model Claude 4, 4.5, dan Sonnet 4.6), aktifkan interleaved thinking dengan menambahkan header beta interleaved-thinking-2025-05-14 ke permintaan API Anda:

import anthropic

client = anthropic.Anthropic()

calculator_tool = {
    "name": "calculator",
    "description": "Perform arithmetic calculations.",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "The math expression to evaluate.",
            }
        },
        "required": ["expression"],
    },
}

database_tool = {
    "name": "database_query",
    "description": "Query the product database.",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "The database query."}
        },
        "required": ["query"],
    },
}

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[calculator_tool, database_tool],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each?",
        }
    ],
    betas=["interleaved-thinking-2025-05-14"],
)

for block in response.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "tool_use":
        print(f"Tool call: {block.name}({block.input})")
    elif block.type == "text":
        print(f"Response: {block.text}")

Dengan interleaved thinking dan HANYA dengan interleaved thinking (bukan pemikiran diperpanjang manual biasa), budget_tokens dapat melebihi parameter max_tokens, karena budget_tokens dalam kasus ini mewakili total anggaran di seluruh blok thinking dalam satu giliran assistant.



Penggunaan alat



Menentukan alat klien

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

{
  "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"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}



Praktik terbaik untuk definisi alat

Berikan deskripsi yang sangat terperinci. Ini adalah faktor paling penting dalam performa alat. Deskripsi Anda harus menjelaskan setiap detail tentang alat, termasuk:

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

Pertimbangkan untuk menggunakan input_examples untuk alat yang kompleks. Untuk alat dengan objek bersarang, parameter opsional, atau input yang sensitif terhadap format, Anda dapat memberikan contoh konkret menggunakan field input_examples (beta). Ini membantu Claude memahami pola input yang diharapkan. Lihat Memberikan contoh penggunaan alat untuk detailnya.

Contoh deskripsi alat yang baik:

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}



Mengontrol output Claude



Memaksa penggunaan alat

Anda dapat memaksa Claude untuk menggunakan alat tertentu dengan menentukan alat tersebut di field tool_choice:

tool_choice = {"type": "tool", "name": "get_weather"}

Saat bekerja dengan parameter tool_choice, ada empat opsi yang memungkinkan:

• 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 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 pun Anda ingin model mengembalikan output JSON yang mengikuti skema yang disediakan.



Chain of thought

Saat menggunakan alat, Claude sering menunjukkan "chain of thought" (rantai pemikiran) miliknya, yaitu penalaran langkah demi langkah yang digunakannya untuk memecah masalah dan memutuskan alat mana yang akan digunakan.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers 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 tool use dan tool result



Menangani hasil dari alat klien

Respons memiliki stop_reason berupa tool_use dan satu atau lebih blok konten tool_use yang mencakup:

• id: Pengidentifikasi 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. Mengekstrak name, id, dan input dari blok tool_use.
2. Menjalankan alat sebenarnya di basis kode Anda yang sesuai dengan nama alat tersebut.
3. Melanjutkan percakapan dengan mengirim pesan baru dengan tool_result:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}



Menangani stop reason max_tokens

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



Menangani stop reason pause_turn

Saat menggunakan alat server seperti pencarian web, API dapat mengembalikan stop reason pause_turn. Lanjutkan percakapan dengan meneruskan respons yang dijeda apa adanya dalam permintaan berikutnya.



Pemecahan masalah error



Error eksekusi alat

Jika alat itu sendiri melemparkan error selama eksekusi, kembalikan pesan error dengan "is_error": true:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}



Nama alat tidak valid

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



Streaming pesan

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



Streaming dengan SDK

import anthropic

client = anthropic.Anthropic()

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



Tipe event

Setiap server-sent event mencakup tipe 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 final.
4. Event message_stop final.

Peringatan: Jumlah token yang ditampilkan di field usage dari event message_delta bersifat kumulatif.



Tipe delta blok konten



Text delta

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



Input JSON delta

Untuk blok konten tool_use, delta adalah string JSON parsial:

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



Thinking delta

Saat menggunakan thinking dengan streaming:

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "thinking_delta",
    "thinking": "Let me solve this step by step..."
  }
}



Contoh permintaan streaming dasar

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-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": "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"}