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/API messages dasar, penggunaan alat, streaming, pemikiran, dan tidak ada yang lain.
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/API messages dasar, penggunaan alat, streaming, pemikiran, dan tidak ada yang lain.
Model
Recommended default for most work, including complex agentic coding: Claude Opus 5.5: claude-opus-5-5
Step up for the hardest long-running agentic and research tasks, at 2x Claude Opus 5.5 pricing: Claude Fable 5.2: claude-fable-5-2
Previous Opus model: Claude Opus 5: claude-opus-5
Smart model: Claude Sonnet 5.5: claude-sonnet-5-5
Previous Sonnet model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 5.5: claude-haiku-5-5
Previous Haiku model: Claude Haiku 4.5: claude-haiku-4-5-20251001Memanggil API
Permintaan dan respons dasar
import anthropic
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-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-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 12,
"output_tokens": 6
}
}Beberapa giliran percakapan
Messages API bersifat “stateless” (tanpa status), yang berarti Anda selalu mengirimkan seluruh riwayat percakapan 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.
Dengan thread pesan, yang masih dalam tahap beta, API dapat menyimpan percakapan, sehingga setiap permintaan berikutnya hanya mengirimkan pesan-pesan baru. Thread kedaluwarsa 5 menit setelah permintaan terakhirnya dan dihapus paling lambat 1 jam setelah penggunaan terakhirnya.
import anthropic
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-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 pada 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 maupun 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 httpx2
# 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(httpx2.get(image_url).content).decode("utf-8")
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-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 dirujuk melalui URL
message_from_url = anthropic.Anthropic().messages.create(
model="claude-opus-5-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"))Pemikiran
Thinking terkadang dapat membantu Claude dengan tugas yang sangat sulit. Mekanisme saat ini adalah pemikiran adaptif (thinking: {"type": "adaptive"}): Claude menentukan kapan dan seberapa banyak berpikir, dan Anda mengarahkan kedalaman thinking dengan parameter effort alih-alih anggaran token. Pemikiran adaptif didukung pada model Claude 4.6 dan yang lebih baru serta Claude Mythos Preview. Pada model Claude 5 dan yang lebih baru serta Claude Mythos Preview, thinking aktif secara default ketika parameter thinking dihilangkan.
Thinking didukung pada model-model berikut:
- Claude Fable 5.2 (
claude-fable-5-2, hanya pemikiran adaptif, selalu aktif) - Claude Mythos 5.2 (
claude-mythos-5-2, hanya pemikiran adaptif, selalu aktif) - Claude Opus 5.5 (
claude-opus-5-5, hanya pemikiran adaptif, selalu aktif) - Claude Sonnet 5.5 (
claude-sonnet-5-5, hanya pemikiran adaptif, aktif secara default;thinking: {"type": "disabled"}mengembalikan error 400, jadi kirimthinking: {"type": "between_tools"}untuk menonaktifkan thinking di awal) - Claude Haiku 5.5 (
claude-haiku-5-5, hanya pemikiran adaptif, aktif secara default) - Claude Fable 5.1 (
claude-fable-5-1, hanya pemikiran adaptif, selalu aktif) - Claude Mythos 5.1 (
claude-mythos-5-1, hanya pemikiran adaptif, selalu aktif) - Claude Fable 5 (
claude-fable-5, hanya pemikiran adaptif, selalu aktif) - Claude Mythos 5 (
claude-mythos-5, hanya pemikiran adaptif, selalu aktif) - Claude Opus 5 (, hanya pemikiran adaptif, aktif secara default)
- Claude Sonnet 5 (
claude-sonnet-5, hanya pemikiran adaptif, aktif secara default) - Claude Opus 4.8 (, hanya pemikiran adaptif)
- Claude Opus 4.7 (
claude-opus-4-7, hanya pemikiran adaptif) - Claude Opus 4.6 (
claude-opus-4-6, pemikiran adaptif atau pemikiran manual lama) - Claude Sonnet 4.6 (
claude-sonnet-4-6, pemikiran adaptif atau pemikiran manual lama) - Claude Opus 4.5 (
claude-opus-4-5-20251101, hanya pemikiran manual lama) - Claude Sonnet 4.5 (
claude-sonnet-4-5-20250929, tidak digunakan lagi, hanya pemikiran manual lama) - Claude Haiku 4.5 (
claude-haiku-4-5-20251001, hanya pemikiran manual lama)
Cara kerja thinking
Ketika thinking aktif, Claude membuat blok konten thinking tempat ia mengeluarkan penalaran internalnya. Respons API menyertakan blok konten thinking, diikuti oleh blok konten text.
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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 berisi blok pemikiran yang diringkas dan blok teks
for block in response.content:
match block.type:
case "thinking":
print(f"\nThinking summary: {block.thinking}")
case "text":
print(f"\nResponse: {block.text}")“Manual extended thinking” (pemikiran diperpanjang manual) (thinking: {"type": "enabled", "budget_tokens": N}) adalah mekanisme lama. 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 pemikiran adaptif sebagai gantinya. Dengan pemikiran diperpanjang manual, budget_tokens menetapkan jumlah maksimum token yang boleh digunakan Claude untuk proses penalaran internalnya; batas ini berlaku untuk token thinking penuh, bukan untuk output yang diringkas. Kecuali Anda menggunakan pemikiran berselang, budget_tokens harus lebih kecil dari max_tokens agar Claude memiliki ruang untuk menulis responsnya setelah thinking selesai.
Thinking dengan penggunaan alat
Thinking dapat digunakan bersama penggunaan alat, memungkinkan Claude untuk bernalar dalam pemilihan alat dan pemrosesan hasil.
Batasan penting:
- Batasan pilihan alat: Dengan pemikiran diperpanjang manual (
thinking: {"type": "enabled"}), hanyatool_choice: {"type": "auto"}(default) atautool_choice: {"type": "none"}yang didukung. Pemikiran adaptif menerima penggunaan alat yang dipaksakan, kecuali pada model yang tercantum di bawah Memaksa penggunaan alat. Jika diterima, pemanggilan alat yang dipaksakan akan melewati thinking: respons dimulai dengan pemanggilan alat dan tidak memiliki blokthinking. - Mempertahankan blok thinking: Selama penggunaan alat, Anda harus meneruskan blok
thinkingkembali 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 thinking dan permintaan alat
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
tools=[weather_tool],
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
# Ekstrak blok thinking 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 thinking dan hasil alat
continuation = client.messages.create(
model="claude-opus-5-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)Pemikiran berselang
“Interleaved thinking” (thinking yang diselingi) memungkinkan Claude untuk berpikir di antara pemanggilan alat, bernalar tentang hasil alat sebelum menentukan langkah berikutnya.
Pada model lama yang menggunakan pemikiran diperpanjang manual (model Claude 4, 4.5, dan Sonnet 4.6), aktifkan pemikiran berselang 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:
match block.type:
case "thinking":
print(f"Thinking: {block.thinking}")
case "tool_use":
print(f"Tool call: {block.name}({block.input})")
case "text":
print(f"Response: {block.text}")Dengan pemikiran berselang dan HANYA dengan pemikiran berselang (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:
| Parameter | Deskripsi |
|---|---|
name | Nama alat. Harus cocok dengan regex ^[a-zA-Z0-9_-]{1,128}$. |
description | Deskripsi teks biasa yang terperinci tentang apa yang dilakukan alat, kapan harus digunakan, dan bagaimana perilakunya. |
input_schema | Objek JSON Schema yang mendefinisikan parameter yang diharapkan untuk alat. |
{
"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 sejauh ini merupakan faktor terpenting dalam kinerja alat. Deskripsi Anda harus menjelaskan setiap detail tentang alat, termasuk:
- Apa yang dilakukan alat
- Kapan alat 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 menunjukkan kepada Claude 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 mungkin:
automemungkinkan Claude menentukan apakah akan memanggil alat yang disediakan atau tidak (default).anymemberi tahu Claude bahwa ia harus menggunakan salah satu alat yang disediakan.toolmemaksa Claude untuk selalu menggunakan alat tertentu.nonemencegah Claude menggunakan alat apa pun.
Pada Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, dan Claude Mythos 5.1, any dan tool mengembalikan error 400. Biarkan tool_choice pada auto dan atur "strict": true pada definisi alat untuk menjamin bahwa setiap pemanggilan yang dilakukan Claude sesuai dengan input_schema alat tersebut. Lihat Penggunaan alat strict.
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.
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 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.
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA" }
}
]
}Ketika Anda menerima respons penggunaan alat, Anda harus:
- Mengekstrak
name,id, daninputdari bloktool_use. - Menjalankan alat sebenarnya di basis kode Anda yang sesuai dengan nama alat tersebut.
- Melanjutkan percakapan dengan mengirimkan pesan baru dengan
tool_result:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}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
Saat menggunakan alat server seperti pencarian web, API dapat mengembalikan alasan berhenti pause_turn. Lanjutkan percakapan dengan meneruskan respons yang dijeda kembali apa adanya dalam permintaan berikutnya.
Pemecahan masalah error
Error eksekusi alat
Jika alat itu sendiri melempar 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 wajib tidak ada), coba lagi permintaan 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” (peristiwa yang dikirim server), atau 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-5",
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)Tipe event
Setiap server-sent event menyertakan tipe event bernama dan data JSON terkait. Setiap stream menggunakan alur event berikut:
message_start: berisi objekMessagedengancontentkosong.- Serangkaian blok konten, masing-masing dengan
content_block_start, satu atau lebih eventcontent_block_delta, dancontent_block_stop. - Satu atau lebih event
message_delta, yang menunjukkan perubahan tingkat atas pada objekMessageakhir. - Event
message_stopterakhir.
Peringatan: Jumlah token yang ditampilkan di field usage dari event message_delta bersifat kumulatif.
Tipe delta blok konten
Delta teks
{
"type": "content_block_delta",
"index": 0,
"delta": { "type": "text_delta", "text": "Hello frien" }
}Delta JSON input
Untuk blok konten tool_use, delta berupa string JSON parsial:
{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}Delta pemikiran
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-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"}Apakah halaman ini membantu?