Teks

Create Message

Membuat pesan menggunakan format Anthropic Messages API

POST
/v1/messages

Gambaran Umum

Endpoint ini menerima format Anthropic Messages asli, sehingga SDK Anthropic dan alat yang dibangun di atasnya dapat bekerja dengan URL dasar TokenLab. Endpoint ini berfungsi dengan model yang accepted_request_formats-nya mencantumkan anthropic_messages: model Claude dan beberapa model lainnya.

messages menampung giliran user dan assistant. Masukkan instruksi sistem di kolom system tingkat atas. max_tokens wajib diisi. Untuk pesan bergaya OpenAI dengan peran seperti system atau tool, gunakan Chat Completions.

URL dasar untuk SDK Anthropic: https://api.tokenlab.sh (tanpa akhiran /v1)

Header Permintaan

x-api-keystringheader

API key TokenLab Anda. Kirimkan x-api-key atau Authorization: Bearer <API_KEY>. Jika Anda mengirim keduanya dengan nilai yang berbeda, TokenLab akan menggunakan x-api-key.

anthropic-versionstringheader

Versi API Anthropic. SDK Anthropic mengirimkannya untuk Anda; gunakan 2023-06-01 saat Anda memanggil API secara langsung.

anthropic-betastringheader

Nama fitur beta Anthropic, dipisahkan dengan koma. TokenLab meneruskan header tersebut, dan apakah fitur beta berfungsi bergantung pada modelnya. Konten yang mereferensikan file_id memerlukan files-api-2025-04-14.

Isi Permintaan

Parameter opsional yang didukung, nilai yang diterima, dan nilai default bergantung pada model yang dipilih. Periksa detail model sebelum mengatur opsi sampling, reasoning, atau tool.

modelstringwajib

ID model yang mendukung format anthropic_messages. Periksa detail model untuk kemampuan saat ini.

messagesarraywajib

Array objek pesan dengan role (user atau assistant) dan content. Hingga 100.000 pesan.

content bisa berupa string biasa atau array blok konten. Untuk mengirim gambar, gunakan blok konten terstruktur alih-alih menempatkan URL gambar atau string Base64 langsung ke dalam teks biasa. Blok asli lainnya, seperti tool_use, tool_result, thinking, dan document, diterima untuk model yang mendukungnya.

Contoh blok konten:

  • blok teks: { "type": "text", "text": "Jelaskan gambar ini" }
  • blok gambar via URL: { "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } }
  • blok gambar via Base64: { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
max_tokensintegerwajib

Token maksimum untuk dihasilkan. Wajib: TokenLab tidak menambahkan nilai default. Maksimum yang dapat digunakan bergantung pada model; lihat max_output_tokens di detail model. Nilai yang besar akan meningkatkan jumlah yang ditahan TokenLab dari saldo Anda saat permintaan berjalan, dan saldo yang tidak mencukupi untuk menutupi penahanan tersebut akan mengembalikan 402.

systemstring | array

Prompt sistem sebagai string atau array blok konten teks, terpisah dari array messages.

temperaturenumber

Suhu sampling. Dukungan, nilai yang diizinkan, dan nilai default bergantung pada model yang dipilih; hilangkan kolom ini untuk menggunakan nilai defaultnya.

streambooleanbawaan: false

Mengembalikan respons sebagai aliran peristiwa yang dikirim server (server-sent events). Lihat Streaming.

thinkingobject

Konfigurasi thinking asli, contohnya {"type":"enabled","budget_tokens":10000}. Mode, anggaran, dan kombinasi dengan parameter lain yang didukung bergantung pada model yang dipilih. Untuk model yang diketahui menolak anggaran manual, TokenLab menjalankan {"type":"enabled"} sebagai adaptive thinking dan mengabaikan budget_tokens.

toolsarray

Alat yang tersedia untuk model. Dukungan bergantung pada model yang dipilih.

tool_choiceobject

Objek pemilihan alat asli, contohnya {"type":"auto"}. Jenis yang didukung bergantung pada model yang dipilih.

cache_controlobject

Penanda caching prompt, contohnya {"type":"ephemeral"}; tambahkan "ttl": "1h" untuk cache satu jam. Di tingkat atas, ini mengaktifkan caching otomatis. Anda juga dapat mengaturnya pada blok system, tools, dan blok konten. Dukungan bergantung pada model; model yang mendukungnya mencantumkan prompt-cache dalam capabilities.

top_pnumber

Parameter sampling nucleus. Gunakan suhu atau top_p, jangan keduanya. Dukungan bergantung pada model yang dipilih.

top_kinteger

Hanya melakukan sampling dari K opsi teratas untuk setiap token. Dukungan bergantung pada model yang dipilih.

stop_sequencesarray

Urutan berhenti kustom yang akan menyebabkan model berhenti menghasilkan teks. Hingga 8.191 entri.

metadataobject

Metadata permintaan dalam format Anthropic. user_id adalah pengenal buram untuk pengguna akhir Anda.

service_tierstring

Hanya auto dan standard_only yang berpengaruh. TokenLab hanya mengenakan biaya untuk tingkat standar dan mengabaikan nilai lainnya.

Respons

idstring

Pengenal pesan unik.

typestring

Selalu message.

rolestring

Selalu assistant.

contentarray

Array blok konten, seperti text, thinking, atau tool_use.

modelstring

Model yang menghasilkan respons.

stop_reasonstring

Alasan pembuatan berhenti, seperti end_turn, max_tokens, stop_sequence, atau tool_use. Model dapat mengembalikan nilai lain, misalnya refusal.

stop_sequencestring | null

Urutan berhenti yang mengakhiri pembuatan, atau null.

usageobject

Penggunaan token dengan input_tokens dan output_tokens. Saat model melaporkan token prompt-cache, usage juga memiliki cache_creation_input_tokens dan cache_read_input_tokens.

Setiap respons membawa ID permintaan di header request-id dan X-Request-ID. Sebutkan ID ini saat Anda menghubungi dukungan.

Permintaan

curl -X POST "https://api.tokenlab.sh/v1/messages" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Respons

Response
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-5",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 10
  }
}

Contoh Input Visi

Untuk model Claude dengan dukungan visi, tempatkan gambar di dalam messages[].content sebagai blok gambar terstruktur.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}
{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

Contoh Extended Thinking

Gunakan model dengan kemampuan reasoning. Sesuaikan max_tokens dan budget_tokens dengan batas model; beberapa model memerlukan konfigurasi thinking yang berbeda.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "Solve this math problem..."}]
)

for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

Streaming

Atur "stream": true untuk menerima peristiwa server-sent Anthropic: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, dan message_stop. Penggunaan token tiba di message_start dan message_delta.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
  • Saat model bekerja, aliran dapat membawa baris komentar SSE seperti : keep-alive. SDK mengabaikannya.
  • Status HTTP sudah bisa 200 saat kegagalan terjadi. Kegagalan setelah aliran dimulai akan tiba sebagai peristiwa event: error dengan isi kesalahan yang sama seperti di bawah.

Kesalahan

Kesalahan menggunakan format kesalahan Anthropic. request_id adalah ID permintaan TokenLab. Beberapa kesalahan menambahkan kolom seperti code dan hint.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: Required. /v1/messages follows the native Anthropic contract and does not infer a default max_tokens value."
  },
  "request_id": "req_01JEXAMPLE"
}
Statuserror.typePenyebab umum
400invalid_request_errorKolom yang hilang atau tidak valid, model tidak dikenal, atau model yang tidak menerima format Messages
401authentication_errorAPI key hilang atau tidak valid
402billing_errorSaldo tidak dapat menutupi permintaan (error.code adalah insufficient_balance). API key yang mencapai batas pengeluaran juga mendapatkan 402, dengan error.code quota_exceeded dan error.type rate_limit_error
403permission_errorAPI key tidak dapat menggunakan model yang diminta, atau akun ditangguhkan atau dibatasi
409conflict_errorPercobaan ulang dengan Idempotency-Key yang sama. Lihat Retry safely with an idempotency key
413request_too_largeInput permintaan terlalu besar
429rate_limit_errorTerlalu banyak permintaan
500, 502, 503api_error atau overloaded_errorPermintaan tidak dapat diselesaikan, atau tidak ada rute yang tersedia untuk saat ini. Coba lagi nanti
504timeout_errorPermintaan kehabisan waktu (timeout)

Antarmuka terkait

Otorisasi

BearerAuth
AuthorizationBearer <token>

Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.

Lokasi: header

Header

X-TokenLab-Delivery-Policy?string

Kebijakan Pengiriman per-permintaan. Menggantikan default API key dan Workspace. Secara otomatis mencoba TokenLab Verified terlebih dahulu dan dapat beralih satu kali ke Official saja sebelum output, penerimaan permintaan, atau pembuatan sumber daya persisten.

Nilai yang tersedia

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Kunci opsional yang menghentikan eksekusi kedua dari permintaan yang sama. Kirim nilai unik baru, seperti UUID, untuk setiap permintaan, dan simpan untuk percobaan ulang setelah timeout. Percobaan ulang dengan kunci yang sama tidak akan berjalan kembali: sistem akan mengembalikan 409 dengan idempotency_replay_unavailable, atau biasanya idempotency_conflict jika body berubah. Pengecualian: jika hasil non-stream selesai setelah klien terputus, percobaan ulang dengan kunci dan body yang sama dalam waktu 24 jam akan mengembalikan hasil tersebut (hingga 1 MB) dengan header Idempotent-Replayed: true dan tidak dikenakan biaya kedua. Kunci yang lebih panjang dari 255 karakter akan diabaikan, dan permintaan tersebut tidak akan memiliki perlindungan idempotensi. Lihat Retry safely with an idempotency key.

Panjang1 <= length <= 255

Body permintaan

application/json

Respons

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json