Menggunakan Messages API
Pola praktis dan contoh untuk menggunakan Messages API secara efektif
Anthropic menawarkan dua cara untuk membangun dengan Claude, masing-masing cocok untuk kasus penggunaan yang berbeda:
| Messages API | Claude Managed Agents | |
|---|---|---|
| Apa itu | Akses langsung untuk memberikan prompt ke model | Harness agen siap pakai yang dapat dikonfigurasi dan berjalan di infrastruktur terkelola |
| Paling cocok untuk | Loop agen kustom dan kontrol yang terperinci | Tugas yang berjalan lama dan pekerjaan asinkron |
Panduan ini mencakup pola umum untuk bekerja dengan Messages API, termasuk permintaan dasar, percakapan multi-giliran, teknik prefill, dan kemampuan vision. Untuk spesifikasi API lengkap, lihat referensi Messages APIPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali.. Jika Anda menginginkan harness agen terkelola, lihat ikhtisar Claude Managed Agents.
Permintaan dan respons dasar
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
}
}Respons penolakan (stop_reason: "refusal") juga menyertakan objek stop_details yang mengidentifikasi kategori kebijakan yang memicu penolakan, pada setiap model. Lihat Seperti apa penolakan itu untuk referensi field dan contoh kode penanganan.
Beberapa giliran percakapan
Messages API bersifat “stateless” (tanpa status), 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.
Dengan thread pesan, dalam beta, API dapat menyimpan percakapan, sehingga setiap permintaan berikutnya hanya mengirimkan pesan baru. Thread kedaluwarsa 5 menit setelah permintaan terakhirnya dan dihapus paling lambat 1 jam setelah penggunaan terakhirnya.
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){
"id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Sure, I'd be happy to provide..."
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 30,
"output_tokens": 309
}
}Peran sistem dalam pesan
Untuk menambahkan instruksi sistem baru di tengah percakapan, sertakan pesan dengan "role": "system" tepat setelah giliran pengguna. Pesan tersebut tidak dapat menjadi entri pertama dalam messages. Ini berfungsi pada Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5, dan Claude Haiku 5.5. Lihat aturan penempatan lengkap.
Pesan sistem di tengah percakapan memiliki otoritas yang sama dengan field system tingkat atas, tetapi karena pesan tersebut ditambahkan ke akhir riwayat pesan, pesan tersebut tidak membatalkan prefiks yang di-cache sebelumnya. Gunakan field system tingkat atas untuk instruksi yang harus berlaku sejak giliran pertama, dan pesan sistem di tengah percakapan untuk instruksi yang baru menjadi relevan kemudian.
Lihat Pesan sistem dan perubahan alat di tengah percakapan untuk panduan lengkap, termasuk cara menggabungkannya dengan “prompt caching” (caching prompt).
Prefill respons Claude
Anda dapat melakukan prefill sebagian respons Claude di posisi terakhir daftar pesan input. Gunakan teknik ini untuk membentuk respons Claude. Contoh berikut menggunakan "max_tokens": 1 untuk mendapatkan satu jawaban pilihan ganda dari Claude.
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){
"id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "C"
}
],
"model": "claude-sonnet-4-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 42,
"output_tokens": 1
}
}Vision
Claude dapat membaca teks dan gambar dalam permintaan. Anda dapat menyediakan gambar menggunakan tipe sumber base64, url, atau file. Tipe sumber file mereferensikan gambar yang diunggah melalui Files API. Tipe media yang didukung adalah image/jpeg, image/png, image/gif, dan image/webp. Lihat panduan Vision untuk detail lebih lanjut.
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(message)
# 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(message_from_url){
"id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 1030,
"output_tokens": 350
}
}Langkah selanjutnya
Tangani setiap nilai stop_reason dan tentukan apa yang harus dilakukan ketika respons berakhir.
Berikan Claude alat untuk memanggil layanan eksternal dan API dari dalam Messages API.
Kendalikan lingkungan komputer desktop dengan Messages API.
Biarkan Claude menavigasi, membaca, dan berinteraksi dengan halaman web di browser yang Anda jalankan.
Dapatkan output JSON yang terjamin dan tervalidasi skema dari Claude.
Tetapkan anggaran token yang bersifat saran di seluruh loop agentik penuh dengan output_config.task_budget.
Ketersediaan
Claude API
- Model
- Semua model
Amazon Bedrock
- Model
- Semua model
Amazon Bedrock (bedrock-runtime)
- Model
- Semua model
Claude Platform on AWS
- Model
- Semua model
Claude Models on Google Cloud (Anthropic managed)
- Model
- Semua model
Claude Models on Google Cloud (Google managed)
- Model
- Semua model
Microsoft Foundry
- Model
- Semua model
Penanganan data
Ikhtisar penanganan dataEndpoint yang berlaku
/v1/messages
Tidak termasuk Model yang dicakup
Panggilan API standar untuk menghasilkan respons Claude.
Apakah halaman ini membantu?