Chat Completions APIとは？messages・role・主要パラメータを解説

Chat Completions APIとは、LLMに「会話のやり取り」の形でリクエストを送り、次の発言を生成してもらうためのAPIです。 OpenAIが公開した仕様ですが、現在では多くのプロバイダーやゲートウェイが同じ形式を採用しており、LLM APIの事実上の標準インターフェースになっています。OpenAI互換APIと呼ばれるものは、基本的にこのChat Completions APIの形式を指します。

この記事では、リクエストの中心である messages 配列と role、レスポンスの読み方、そして最初に押さえておきたい主要パラメータを、実際に動くコードとあわせて解説します。

Chat Completions APIとは

Chat Completions APIは、POST /v1/chat/completions というエンドポイントに、使いたいモデル名と会話の履歴をJSONで送り、モデルが生成した「次の発言」を受け取るAPIです。

ポイントは、リクエストの単位が「1つの質問文」ではなく**「会話の履歴全体」**であることです。モデルは渡された会話をすべて読んだうえで、その続きを返します。この設計のおかげで、チャットボットだけでなく、要約・分類・コード生成といった単発のタスクも、同じ形式で扱えます。

messages配列と3つのrole

リクエストの本体は messages という配列です。各要素は role（誰の発言か）と content（発言の内容）を持ちます。

最小構成は user が1件だけの配列ですが、実際には system で前提を置き、user と assistant を交互に並べて会話を組み立てます。system の書き方についてはシステムプロンプトとはで詳しく扱っています。

会話の履歴は毎回送り直す

見落とされやすいのが、Chat Completions APIはステートレスだという点です。サーバー側は前回のやり取りを覚えていません。2ターン目のリクエストには、1ターン目の user と assistant の発言も含めて送る必要があります。

{
  "model": "anthropic-claude-haiku-4-5",
  "messages": [
    {"role": "system", "content": "あなたは簡潔に答えるアシスタントです。"},
    {"role": "user", "content": "東京タワーの高さは？"},
    {"role": "assistant", "content": "東京タワーの高さは333メートルです。"},
    {"role": "user", "content": "スカイツリーは？"}
  ]
}

最後の「スカイツリーは？」だけを送ると、モデルは何について聞かれているのか分かりません。履歴を含めて送ることで、文脈を踏まえた「東京スカイツリーの高さは634メートルです」という応答が返ります。

裏を返せば、会話が長くなるほど毎回送る入力が増え、その分トークン消費も増えます。この仕組みはトークンとはで解説しているコストの考え方と直結しています。

レスポンスの読み方

レスポンスも決まった形をしています。主に見るのは次の3か所です。

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "anthropic-claude-haiku-4-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "東京スカイツリーの高さは634メートルです。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 58,
    "completion_tokens": 17,
    "total_tokens": 75
  }
}

• choices[0].message — モデルの応答本体です。role は assistant、本文は content に入ります。
• finish_reason — 生成が終わった理由です。stop なら自然に完了、length なら max_tokens の上限で途中で切れた、tool_calls ならツール呼び出しが要求された、という意味になります。
• usage — 入力・出力それぞれのトークン数です。課金はこの数値をもとに計算されるので、コストを把握するには必ず見ておきたい項目です。

主要パラメータ

最初に押さえておけば十分な主要パラメータをまとめます。

temperature の実際の効き方はtemperatureとtop_pとは、ストリーミングの実装はストリーミング応答のチュートリアルを参照してください。

実際に使ってみる

FastMetalはChat Completions APIと同じ形式のエンドポイントを提供しています。APIキーを用意して、次のように呼び出します。

curl https://api.fastmetal.ai/v1/chat/completions \
  -H "Authorization: Bearer $FASTMETAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic-claude-haiku-4-5",
    "max_tokens": 200,
    "messages": [
      {"role": "system", "content": "あなたは簡潔に答えるアシスタントです。"},
      {"role": "user", "content": "Chat Completions APIを一文で説明して"}
    ]
  }'

OpenAIのPython SDKを使う場合は、base_url を差し替えるだけです。

from openai import OpenAI

client = OpenAI(
    api_key="<FASTMETAL_API_KEY>",
    base_url="https://api.fastmetal.ai/v1",
)

resp = client.chat.completions.create(
    model="anthropic-claude-haiku-4-5",
    max_tokens=200,
    messages=[
        {"role": "system", "content": "あなたは簡潔に答えるアシスタントです。"},
        {"role": "user", "content": "Chat Completions APIを一文で説明して"},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

model の値を差し替えるだけで、同じコードのまま別のモデルを試せます。1つのAPIキーでフロンティアモデルからオープンモデルまで使えるので、モデル比較のコストが小さいのがゲートウェイ経由の利点です。初めて呼び出す場合は最初のチャット補完を送る手順も参考にしてください。

よくある質問

Q. Chat Completions APIとCompletions APIは何が違いますか？ Completions APIは1本のテキストの続きを生成する旧来の形式で、Chat Completions APIは role 付きの会話履歴を渡す形式です。現在のモデルはChat Completions前提で設計されており、新規開発ではこちらを使うのが標準です。

Q. 会話の履歴はどこまで送ればよいですか？ 文脈の理解に必要な分だけで十分です。すべて送ると入力トークンが増えて費用も上がるため、古いやり取りを要約して渡す、直近数ターンに絞る、といった工夫が一般的です。

Q. モデルを変えるとリクエストの書き方も変わりますか？ Chat Completions形式に対応したモデルであれば、基本的に model の値を変えるだけです。ただしツール呼び出しや画像入力などの対応状況はモデルごとに異なるため、モデルカタログで確認してください。

まとめ

Chat Completions APIは、messages に会話の履歴を積み、choices[0].message で応答を受け取るシンプルな仕組みです。この形式を押さえておけば、OpenAI互換APIを提供するどのサービスでも同じコードが使えます。FastMetalでは円建てのプリペイドで複数のモデルを同じ形式で呼び出せるので、まずはAPIキーを取得して最初のリクエストを送ってみてください。