Teks
Create Message
Membuat pesan menggunakan format Anthropic Messages API
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
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.
Versi API Anthropic. SDK Anthropic mengirimkannya untuk Anda; gunakan 2023-06-01 saat Anda memanggil API secara langsung.
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.
ID model yang mendukung format anthropic_messages. Periksa detail model untuk kemampuan saat ini.
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..." } }
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.
Prompt sistem sebagai string atau array blok konten teks, terpisah dari array messages.
Suhu sampling. Dukungan, nilai yang diizinkan, dan nilai default bergantung pada model yang dipilih; hilangkan kolom ini untuk menggunakan nilai defaultnya.
falseMengembalikan respons sebagai aliran peristiwa yang dikirim server (server-sent events). Lihat Streaming.
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.
Alat yang tersedia untuk model. Dukungan bergantung pada model yang dipilih.
Objek pemilihan alat asli, contohnya {"type":"auto"}. Jenis yang didukung bergantung pada model yang dipilih.
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.
Parameter sampling nucleus. Gunakan suhu atau top_p, jangan keduanya. Dukungan bergantung pada model yang dipilih.
Hanya melakukan sampling dari K opsi teratas untuk setiap token. Dukungan bergantung pada model yang dipilih.
Urutan berhenti kustom yang akan menyebabkan model berhenti menghasilkan teks. Hingga 8.191 entri.
Metadata permintaan dalam format Anthropic. user_id adalah pengenal buram untuk pengguna akhir Anda.
Hanya auto dan standard_only yang berpengaruh. TokenLab hanya mengenakan biaya untuk tingkat standar dan mengabaikan nilai lainnya.
Respons
Pengenal pesan unik.
Selalu message.
Selalu assistant.
Array blok konten, seperti text, thinking, atau tool_use.
Model yang menghasilkan respons.
Alasan pembuatan berhenti, seperti end_turn, max_tokens, stop_sequence, atau tool_use. Model dapat mengembalikan nilai lain, misalnya refusal.
Urutan berhenti yang mengakhiri pembuatan, atau null.
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
{
"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
200saat kegagalan terjadi. Kegagalan setelah aliran dimulai akan tiba sebagai peristiwaevent: errordengan 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"
}| Status | error.type | Penyebab umum |
|---|---|---|
| 400 | invalid_request_error | Kolom yang hilang atau tidak valid, model tidak dikenal, atau model yang tidak menerima format Messages |
| 401 | authentication_error | API key hilang atau tidak valid |
| 402 | billing_error | Saldo 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 |
| 403 | permission_error | API key tidak dapat menggunakan model yang diminta, atau akun ditangguhkan atau dibatasi |
| 409 | conflict_error | Percobaan ulang dengan Idempotency-Key yang sama. Lihat Retry safely with an idempotency key |
| 413 | request_too_large | Input permintaan terlalu besar |
| 429 | rate_limit_error | Terlalu banyak permintaan |
| 500, 502, 503 | api_error atau overloaded_error | Permintaan tidak dapat diselesaikan, atau tidak ada rute yang tersedia untuk saat ini. Coba lagi nanti |
| 504 | timeout_error | Permintaan kehabisan waktu (timeout) |
Antarmuka terkait
- Hitung token pesan: estimasi token input dari permintaan sebelum Anda mengirimnya.
- Message Batches menjalankan banyak permintaan Messages secara asinkron: buat, daftar, ambil, batalkan, dapatkan hasil, dan hapus.
Otorisasi
BearerAuth Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.
Lokasi: header
Header
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"
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.
1 <= length <= 255Body 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