最終更新日 2025年09月04日(木)

/v1/chat/completions​ エンドポイントは、提供された一連の入力メッセージに対する会話補完を生成します。モデルを指定したり、temperature​ などの生成設定を調整したり、応答をリアルタイムでストリーミングしたりすることができます。モデルが呼び出す tools​ を指定することもできます。

利用可能なチャットモデル​を参照してください。

リクエストボディパラメータ

パラメータを使用して、会話補完を生成する方法を管理します。

必須パラメータ

フィールド	型	説明	例
model​	文字列​	補完に使用するモデル (通常は INFERENCE_MODEL_ID​ 環境設定)	"claude-4-sonnet"​
messages	配列​	モデルが次の応答を生成するために使用する messages オブジェクト (ユーザーとアシスタントの会話ターン) の配列	[{"role": "user", "content": "Why is Heroku so awesome?"}]​

任意のパラメータ

フィールド	型	説明	デフォルト	例
extended_thinking​	オブジェクト​	(Claude Sonnet 3.7 と 4 のみ) 拡張思考​を有効にして内部推論ステップを実行します (Anthropic の拡張思考ドキュメント)​を参照)	null​	{"enabled": true, "budget_tokens": 1024, "include_reasoning": true}​
max_completion_tokens​	整数​	モデルが停止する前に生成できるトークンの最大数 (各トークンは通常約 4 文字のテキストを表す)* 最大値: Haiku モデルでは 4096​、Sonnet モデルでは 8192​	変動​	1024​
modalities​	配列​	モデルに生成させる出力タイプ (現在サポートされているのはテキストのみ)	["text"]​	["text"]​
stop​	配列​	応答に文字列のいずれかが含まれている場合に、モデルがそれ以上トークンを生成しないようにする文字列のリスト	null​	["foo"]​
stream​	ブール値​	サーバーから送信されたイベントを介して応答を段階的にストリーミングします (チャットインターフェースやタイムアウトエラーの回避に便利)	false​	true​
temperature​	フロート​	応答のランダム性を制御します。値が 0​ に近いほど高確率のトークンが優先され、より焦点が絞られた応答になります。また、値が 1.0​ に近いほど生成されたトークンごとにより広範囲の選択肢からサンプリングされるため、より多様な応答が促進されます。 範囲: 0.0​ ～ 1.0	1.0​	0.2​
top_k​	整数​	後続の各トークンについて上位 K 個のオプションからサンプルを抽出し、低い値はロングテールの応答を制限します	0	100
tool_choice​	列挙​または​オブジェクト​	tools​ に列挙されているツールの 1 つ以上をモデルに強制的に使用させます (「tool_choice)​」を参照)	"required"​	"auto"​
tools​	配列​	モデルが呼び出すことができるツールのリスト (「tools)​」を参照)	[]​	「tools」セクションの JSON の例​を参照
top_p​	フロート​	次のトークンを生成するときに考慮するトークンの割合を累積確率で指定します 範囲: 0​ ～ 1.0​	0.999​	0.95​
allow_ignored_params​	ブール値​	エラーをスローする代わりに、リクエスト内のサポートされていないパラメータを無視します	false​	true​

* 廃止予定の max_tokens​ パラメータと同様に、リクエストごとにこれらのうち 1 つのみを使用してください

extended_thinking オブジェクト

extended_thinking​ オブジェクトを使用すると、最終出力を生成する前にモデルが推論ステップに追加の内部トークンを使用するように要求できます。通常、拡張思考を有効にすると、複雑なタスクにおける推論能力が向上します。

フィールド	型	説明	デフォルト
enabled​	ブール値​	拡張思考が有効になっているかどうかを示します	false​
budget_tokens​	整数​	内部推論中に使用する内部「思考」トークンの最大数 ​>= 1024​ かつ < max_tokens​ である必要があります​	null​
include_reasoning​	ブール値​	モデルの内部推論トレースが応答に含まれているかどうかを示します	false​

オブジェクトの tools 配列

tools​ を使用すると、呼び出すことができるツールの配列をモデルに提供できます。tool_choice を使用して、モデルがツールを呼び出す方法を指定します。 これが提供された場合、モデルは role="assistant" により生成されたメッセージの中で tool_calls を返す場合があり、指定されたツールを実行するようシステムに指示し、その結果を role="tool" のメッセージで返します。

これらのツールは拡張プロンプトの形式でモデルに提供され、それ以上の検証は行われないことに注意してください。 モデルは指定されたツール配列に存在しないツール名を作成する場合があります。これを避けるため、モデルが tool_calls のアシスタントメッセージを返したときに、ツール検証を実行することをお勧めします。

フィールド	型	説明	例
type​	列挙<文字列>	ツールの種別 常に​ "function")	"function"​
function​	オブジェクト​	呼び出す関数​についての詳細	例)

function オブジェクト

フィールド	型	説明	例
description​	文字列​	関数が行う処理についての説明。モデルが関数をいつどのように呼び出すかを選択するときに使用します。	"This function calculates X"​
name​	文字列​	呼び出される関数の名前	"example_function"​
parameters​	オブジェクト​	関数が JSON スキーマオブジェクトとして受け入れるパラメータ	{"type": "object", "properties": {}}​

tools 配列の例

[
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. Portland, OR"
            }
          },
          "required": ["location"]
        }
      }
    }
  ]

tool_choice オブジェクト

tool_choice​ オブジェクトは、モデルが提供された tools をどのように使用するかを指定します。

これは、文字列 (none​、auto​、required​) または tool_choice​ オブジェクトの場合があります。 none​ はモデルがツールを呼び出さないことを意味します。auto​ の場合、モデルは提供されたツールを 0 ～多数呼び出すことができ、required​ の場合は、モデルがユーザーに応答する前に少なくとも 1 つ以上のツールを呼び出すことを強制します。

モデルに特定のツールの呼び出しを強制するには、tools​ オブジェクトで単一のツールを指定して "tools": "required"​ を渡すか、必要な関数を指定する tool_choice​ オブジェクトを渡してツールの選択を強制します。

フィールド	型	説明	例
type​	列挙<文字列>	ツールの種別 常に​ "function"​	"function"​
function​	オブジェクト​	関数の名前を含む JSON オブジェクト	{"name": "example_function"}​

オブジェクトの messages 配列

messages​ オブジェクトはメッセージオブジェクトの配列です。

各メッセージはメッセージのスキーマを決定する role​ フィールドを指定する必要があります (以下を参照)。

現在サポートされているタイプは、user​、assistant​、system​、tool​ です。

最新のメッセージで assistant​ ロールを使用している場合、モデルはその最新メッセージの内容から回答を続行します。

role=user メッセージ

user​ メッセージは、モデルにクエリを送信し、応答を促す主な方法です。

フィールド	型	説明	必須かどうか	例
role​	文字列​	メッセージのロール (user​)	はい	"user"​
content​	文字列​、オブジェクト​、オブジェクトの配列​	ユーザーメッセージの内容	はい	"What is the weather?"​

role=assistant メッセージ

通常、assistant​ メッセージはモデルによってのみ生成されますが、独自のメッセージを作成したり、部分的に入力された assistant​ の応答を事前に入力したりすることで、モデルが次のターンに生成するコンテンツに影響を与えることができます。

フィールド	型	説明	必須かどうか	例
role​	文字列​	メッセージのロール 常に​ "assistant"​	はい	"assistant"​
content​	文字列​、オブジェクト​、オブジェクトの配列​	アシスタントメッセージの内容	はい	"Here is the information"​
tool_calls​	配列​	ツール呼び出し​要求オブジェクトの配列	なし	[{"id": "tool_call_12345", "type": "function", "function": {"name": "my_cool_tool", "arguments": {"some_input": 123}}}]​

ツール呼び出しオブジェクト

フィールド	型	説明	例
id​	文字列​	ツール呼び出しの一意の ID	"tooluse_abc123"​
type​	文字列​	呼び出しの種別 (現在は常に "function"​)	"function"​
function	オブジェクト​	関数​呼び出しの詳細	ツール呼び出しの例​を参照

​ツール呼び出しの例

tools によってオプションで指定されたツールの呼び出しをモデルが決定したときの tool_calls​ オブジェクトの例を以下に示します。

"tool_calls": [
  {
    "id": "toolu_02F9GXvY5MZAq8Lw3PTNQyJK",
    "type": "function",
    "function": {
        "name": "get_weather",
        "arguments": "{\"location\":\"Portland, OR\"}"
    }
  }
]

関数オブジェクト

フィールド	型	説明	例
name​	文字列​	呼び出すツールの名前	"your_cool_tool"​
arguments	文字列​	ツール引数の JSON エンコードされた文字列	"{}"​

role=system メッセージ

system​ メッセージは、モデルの応答に影響を与えるためにモデルに提供される、プロンプトの「プレフィックス」のようなものです。

フィールド	型	説明	必須かどうか	例
role​	文字列​	メッセージのロール (system​)	はい	"system"​
content​	文字列​、オブジェクト​、オブジェクトの配列​	システムメッセージの内容	はい	"You are a helpful assistant. You favor brevity and avoid hedging. You readily admit when you don't know an answer."​

role=tool メッセージ

tool​ メッセージオブジェクトを使用すると、指定されたツールの結果 (出力) をモデルに伝えることができます。

フィールド	型	説明	必須かどうか	例
role​	文字列​	メッセージのロール (tool​)	はい	"get_weather"​
content​	文字列​、オブジェクト​、オブジェクトの配列​	ツール呼び出し結果 (出力)	はい	"Rainy and 84º"​
tool_call_id​	文字列​	このメッセージが応答するツール呼び出し	はい	"toolu_02F9GXvY5MZAq8Lw3PTNQyJK"​

リクエストヘッダー

次の例では、モデルリソースに「INFERENCE​」(デフォルト) というエイリアスがあると仮定しています。

ヘッダー	型	説明
Authorization	文字列​	AI アドオンの 'INFERENCE_KEY'​ の値 (API ベアラートークン)

すべての推論の curl​ リクエストには、Heroku 推論キーを含む Authorization​ ヘッダーを含める必要があります。

応答形式

リクエストが成功すると、API は次の構造で JSON オブジェクトを返します。

フィールド	型	説明	例
id​	文字列​	チャット補完の一意の識別子	"chatcmpl-12345"​
object​	文字列​	応答オブジェクトタイプ 常に​ "chat.completion"​	"chat.completion"​
created​	整数​	補完が作成された時点の UNIX タイムスタンプ	1745623456​
model​	文字列​	応答を生成するために使用するモデル ID	"claude-4-sonnet"​
system_fingerprint​	文字列​	(任意) 出力を生成したシステムバージョンのフィンガープリント	"heroku-inf-abc123"​
choices​	オブジェクトの配列​	生成されるメッセージの選択肢​のリスト (長さは常に 1)	応答の例​を参照
usage​	オブジェクト​	トークンの使用量​の統計	{"prompt_tokens":15,"completion_tokens":13,"total_tokens":28}​

選択オブジェクト

choices​ 文字列 (長さは 1) 内のオブジェクトの構造は次のとおりです。

フィールド	型	説明	例
index​	整数​	選択のインデックス 常に0​	0​
message​	オブジェクト​	生成されるメッセージ​の内容	応答の例​を参照
finish_reason​	列挙<文字列>	モデルが停止した理由 次のいずれか: "stop"​、"length"​、"tool_calls"​	"stop"​

メッセージオブジェクト

フィールド	型	説明	例
role​	列挙<文字列>	メッセージ送信者のロール 次のいずれか: assistant​、tool​	assistant​
content​	文字列​、オブジェクト​、オブジェクトの配列​	メッセージのテキスト内容	"hello! how can I help you today?"​
reasoning​	オブジェクト​	extended_thinking.include_reasoning​ が true の場合に内部推論​トレースが生成されます
refusal​	文字列​	(現在は常に null) モデルが回答を拒否した場合の拒否メッセージ	null​
tool_calls​	オブジェクトの配列​	(オプション) モデルによって生成されるツール呼び出し要求	応答の例​を参照

コンテンツオブジェクト

メッセージの内容は、コンテンツオブジェクトの形式になる場合があります。

フィールド	型	説明	例
type​	列挙<文字列>	メッセージ内容の種別/分類 次のいずれか: text​、image_url​	text​
content​	文字列または配列​	メッセージの内容	"hello! how can I help you today?" [{"type":"text", "text":"tell me about this image"}, {"type":"image_url", "image_url":"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"}]​

理由オブジェクト

extended_thinking.include_reasoning​ が true に設定されている場合、モデルは message​ 内部の reasoning​ オブジェクトを返します。

フィールド	型	説明	例
thinking​	文字列​	モデルの応答を形成するために使用する内部思考連鎖推論 (claude-4-sonnet​ 向けに要約)	"The user is asking about the weather. I should call the get_weather function with Portland, Oregon."​
signature​	文字列​	推論内容を検証する暗号化署名	"ErcBCkgIAxABGAIi..."​
redacted_thinking​	文字列​	(任意、通常は応答では省略) 安全またはプライバシーのために一部が削除された場合の、編集されたバージョンの thinking​ (claude-3-7-sonnet​ にのみ関連)	null​

使用量オブジェクト

トークンの消費に関する情報。

フィールド	型	説明	例
prompt_tokens​	整数​	入力プロンプトで使用するトークンの数	407​
completion_tokens​	整数​	応答で生成されるトークンの数	107​
total_tokens​	整数​	使用するトークンの合計数 (プロンプト + 補完)	514​

リクエストの例

/v1/chat/completions​ curl リクエストの例を見てみましょう。

まず、このコマンドを使用して、Heroku 環境変数をローカル変数として設定します。 bash eval $(heroku config -a $APP_NAME --shell | grep '^INFERENCE_' | sed 's/^/export /' | tee >(cat >&2)) 次に、curl​ リクエストを送信します。

curl $INFERENCE_URL/v1/chat/completions \
 -H "Authorization: Bearer $INFERENCE_KEY" \
 -d @- <<EOF | jq
{
  "model": "$INFERENCE_MODEL_ID",
  "messages": [{"role": "user", "content": "Hello"}]
}
EOF

応答の例

{
  "id": "chatcmpl-1839afa8133ceda215788",
  "object": "chat.completion",
  "created": 1745619466,
  "model": "claude-4-sonnet",
  "system_fingerprint": "heroku-inf-1y38gdr",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hi! How can I help you today?",
        "refusal": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 12,
    "total_tokens": 20
  }
}

ツールを使用したリクエストの例

 curl $INFERENCE_URL/v1/chat/completions \
 -H "Authorization: Bearer $INFERENCE_KEY" \
 -d @- <<EOF | jq
 {
    "model": "$INFERENCE_MODEL_ID",
    "messages": [
        {
            "role": "user",
            "content": "What's the weather like in Portland?"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. Portland, OR"
                        }
                    },
                    "required": [
                        "location"
                    ]
                }
            }
        }
    ]
}
EOF

ツールを使用した応答の例

{
  "id": "chatcmpl-1839adcc2079997417288",
  "object": "chat.completion",
  "created": 1745617422,
  "model": "claude-4-sonnet",
  "system_fingerprint": "heroku-inf-1y38gdr",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I'll help you check the current weather in Portland. Since Portland could refer to either Portland, Oregon or Portland, Maine, I should specify the state.\nI'll check Portland, OR as it's the larger and more commonly referenced Portland.",
        "refusal": null,
        "tool_calls": [
          {
            "id": "tooluse_aFByQsacQ_2BmYMGHvkBmg",
            "type": "function",
            "function": {
              "name": "get_current_weather",
              "arguments": "{\"location\":\"Portland, OR\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 407,
    "completion_tokens": 107,
    "total_tokens": 514
  }
}