リクエスト例

/v1/chat/completions エンドポイント詳解

本ドキュメントでは /v1/chat/completions エンドポイントのリクエストパラメータとレスポンス結果を詳しく解説し、AIone の OpenAI Compatible インターフェースを素早く使い始められるようにします。

Gemini 画像生成モデルや aspect_ratio、image_size、top_k などの画像関連パラメータについては、「Gemini 画像生成」もあわせてご確認ください。

1. リクエストパラメータ詳解

必須パラメータ

model（必須）

使用するモデル ID です。完全な一覧はモデルと料金をご確認ください。

"model": "claude-sonnet-4-6"

messages（必須）

会話メッセージの配列です。各メッセージには role と content が含まれます。

"messages": [
  {"role": "system", "content": "あなたはプロフェッショナルな技術コンサルタントです"},
  {"role": "user", "content": "API Gateway とは何か説明してください"}
]

role の値：

• system：システムプロンプト。AI の振る舞いや役割を設定します
• user：ユーザーメッセージ
• assistant：AI の回答（マルチターン会話で使用）

オプションパラメータ

temperature（デフォルト 1.0）

出力のランダム性を制御します。範囲は 0〜2 です。

• 0：決定論的出力。コード生成やデータ抽出に適しています
• 0.7：創造性と一貫性のバランス。日常利用に推奨
• 1.5+：高い創造性。クリエイティブライティングに適しています

max_tokens

生成する最大トークン数です。設定しない場合はモデルのデフォルト値が使用されます。

stream（デフォルト false）

ストリーミングレスポンスを有効にするかどうかです。true に設定すると SSE フォーマットのデータストリームが返されます。

対話型のシーンでは stream: true を強く推奨します。 最初のトークンが届くまでの待ち時間を 10 秒以上から 2〜3 秒に短縮できます。非ストリーミングリクエストではモデルがすべてのコンテンツを生成し終わるまで待つ必要があり、大規模モデルが長い回答を生成する場合はタイムアウトしやすくなります。

top_p（デフォルト 1.0）

核サンプリングパラメータです。通常は temperature と top_p のどちらか一方のみを調整してください。

tools

Function calling のツール定義です。モデルに外部関数を呼び出させることができます。

"tools": [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "指定した都市の天気を取得する",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string", "description": "都市名"}
        },
        "required": ["city"]
      }
    }
  }
]

response_format

レスポンスフォーマットの指定です。JSON mode をサポートします。

"response_format": {"type": "json_object"}

2. 完全なリクエスト例（ストリーミング、推奨）

{
  "model": "claude-sonnet-4-6",
  "messages": [
    {"role": "system", "content": "あなたは親切なアシスタントです。簡潔な日本語で回答してください。"},
    {"role": "user", "content": "RESTful API とは何ですか？3 文で説明してください。"}
  ],
  "max_tokens": 500,
  "temperature": 0.7,
  "stream": true
}

3. ストリーミングレスポンスのフォーマット

stream: true を有効にすると、SSE（Server-Sent Events）フォーマットで返されます。各チャンクは JSON オブジェクトです。

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":"REST"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":"ful"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

主要フィールド：

• choices[0].delta.content：今回のインクリメンタルなテキスト断片
• choices[0].finish_reason：null は未完了、stop は正常完了、length は max_tokens 到達を示します

4. 非ストリーミングレスポンスのフォーマット

{
  "id": "chatcmpl-abc123def456",
  "object": "chat.completion",
  "created": 1711500000,
  "model": "claude-sonnet-4-6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "RESTful API とは HTTP プロトコルに基づくインターフェース設計スタイルです..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 85,
    "total_tokens": 127
  }
}

主要フィールドの説明：

5. 注意事項

1. ストリーミングモードを推奨：対話型シーン（チャット、IDE コーディング）では常に stream: true を使用してください。体験と安定性が非ストリーミングより大幅に向上します
2. 権限とキー：API キーが有効であり、選択したモデルへのアクセス権限があることを確認してください
3. パラメータフォーマット：messages は配列形式で、各メッセージに role と content が必須です
4. トークン課金：入力トークンと出力トークンは個別に課金され、単価が異なります
5. 互換性：AIone は OpenAI SDK と完全互換のため、openai ライブラリをそのまま使用できます
6. エラーハンドリング：429（レートリミット）と 5xx（サーバーエラー）にはエクスポネンシャルバックオフによるリトライを推奨します