Teks

Buat Chat Completion

Membuat completion untuk pesan chat

POST
/v1/chat/completions

Body Permintaan

Parameter opsional yang didukung, nilai yang diterima, dan default bergantung pada model yang dipilih. Periksa detail model sebelum mengatur opsi sampling, reasoning, atau tool. Kontrol yang tidak dapat dipenuhi oleh model, seperti n di atas 1 pada beberapa model, akan ditolak dengan error 4xx. Kontrol sampling minor seperti seed atau penalti dapat diabaikan sebagai gantinya.

modelstringwajib

ID model yang akan digunakan. Lihat Model untuk opsi yang tersedia.

messagesarraywajib

Daftar pesan yang menyusun percakapan.

Setiap objek pesan berisi:

  • role (string): system, developer, user, assistant, tool, function
  • content (string | array | null): Konten pesan

Untuk pesan assistant yang berisi tool_calls, content dapat dihilangkan atau diatur ke null.

Jika content berupa array, TokenLab mendukung blok multimodal terstruktur untuk model yang kompatibel:

  • teks: { "type": "text", "text": "..." }
  • gambar: { "type": "image_url", "image_url": { "url": "https://..." } }
  • video: { "type": "video_url", "video_url": { "url": "https://..." } }
  • audio: { "type": "input_audio", "input_audio": { "data": "https://... or base64 data URL", "format": "wav" } }, atau { "type": "audio_url", "audio_url": { "url": "https://..." } }

Untuk input multimodal, gunakan URL https yang dapat diakses publik. Gambar juga dapat dikirim sebagai URL data base64. Tipe media yang didukung bergantung pada model yang dipilih.

temperaturenumber

Suhu sampling (temperature). Dukungan, nilai yang diizinkan, dan default bergantung pada model yang dipilih; kosongkan field ini untuk menggunakan nilai default-nya.

max_tokensinteger

Jumlah token maksimum yang akan dihasilkan. Kirim salah satu antara max_tokens atau max_completion_tokens, jangan keduanya: model yang disajikan melalui protokol lain dapat menolak permintaan yang menyertakan keduanya.

Pada model yang melakukan proses berpikir (thinking), token berpikir dihitung dalam batas ini. Jika batasnya terlalu kecil, seluruh anggaran dapat habis untuk berpikir dan menyisakan isi pesan yang kosong, dan token yang digunakan tetap ditagihkan. Naikkan batasnya, atau nonaktifkan proses berpikir jika model mengizinkannya, misalnya dengan "reasoning_effort": "none". Pada deepseek-v4.1-flash (alias deepseek-flash), "thinking": {"type": "disabled"} juga menonaktifkannya.

Sebelum permintaan dijalankan, TokenLab memeriksa apakah saldo Anda mencukupi batas maksimum ini. Nilai yang sangat besar dapat mengembalikan 402 jika saldo rendah, meskipun jawabannya singkat.

streambooleanbawaan: false

Jika true, delta pesan parsial dikirim sebagai server-sent events (SSE). Lihat Streaming.

Untuk output yang panjang (ribuan token atau lebih), atur stream: true agar klien dan proksi tidak mengalami timeout saat menunggu respons lengkap.

stream_optionsobject

Opsi untuk streaming. Atur include_usage: true untuk menerima satu chunk tambahan berisi penggunaan token sebelum data: [DONE]. Tanpa opsi ini, stream tidak menyertakan data penggunaan.

top_pnumber

Parameter nucleus sampling. Kami menyarankan untuk mengubah parameter ini atau temperature, jangan keduanya.

frequency_penaltynumber

Angka antara -2.0 dan 2.0. Nilai positif memberikan penalti pada token yang berulang.

presence_penaltynumber

Angka antara -2.0 dan 2.0. Nilai positif memberikan penalti pada token yang sudah muncul dalam teks.

stopstring | array

Sekuens henti atau daftar sekuens. Dukungan dan batas sekuens bergantung pada model yang dipilih.

toolsarray

Daftar tool yang dapat dipanggil oleh model (function calling). Setiap tool adalah { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } }. Lihat Output terstruktur dan pemanggilan tool.

tool_choicestring | object

Mengontrol cara model menggunakan tool. Opsi: auto, none, required, atau { "type": "function", "function": { "name": "..." } } untuk memaksakan satu tool.

parallel_tool_callsboolean

Izinkan beberapa panggilan tool dalam satu giliran assistant, jika didukung oleh model yang dipilih.

max_completion_tokensinteger

Batas atas untuk completion, termasuk token berpikir. Alternatif untuk max_tokens yang digunakan oleh keluarga model OpenAI yang lebih baru. Kirim hanya salah satu dari keduanya.

reasoning_effortstring

Upaya penalaran (reasoning effort) untuk model yang mendukungnya. Nilai yang diterima bergantung pada model yang dipilih.

Untuk model Claude, nilai ini mengatur proses berpikir model: tingkat upaya pada model dengan adaptive thinking, atau anggaran berpikir (thinking budget) pada model yang menggunakannya. none menonaktifkan proses berpikir pada model yang mengizinkannya. Nilai yang tidak didukung oleh model akan ditolak dengan 400, kode invalid_value, dan error tersebut akan mencantumkan nilai-nilai yang didukung. Saat proses berpikir aktif, Claude menolak temperature selain 1, top_k, top_p di luar 0.95–1, serta pesan assistant yang telah diisi sebelumnya (prefilled). tool_choice yang dipaksakan berfungsi dengan adaptive thinking tetapi tidak dengan thinking budget.

anthropic_optionsobject

Opsi untuk model Claude.

  • prompt_caching (boolean): Atur true untuk menyimpan cache awal prompt. TokenLab menandai akhir dari prompt sistem dan pesan pengguna terbaru sebagai titik cache. Permintaan berikutnya yang dimulai dengan konten yang sama akan membacanya dari cache. Gunakan opsi ini atau tanda cache_control Anda sendiri, jangan keduanya.
  • prompt_caching_ttl (string): 5m (default) atau 1h. Ketika layanan yang menangani permintaan tidak dapat menyimpan cache selama satu jam, TokenLab dapat menggunakan cache lima menit alih-alih menolak permintaan tersebut.

extra.prompt_caching dan extra.prompt_caching_ttl diterima sebagai opsi yang sama. Lihat Prompt caching untuk harga dan cara memeriksa token yang di-cache.

seedinteger

Seed sampling untuk model yang mendukungnya. Output yang identik tidak dijamin.

ninteger

Jumlah completion yang akan dihasilkan. Model yang mendukungnya menerima 1-128. Banyak model hanya mendukung 1.

logprobsboolean

Menentukan apakah akan mengembalikan probabilitas log (log probabilities).

top_logprobsinteger

Jumlah probabilitas log teratas yang akan dikembalikan (0-20). Memerlukan logprobs: true.

top_kinteger

Sampling Top-K untuk model yang mendukungnya.

response_formatobject

Format respons. Gunakan {"type": "text"} (default), {"type": "json_object"} untuk mode JSON, atau {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}} untuk skema JSON. Dukungan bergantung pada model yang dipilih. Lihat Output terstruktur dan pemanggilan tool.

logit_biasobject

Memodifikasi kemungkinan munculnya token tertentu. Petakan ID token (sebagai string) ke nilai bias dari -100 hingga 100. Dukungan bergantung pada model yang dipilih.

service_tierstring

TokenLab melayani dan menagih permintaan Chat pada tingkat layanan (service tier) standar. auto dan default dapat diterima. Nilai lain, seperti flex atau priority, akan dihapus dari permintaan, dan permintaan akan ditagih dengan harga standar.

userstring

Pengidentifikasi unik yang mewakili pengguna akhir Anda untuk pemantauan penyalahgunaan.

Respons

idstring

Pengidentifikasi unik untuk completion.

objectstring

Selalu chat.completion.

createdinteger

Timestamp Unix saat completion dibuat.

modelstring

Model yang digunakan untuk completion.

choicesarray

Daftar pilihan completion.

Setiap pilihan berisi:

  • index (integer): Indeks pilihan
  • message (object): Pesan yang dihasilkan
  • finish_reason (string): Alasan model berhenti, misalnya stop, length, tool_calls, atau content_filter

Saat model berpikir, message juga dapat berisi:

  • reasoning_content (string): Teks proses berpikir. Beberapa model hanya mengembalikan ringkasan, atau tidak ada teks sama sekali.
  • reasoning_details (array): Blok proses berpikir beserta signature-nya. Untuk melanjutkan percakapan yang menyertakan proses berpikir, misalnya setelah panggilan tool, kirimkan kembali tanpa perubahan dalam pesan assistant.

Dalam sebuah stream, field yang sama akan diterima sebagai delta.reasoning_content dan delta.reasoning_details.

usageobject

Statistik penggunaan token.

  • prompt_tokens (integer): Token dalam prompt
  • completion_tokens (integer): Token dalam completion, termasuk token berpikir
  • total_tokens (integer): Total token yang digunakan
  • prompt_tokens_details.cached_tokens (integer): Token prompt yang dibaca dari cache
  • cache_creation_input_tokens (integer): Token prompt yang ditulis ke cache. Hanya ada jika nilainya lebih besar dari 0
  • completion_tokens_details.reasoning_tokens (integer): Token berpikir, jika model melaporkannya

Dalam stream, data penggunaan hanya masuk ketika stream_options.include_usage bernilai true.

Permintaan

curl -X POST "https://api.tokenlab.sh/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 1000
  }'

Contoh Multimodal

{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this video briefly." },
        { "type": "video_url", "video_url": { "url": "https://example.com/demo.mp4" } }
      ]
    }
  ],
  "max_tokens": 64
}

Respons

Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

Streaming

Dengan stream: true, respons berupa text/event-stream. Setiap event berupa data: {...} dengan objek chat.completion.chunk yang choices[].delta-nya membawa teks baru, argumen panggilan tool, atau teks proses berpikir. Stream diakhiri dengan data: [DONE]. Baris yang diawali dengan : adalah komentar keep-alive: abaikan baris tersebut. Stream yang berakhir tanpa [DONE] atau tanpa finish_reason tidaklah lengkap. Lihat Streaming.

Error

Error menggunakan objek error bergaya OpenAI. Kasus umum: 400 untuk field yang tidak valid atau nilai yang tidak diterima model, 401 untuk key yang tidak valid, 402 untuk saldo tidak mencukupi, 413 untuk input yang melebihi batas ukuran, dan 429 untuk batas laju (rate limit). Lihat Menangani error API.

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