テキスト

Chat Completion の作成

チャットメッセージに対する補完を作成します

POST
/v1/chat/completions

リクエストボディ

サポートされるオプションパラメータ、指定可能な値、およびデフォルト値は、選択したモデルによって異なります。サンプリング、推論、またはツールのオプションを設定する前に、モデル詳細を確認してください。一部のモデルにおける 1 を超える n のように、モデルが対応していない設定は 4xx エラーで拒否されます。seed やペナルティなどの軽微なサンプリング設定は、エラーにならず無視される場合があります。

modelstring必須

使用するモデルの ID。利用可能なオプションについては モデル を参照してください。

messagesarray必須

会話を構成するメッセージのリスト。

各メッセージオブジェクトの内容:

  • role (string): system、developer、user、assistant、tool、function
  • content (string | array | null): メッセージの内容

tool_calls を含む assistant メッセージの場合、content は省略するか null に設定できます。

content が配列の場合、TokenLab は対応モデルに対して構造化されたマルチモーダルブロックをサポートします:

  • テキスト: { "type": "text", "text": "..." }
  • 画像: { "type": "image_url", "image_url": { "url": "https://..." } }
  • 動画: { "type": "video_url", "video_url": { "url": "https://..." } }
  • 音声: { "type": "input_audio", "input_audio": { "data": "https://... or base64 data URL", "format": "wav" } }、または { "type": "audio_url", "audio_url": { "url": "https://..." } }

マルチモーダル入力には、パブリックにアクセス可能な https URL を使用してください。画像は base64 データ URL として送信することもできます。サポートされるメディアタイプは、選択したモデルによって異なります。

temperaturenumber

サンプリング温度。サポート状況、許容値、およびデフォルト値は選択したモデルによって異なります。モデルのデフォルト値を使用する場合は、このフィールドを省略してください。

max_tokensinteger

生成するトークンの最大数。max_tokens または max_completion_tokens のいずれか一方のみを送信してください(両方は不可)。別のプロトコル経由で提供されるモデルでは、両方が指定されたリクエストが拒否される場合があります。

思考(Thinking)を行うモデルでは、思考トークンもこの制限にカウントされます。制限が小さすぎると、割り当て全体が思考に消費されてメッセージ本文が空になる可能性があり、その場合でも使用されたトークンは課金対象となります。制限を引き上げるか、モデルが許可している場合は思考を無効にしてください(例: "reasoning_effort": "none")。deepseek-v4.1-flash(エイリアス deepseek-flash)では、"thinking": {"type": "disabled"} でも無効化できます。

リクエストの実行前に、TokenLab は残高がこの最大トークン数をカバーしているか確認します。残高が少ない場合、実際の回答が短くても、非常に大きな値を設定すると 402 が返されることがあります。

streambooleanデフォルト: false

true の場合、部分的なメッセージの差分が Server-Sent Events (SSE) として送信されます。ストリーミング を参照してください。

長い出力(数千トークン以上)の場合は、完全なレスポンスを待つ間にクライアントやプロキシがタイムアウトしないよう、stream: true を設定してください。

stream_optionsobject

ストリーミング用のオプション。include_usage: true を設定すると、data: [DONE] の前に追加でトークン使用量を含むチャンクを 1 つ受信します。設定しない場合、ストリームに使用量は含まれません。

top_pnumber

Nucleus サンプリングのパラメータ。これまたは temperature のどちらか一方のみを変更することをお勧めします。

frequency_penaltynumber

-2.0 から 2.0 までの数値。正の値を指定すると、トークンの繰り返しにペナルティが適用されます。

presence_penaltynumber

-2.0 から 2.0 までの数値。正の値を指定すると、テキスト内にすでに存在するトークンにペナルティが適用されます。

stopstring | array

停止シーケンスまたはシーケンスのリスト。サポート状況およびシーケンスの制限は、選択したモデルによって異なります。

toolsarray

モデルが呼び出す可能性のあるツールのリスト(Function Calling)。各ツールは { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } } です。構造化出力とツール呼び出し を参照してください。

tool_choicestring | object

モデルによるツールの使用方法を制御します。選択肢: auto、none、required、または特定のツールを強制する { "type": "function", "function": { "name": "..." } }。

parallel_tool_callsboolean

選択したモデルでサポートされている場合、1 回のアシスタントターンで複数のツール呼び出しを許可します。

max_completion_tokensinteger

思考トークンを含む補完の上限値。新しい OpenAI モデルファミリーで使用される max_tokens の代替です。いずれか一方のみを送信してください。

reasoning_effortstring

サポートしているモデルの推論エフォート。指定可能な値は選択したモデルによって異なります。

Claude モデルの場合、この値はモデルの思考を設定します(アダプティブシンキングを備えたモデルではエフォートレベル、思考バジェットを使用するモデルではバジェット)。対応しているモデルでは、none で思考をオフにできます。モデルがサポートしていない値は、エラーコード invalid_value の 400 で拒否され、エラーメッセージにサポートされている値がリストされます。思考が有効な間、Claude は 1 以外の temperature、top_k、0.95〜1 の範囲外の top_p、および入力済みの assistant メッセージを拒否します。tool_choice の強制指定はアダプティブシンキングでは機能しますが、思考バジェットでは機能しません。

anthropic_optionsobject

Claude モデル用のオプション。

  • prompt_caching (boolean): プロンプトの先頭部分をキャッシュする場合は true に設定します。TokenLab はシステムプロンプトの末尾と最新のユーザーメッセージをキャッシュポイントとしてマークします。同じコンテンツで始まる後続のリクエストは、キャッシュから読み取られます。このオプションまたは独自に指定する cache_control マークのいずれか一方のみを使用してください。
  • prompt_caching_ttl (string): 5m(デフォルト)または 1h。リクエストを処理するサービスがキャッシュを 1 時間保持できない場合、TokenLab はリクエストを拒否する代わりに 5 分間のキャッシュを使用できます。

extra.prompt_caching および extra.prompt_caching_ttl も同じオプションとして受け入れられます。料金およびキャッシュされたトークンの確認方法については、プロンプトキャッシュ を参照してください。

seedinteger

サポートしているモデル用のサンプリングシード。完全に同一の出力が得られることは保証されません。

ninteger

生成する補完の数。サポートしているモデルでは 1〜128 を受け入れます。多くのモデルは 1 のみをサポートしています。

logprobsboolean

対数確率(log probabilities)を返すかどうか。

top_logprobsinteger

返す上位対数確率の数(0〜20)。logprobs: true が必要です。

top_kinteger

サポートしているモデル用の Top-K サンプリング。

response_formatobject

レスポンスフォーマット。{"type": "text"}(デフォルト)、JSON モードの場合は {"type": "json_object"}、JSON スキーマの場合は {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}} を使用します。サポート状況は選択したモデルによって異なります。構造化出力とツール呼び出し を参照してください。

logit_biasobject

指定したトークンが出現する確率を変更します。トークン ID(文字列)を -100 から 100 までのバイアス値にマッピングします。サポート状況は選択したモデルによって異なります。

service_tierstring

TokenLab は Chat リクエストを標準のサービスクラスで提供し、課金します。auto および default が受け入れられます。flex や priority などのその他の値はリクエストから削除され、リクエストは標準価格で課金されます。

userstring

不正利用の監視を目的とした、エンドユーザーを表す一意の識別子。

レスポンス

idstring

補完の一意な識別子。

objectstring

常に chat.completion。

createdinteger

補完が作成された時点の Unix タイムスタンプ。

modelstring

補完に使用されたモデル。

choicesarray

補完の選択肢(チョイス)のリスト。

各チョイスの内容:

  • index (integer): チョイスのインデックス
  • message (object): 生成されたメッセージ
  • finish_reason (string): モデルが停止した理由(例: stop、length、tool_calls、content_filter)

モデルが思考を行う場合、message には以下が含まれることもあります:

  • reasoning_content (string): 思考テキスト。一部のモデルは要約のみを返すか、テキストを返しません。
  • reasoning_details (array): 署名付きの思考ブロック。ツール呼び出し後などに思考を含む会話を継続するには、これらを assistant メッセージで変更せずにそのまま返送してください。

ストリームでは、同じフィールドが delta.reasoning_content および delta.reasoning_details として届きます。

usageobject

トークン使用量の統計情報。

  • prompt_tokens (integer): プロンプトのトークン数
  • completion_tokens (integer): 補完のトークン数(思考トークンを含む)
  • total_tokens (integer): 使用された合計トークン数
  • prompt_tokens_details.cached_tokens (integer): キャッシュから読み取られたプロンプトトークン数
  • cache_creation_input_tokens (integer): キャッシュに書き込まれたプロンプトトークン数。値が 0 より大きい場合にのみ存在
  • completion_tokens_details.reasoning_tokens (integer): 思考トークン数(モデルから報告された場合)

ストリームでは、stream_options.include_usage が true の場合にのみ使用量が届きます。

リクエスト

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
  }'

マルチモーダルの例

{
  "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
}

レスポンス

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
  }
}

ストリーミング

stream: true を指定すると、レスポンスは text/event-stream になります。各イベントは data: {...} であり、その chat.completion.chunk オブジェクトの choices[].delta に新しいテキスト、ツール呼び出しの引数、または思考テキストが含まれます。ストリームは data: [DONE] で終了します。: で始まる行はキープアライブ用のコメントであるため、無視してください。[DONE] や finish_reason なしで終了したストリームは不完全です。ストリーミング を参照してください。

エラー

エラーには OpenAI スタイルの error オブジェクトが使用されます。一般的なケース: 無効なフィールドまたはモデルが受け入れない値の場合は 400、無効なキーの場合は 401、残高不足の場合は 402、入力がサイズ制限を超えている場合は 413、レート制限の場合は 429 です。API エラーの処理 を参照してください。

認証

BearerAuth
AuthorizationBearer <token>

APIキー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。

場所: header

ヘッダー

X-TokenLab-Delivery-Policy?string

リクエストごとの配信ポリシー。APIキーおよびWorkspaceのデフォルト設定を上書きします。自動的にまず TokenLab Verified を試行し、出力、リクエストの受け入れ、または永続的なリソース作成の前に、一度だけ Official に切り替える場合があります。

指定できる値

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

同じリクエストの二重実行を防ぐためのオプションのキー。リクエストごとにUUIDなどの新しい一意の値を送信し、タイムアウト後の再試行時にも同じ値を保持してください。同じキーを使用した再試行は再実行されず、409とidempotency_replay_unavailable、またはボディが変更された場合は通常idempotency_conflictが返されます。例外として、クライアントの切断後に非ストリーミングの結果が完了した場合、24時間以内に同じキーとボディで再試行すると、その結果(最大1 MB)がヘッダーIdempotent-Replayed: trueと共に返され、二重課金は発生しません。255文字を超えるキーは無視され、そのリクエストには冪等性保護が適用されません。詳細は冪等性キーを使用した安全な再試行を参照してください。

長さ1 <= length <= 255

リクエストボディ

application/json

レスポンス

application/json

application/json

application/json

application/json

application/json

application/json

application/json