Claude Platform Docs
PesanMembangun dengan Claude

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 APIClaude Managed Agents
Apa ituAkses langsung untuk memberikan prompt ke modelHarness agen siap pakai yang dapat dikonfigurasi dan berjalan di infrastruktur terkelola
Paling cocok untukLoop agen kustom dan kontrol yang terperinciTugas 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)
Output
{
  "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)
Output
{
  "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)
Output
{
  "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)
Output
{
  "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

Messages API
Persyaratan ketersediaan untuk Messages API sama di semua platform yang didukung.
Model
  • Semua model

Endpoint yang berlaku

  • /v1/messages
Retensi data nolLayak

Tidak termasuk Model yang dicakup

Panggilan API standar untuk menghasilkan respons Claude.

HIPAALayak

Apakah halaman ini membantu?