Keural API

Keuralに登録されたモデルを、OpenAI Chat Completions形式で呼び出します。

Base URLはhttps://<環境ごとの公開APIドメイン>/llm/v1の形式です。公開APIドメインは環境ごとに異なるため、管理者に確認してください。

埋め込み、画像生成、音声、Responses APIのパスは対応しておらず、404を返します。

利用の流れアンカーリンクをコピー

準備事項アンカーリンクをコピー

APIキーの発行アンカーリンクをコピー

1. 左下のアカウントメニューから設定を開き、APIを選びます。デスクトップアプリとモバイルアプリでは、ツールの欄にあります。
2. API keysタブで、キーの所有先（個人のワークスペースまたは組織のワークスペース）とModel IDを選びます。
3. 必要に応じて、New key expiration (optional, Korea time)を決めます。空欄のままにすると、回収されるまで無期限です。
4. Issue keyを押し、表示されたキーをCopy keyでコピーして、安全な場所に保管します。キーの全文は、このときに1回だけ表示されます。画面を閉じると、再び見ることはできません。

• キーは選択したワークスペースとモデル1つに紐づきます。使用量は、キーを発行した人に帰属します。
• 同じワークスペース・モデルのキーは1つだけです。新しく受け取るには、既存のキーを再発行するか回収します。
• キーを紛失した場合は再発行します。再発行すると、以前のキーは即座に無効になります。
• 発行できるモデルがない場合は、モデルの公開設定、料金プラン、組織のAPI権限を管理者に確認してください。

組織メンバーのAPI権限アンカーリンクをコピー

組織のオーナー・管理者用です。組織のワークスペースでメンバーがキーを受け取るには、管理者が先に許可する必要があります。すべてのメンバーの既定値は遮断です。

組織管理 → Organization APIは、次の3つの領域で構成されます。メニューがない場合は、API機能がオフになっているか、組織管理の権限がないアカウントです。

メンバーが組織を退出したり、組織から除外されたりすると、そのメンバーが組織から受け取ったキーは自動的に回収されます。

クライアントに接続するアンカーリンクをコピー

OpenAI API互換のアプリ（チャットクライアント、IDE拡張、自動化ツールなど）に、次の3つの値を入力します。

1. アプリの設定で、OpenAI互換の接続（Connection）を追加します。
2. Base URLとAPI Keyを入力して保存します。
3. モデル一覧からモデルを選びます。一覧には、キーに接続されたモデルが1つだけ表示されます。
4. 短いメッセージを送り、応答を確認します。

リクエストは次のとおりです。

最初のリクエストアンカーリンクをコピー

export KEURAL_API_KEY='発行されたキー'
export KEURAL_BASE_URL='https://<環境ごとの公開APIドメイン>/llm/v1'
export MODEL_ID='発行画面のモデルID'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"こんにちは。\"}]}"

リクエスト本文のmodelは、キーに接続されたモデルIDと同じである必要があります。provider/モデルIDのように前にパスが付いている場合は、最後の/の後ろを比較します。異なる場合は403を返します。レスポンスのmodelには、常にキーのモデルIDが入ります。

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "こんにちは。"}],
)
print(res.choices[0].message.content)

対応しているリクエストのフィールドアンカーリンクをコピー

最上位のフィールドは、次の18個だけを受け付けます。ほかのフィールドを送ると400を返します。値がnullの省略可能なフィールドは、送信しなかったものとして処理します。

メッセージアンカーリンクをコピー

• toolメッセージは、直前のtool_callsのidに対して1回ずつだけ返答します。
• 画像パーツ（image_url）は、画像を受け付けるモデルのuserメッセージにだけ入れます。http・httpsのアドレス、またはPNG・JPEG・GIF・WebPのbase64データURIを入れます。detailはauto・low・highです。

本文アンカーリンクをコピー

本文のルールに違反すると400になり、paramはbodyです。

ストリーミングアンカーリンクをコピー

リクエストに"stream": trueを入れると、SSEで応答します。チャンクはdata: ...のイベントで送信され、最後にdata: [DONE]が送信されます。"stream_options": {"include_usage": true}を入れると、[DONE]の直前に、トークン使用量のチャンクが追加で送信されます。

include_usageを入れると、すべてのチャンクにusage: nullが入り、最後の使用量のチャンクはchoicesが空の配列になります。ストリーミングでない応答は、入力・出力のトークンがどちらも確認できたときにだけusageを含みます。

応答のidはchatcmpl-<x-request-id>の形式です。すべての応答ヘッダーにはx-request-idが付きます。

ストリーミング中にエラーが発生すると、エラーのJSONを含むdata:のイベントが送信され、[DONE]なしで接続が終わります。チャンク1つが1MiBを超えるか、応答が16MiBを超えると、503で終わります。

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"こんにちは。\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

利用上限アンカーリンクをコピー

リクエストは、ユーザー・組織・モデルごとに、同時リクエスト数、1分あたりのリクエスト数（RPM）、1分あたりのトークン数（TPM）が制限されます。実際の値は、環境ごとに異なります。

1分あたりのトークンは、リクエストを受け取る時点で先に差し引きます。入力は英語4文字につき1トークン、それ以外の文字は1文字につき1トークン、画像1枚は2,000トークンとして計算します。出力はmax_tokens（最大4,096）の分だけ差し引かれるため、出力の上限を必要な分だけ指定すると、利用上限の余裕が大きくなります。

キーの管理アンカーリンクをコピー

設定 → APIのAPI keysタブで、発行されたキーの状態（有効・期限切れ・回収済み）を確認し、再発行したり回収したりします。

キーはkrl_llm_で始まる51文字の文字列です。キーの所有先ごとに、キーは1つだけです。すでにある場合は、新たに発行せず再発行します。有効期限は、今日以降の日付のみ指定できます。

使用量の確認アンカーリンクをコピー

APIで送信したリクエストと使用したトークンは、次の2か所で確認します。

照会の条件アンカーリンクをコピー

条件を決めてSearchを押します。最近のリクエストを反映するにはRefreshを押します。

画面に表示される値アンカーリンクをコピー

• 適用された照会期間（KST）: 実際に照会された期間です。開始日時・終了日時を空欄にした場合や90日を超えた場合は、サーバーが調整した期間が表示されます。
• リクエスト数と入力トークン・出力トークン・合計トークンの合計: 確認された値のみを合算します。確認されていないトークンは0として扱わず、未確認と表示します。
• リクエストの一覧: リクエストごとに、リクエスト日時、Model ID、リクエストの状態、入力・出力・合計のトークンが1行ずつ表示されます。1ページに20件ずつ表示され、Previous・Nextで移動します。

行のRequest detailsを押すと、次の値が展開されます。

ストリーミングのリクエストは、stream_options.include_usageを入れなくても使用量が記録されます。リクエストが途中で切れると、一部確認済みや未確認のまま残ることがあります。

エラーの形式アンカーリンクをコピー

エラーは、OpenAI互換の形式で返します。

{
  "error": {
    "message": "人が読める形式のエラーの説明",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

typeはステータスコードで決まり、codeで原因を区別します。

トラブルシューティングアンカーリンクをコピー

解決しない場合は、管理者に問い合わせてください。次の情報を添えると、原因を早く特定できます。キーの全文とプロンプトの内容は送信しないでください。

• 発生した日時
• 使用したモデルID
• クライアントアプリの名前とバージョン
• 応答ヘッダーのx-request-id
• 画面に表示されたエラーメッセージ