Chat Completions - Hostlinku Docs

Hostlinkuのメインエンドポイント。リクエストおよびレスポンスのフォーマットはOpenAI Chat Completions APIと互換性があるため、base_urlをhttps://api.hostlinku.com/v1に置き換えるだけで、公式のOpenAI SDKを使用することができます。

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

すべてのレスポンスには、ヘッダー x-request-id（リクエスト ID Hostlinku）が含まれており、非ストリーミングの成功レスポンスには、ヘッダー x-model（リクエストを処理したモデルのパブリックslug）も含まれます。

bodyパラメータ

パラメータ	タイプ	デフォルト	説明
`model`	`string`	ない	必須。 slugモデル（例：`gpt-5-5`）。モデルを参照してください。
`messages`	`array`	ない	必須。最低1件の注文が必要です。各項目：`{ role, content, name? }`および`role`に加え、`system`、`user`、`assistant`、`tool`のいずれか1つ。
`temperature`	`number`	プロバイダーのデフォルト設定	範囲：`0`～`2`。数値が高いほどランダム性が高くなる。
`top_p`	`number`	プロバイダーのデフォルト設定	範囲 `0`–`1`。`temperature` からの nucleus sampling の代替案。
`n`	`integer`	`1`	回答選択肢の数、`1`～`8`。
`stream`	`boolean`	`false`	`true`：SSEストリーミング応答用（下記参照）。
`stop`	`string` \| `string[]`	ない	生成を停止させる1つまたは複数のテキストシーケンス。
`max_tokens`	`integer`	モデルの仕様	出力トークンの上限（正）。
`max_completion_tokens`	`integer`	ない	`max_tokens`の現代的な代替案（一部のプロバイダーで使用されている）。
`presence_penalty`	`number`	`0`	範囲：`-2`～`2`。
`frequency_penalty`	`number`	`0`	範囲 `-2`～`2`。
`user`	`string`	ない	不正利用の追跡のためのエンドユーザー識別子。
`tools`	`array`	ない	ツール／関数呼び出しの定義（形式 OpenAI）。
`tool_choice`	`any`	ない	ツールの選択制御（`"auto"`、`"none"`、`{...}`）。
`response_format`	`any`	ない	例：`{ "type": "json_object" }`（JSON出力用、モデルの対応状況による）。
`seed`	`integer`	ない	シード決定論（ベストエフォート、プロバイダによる）。

例：非ストリーミングリクエスト（curl）

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

回答（抜粋）：

{
  "id": "cmpl_…",
  "object": "chat.completion",
  "created": 1770000000,
  "model": "gpt-5-5",
  "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
  }
}

フィールド model には常にパブリックslug Hostlinku（内部 ID ではない）が含まれており、追加ブロック hostlinku は成功レスポンスに必ず存在し、リクエストのコストとレイテンシのみが含まれています：

フィールド	意味
`cost`	リクエストの費用（米ドル、高精度の小数表示）。
`latencyMs`	ゲートウェイでの受信から完了までのリクエストの合計レイテンシ（ミリ秒）。

ストリーミング (`stream: true`)

stream: true に対して、ゲートウェイは Content-Type: text/event-stream (SSE) で応答し、OpenAI 互換のフォーマットでチャンクをストリーミングします（各チャンクは、Hostlinku のパブリック id および同じモデルのslugを使用します）。その後、data: [DONE]でストリームを閉じます：

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

data: {"id":"cmpl_…","model":"gpt-5-5","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"cmpl_…","model":"gpt-5-5","choices":[{"index":0,"delta":{"content":"1"}}]}

data: {"id":"cmpl_…","model":"gpt-5-5","choices":[{"index":0,"delta":{"content":", 2"}}]}

data: [DONE]

重要な注意事項：

ストリームの途中で障害が発生した場合、ゲートウェイは1つのエラーイベント（data: {"error": { "code": …, "message": … }}）を送信し、偽の[DONE]は送信しない。切断されたストリームは、正常に終了したストリームのように見えることは決してない。
固定料金は、ストリーミング終了後の実際の使用量に基づいて計算されます。使用量が確認できない場合は、リクエスト受付時に予約された推定値に基づいて請求されます。
ヘッダー x-request-id は、コンソールのログと関連付けるために、ストリーミング応答にも送信されます。

例：Python（OpenAI公式SDK）

base_url以外のコードに変更はありません。OpenAIのSDKはそのまま使用可能です：

from openai import OpenAI

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

# Non-streaming
response = client.chat.completions.create(
    model="gpt-5-5",
    messages=[
        {"role": "system", "content": "Kamu adalah 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-5",
    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)

このエンドポイントでよく発生するエラー

事例	HTTP	`error.code`
本文が検証に合格しませんでした（フィールドエラー／型エラー／`messages`が空欄）	422	`VALIDATION_FAILED`
APIキーが無効です／有効期限が切れています	401	`UNAUTHORIZED`
APIキーの残高または利用限度額が不足しています	402	`PAYMENT_REQUIRED`
カタログにこのモデルのslugがありません	404	`MODEL_NOT_FOUND`
`max_tokens`はモデルの出力上限を超えています	400	`BAD_REQUEST`
非推奨モデル／現在利用不可	503	`MODEL_UNAVAILABLE`
APIキーごとのレート制限を超過しました	429	`RATE_LIMITED`
アップストリームが利用不可／一時的な障害（再試行可能）	503	`UPSTREAM_ERROR`

エラーエンベロープの完全な形式については、エラーを参照してください。

​bodyパラメータ

​例：非ストリーミングリクエスト（curl）

​ストリーミング (stream: true)

​例：Python（OpenAI公式SDK）

​このエンドポイントでよく発生するエラー

bodyパラメータ

例：非ストリーミングリクエスト（curl）

ストリーミング (`stream: true`)

例：Python（OpenAI公式SDK）

このエンドポイントでよく発生するエラー