Chat Completions

Referensi endpoint POST /v1/chat/completions — parameter, streaming SSE, dan contoh curl + Python

Endpoint utama Hostlinku. Format request dan respons kompatibel dengan OpenAI Chat Completions API, sehingga SDK OpenAI resmi bisa dipakai hanya dengan mengganti base_url ke https://api.hostlinku.com/v1.

POST https://api.hostlinku.com/v1/chat/completions
Authorization: Bearer sk-isi-kunci-anda
Content-Type: application/json

Setiap respons menyertakan header x-request-id (ID request Hostlinku) dan, pada respons sukses non-streaming, header x-model (slug model yang dipakai gateway).

Parameter body

Parameter	Tipe	Default	Keterangan
`model`	`string`	—	Wajib. Slug model, mis. `gpt-5-4-mini`. Lihat Model.
`messages`	`array`	—	Wajib. Minimal 1 pesan. Setiap item: `{ role, content, name? }` dengan `role` salah satu dari `system`, `user`, `assistant`, `tool`.
`temperature`	`number`	bawaan provider	Rentang `0`–`2`. Semakin tinggi semakin acak.
`top_p`	`number`	bawaan provider	Rentang `0`–`1`. Alternatif nucleus sampling dari `temperature`.
`n`	`integer`	`1`	Jumlah pilihan jawaban, `1`–`8`.
`stream`	`boolean`	`false`	`true` untuk respons streaming SSE (lihat di bawah).
`stop`	`string` \| `string[]`	—	Satu atau beberapa urutan teks yang menghentikan generasi.
`max_tokens`	`integer`	bawaan model	Batas token output (positif).
`max_completion_tokens`	`integer`	—	Alternatif modern `max_tokens` (dipakai sebagian provider).
`presence_penalty`	`number`	`0`	Rentang `-2`–`2`.
`frequency_penalty`	`number`	`0`	Rentang `-2`–`2`.
`user`	`string`	—	Identifier pengguna akhir untuk pelacakan penyalahgunaan.
`tools`	`array`	—	Definisi tool/function calling (format OpenAI).
`tool_choice`	`any`	—	Kontrol pemilihan tool (`"auto"`, `"none"`, `{...}`).
`response_format`	`any`	—	Mis. `{ "type": "json_object" }` untuk output JSON (tergantung dukungan model).
`seed`	`integer`	—	Seed determinisme (best-effort, tergantung provider).

Hanya parameter di atas yang diproses

Body divalidasi dengan skema ketat sebelum diteruskan ke provider. Field di luar daftar di atas akan diabaikan (dibuang dari body), dan body yang tidak valid ditolak dengan 422 VALIDATION_FAILED beserta detail per field. messages[].content menerima string maupun array konten multimodal (format OpenAI) selama model mendukungnya.

Contoh: request non-streaming (curl)

curl https://api.hostlinku.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-isi-kunci-anda" \
  -d '{
    "model": "gpt-5-4-mini",
    "messages": [
      { "role": "system", "content": "Anda asisten yang ringkas." },
      { "role": "user", "content": "Jelaskan apa itu API gateway dalam dua kalimat." }
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

Respons (dipotong):

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1770000000,
  "model": "gpt-5-4-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "API gateway adalah …" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 30, "completion_tokens": 55, "total_tokens": 85 },
  "hostlinku": {
    "cost": 0.00021,
    "latencyMs": 940,
    "gateway": "…",
    "upstreamRequestId": "…",
    "usageSource": "upstream"
  }
}

Field tambahan hostlinku selalu ada pada respons sukses dari gateway:

Field	Arti
`cost`	Biaya request dalam USD (angka desimal presisi tinggi).
`latencyMs`	Latensi total request dari diterima gateway sampai selesai, milidetik.
`gateway`	ID gateway upstream yang melayani request (berguna saat failover).
`upstreamRequestId`	ID request di sisi provider, untuk korelasi saat troubleshooting.
`usageSource`	Asal data usage: dari provider (`upstream`) atau tidak tersedia (`none`).

Streaming (`stream: true`)

Dengan stream: true, gateway merespons dengan Content-Type: text/event-stream (SSE) dan meneruskan chunk dari provider apa adanya, lalu menutup stream dengan data: [DONE]:

curl https://api.hostlinku.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-isi-kunci-anda" \
  -d '{
    "model": "gpt-5-4-mini",
    "messages": [{ "role": "user", "content": "Hitung 1 sampai 5." }],
    "stream": true
  }'

data: {"id":"chatcmpl-…","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"chatcmpl-…","choices":[{"index":0,"delta":{"content":"1"}}]}

data: {"id":"chatcmpl-…","choices":[{"index":0,"delta":{"content":", 2"}}]}

data: [DONE]

Catatan penting:

Jika terjadi kegagalan di tengah stream, gateway mengirim satu event error (data: {"error": { "code": …, "message": … }}) dan tidak mengirim [DONE] palsu — stream yang terputus tidak pernah terlihat seperti stream yang selesai normal.
Biaya tetap dihitung dari usage nyata setelah stream selesai; bila provider tidak mengirimkan usage, tagihan memakai estimasi yang sudah direservasi saat request masuk.
Header x-request-id juga dikirim pada respons streaming untuk menghubungkan dengan log di console.

Contoh: Python (SDK resmi OpenAI)

Tidak ada perubahan kode selain base_url — SDK OpenAI bisa langsung dipakai:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.hostlinku.com/v1",
    api_key="sk-isi-kunci-anda",
)

# Non-streaming
response = client.chat.completions.create(
    model="gpt-5-4-mini",
    messages=[
        {"role": "system", "content": "Anda asisten yang ringkas."},
        {"role": "user", "content": "Halo dari SDK OpenAI!"},
    ],
)
print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="gpt-5-4-mini",
    messages=[{"role": "user", "content": "Tulis satu paragraf pendek."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Ganti base_url di library lain

Pola yang sama berlaku untuk openai-node (new OpenAI({ baseURL: 'https://api.hostlinku.com/v1' })), LangChain (baseURL/openai_api_base), LiteLLM client, dan alat lain yang mendukung endpoint OpenAI-compatible.

Error yang umum di endpoint ini

Kasus	HTTP	`error.code`
Body tidak lolos validasi (field salah/tipe salah/`messages` kosong)	422	`VALIDATION_FAILED`
Kunci tidak valid / kedaluwarsa	401	`UNAUTHORIZED`
Saldo atau limit kunci tidak cukup	402	`PAYMENT_REQUIRED`
Model tidak ada / deprecated / sedang tidak tersedia	503	`MODEL_UNAVAILABLE`
Rate limit per kunci terlampaui	429	`RATE_LIMITED`
Provider upstream gagal setelah failover	502	`UPSTREAM_ERROR`

Format lengkap error envelope ada di Error.

Chat Completions

Parameter body

Contoh: request non-streaming (curl)

Streaming (`stream: true`)

Contoh: Python (SDK resmi OpenAI)

Error yang umum di endpoint ini

PRODUK

DOKUMENTASI

BANTUAN

Chat Completions

Parameter body

Contoh: request non-streaming (curl)

Streaming (stream: true)

Contoh: Python (SDK resmi OpenAI)

Error yang umum di endpoint ini

PRODUK

DOKUMENTASI

BANTUAN

Streaming (`stream: true`)