共通 Chat Completions | API ドキュメント

# Common Chat Completions

Unified chat API for switching text models through the `model` parameter. The request format is compatible with OpenAI Chat Completions.

POST https://api.apihop.ai/v1/chat-completions

Unified chat API for switching text models through the `model` parameter. The request format is compatible with OpenAI Chat Completions.

Claude Sonnet 4.6 (`claude-sonnet-4-6`) is supported by the upstream supplier but is not currently published on RequestBeam. It is not an active integration default. Before calling any model, confirm access with your own `GET https://api.apihop.ai/v1/models` response.

This endpoint returns one complete JSON response by default. Set `stream: true` explicitly when you need SSE streaming.

```text
POST https://api.apihop.ai/v1/chat-completions
```

## Authentication

All requests require Bearer Token authentication.

```http
Authorization: Bearer YOUR_API_KEY
```

If authentication fails, check:

- Whether the API Key is correct
- Whether the key is valid for this API Base URL
- Whether the request header is spelled correctly
- Whether a proxy rewrites the authorization header

## Body

### `model` (string, required, Default: gpt-5.4)

Documented text model IDs (confirm access with `GET https://api.apihop.ai/v1/models`):

- OpenAI: `gpt-5.4`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-6-astra`
- Anthropic: `claude-fable-5`, `claude-fable-5-1`, `claude-opus-4-6`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-5`, `claude-sonnet-5-5`
- DeepSeek: `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-v4.1-flash`

(V4.1 Flash is a distinct model ID, available only after deployment and enablement; check `GET https://api.apihop.ai/v1/models`).

- Gemini: `gemini-3.6-flash`, `gemini-3.7-flash`, `gemini-3.8-flash`, `gemini-3.5-flash-lite`, `gemini-4-argon` (after deployment and enablement)
- Kimi: `kimi-k3`
- MiniMax: `minimax-m3`

See the [Model Catalog](https://apihop.ai/en/docs/api-reference/models) for the complete list and the models visible to the current API Key. Use your own `GET https://api.apihop.ai/v1/models` response as the current source of availability. See the [DeepSeek](https://apihop.ai/en/docs/api-reference/DeepSeek/models), [Gemini](https://apihop.ai/en/docs/api-reference/Gemini/models), [Kimi](https://apihop.ai/en/docs/api-reference/Kimi/models), and [MiniMax](https://apihop.ai/en/docs/api-reference/MiniMax/models) guides for family-specific selection notes and examples.

### `messages` (object[], required)

Chat messages. Each message should include:

- `role`: `system`, `user`, or `assistant`
- `content`: message content

Example:

```json
  [
    {"role": "system", "content": "You are a helpful Python tutor."},
    {"role": "user", "content": "How should I learn programming?"}
  ]
```

**Model-specific sampling limits:** `gpt-6-astra` does not accept legacy `temperature`, `top_p`, or `top_logprobs`; omit those fields even when an older client includes them. RequestBeam's GPT-6 Astra Playground also hides the legacy sampling and penalty controls. `claude-sonnet-5` rejected `top_p` in a documented integration recheck, so omit it for that model as well. Passing an optional field through a proxy does not establish that the selected upstream model supports it.

### `temperature` (number, Default: 1.0)

Sampling temperature. OpenAI-compatible clients commonly use `0` through `2`, but the selected model makes the final validation decision.

### `max_tokens` (integer)

Optional maximum output tokens, as a positive integer. Omit this field to use the upstream default for the selected model; defaults and maximum limits vary by model and upstream configuration.

Depending on the model, the budget may include reasoning tokens as well as final text. A small budget can cause `finish_reason: "length"`, truncate the answer, or be exhausted before final text. Increasing it may increase cost.

### `max_completion_tokens` (integer)

Optional compatibility alternative to `max_tokens`, with the same budget considerations. A model may accept only one of these fields, so start with a minimal body when switching models. Omit both to use the upstream default.

### `stream` (boolean, Default: false)

Whether to stream the response.

- `true`: return Server-Sent Events
- `false`: return one complete response

### `top_p` (number, Default: 1.0)

Nucleus sampling parameter. OpenAI-compatible clients commonly use `0` through `1`; the selected model performs final validation.

### `frequency_penalty` (number, Default: 0)

Frequency penalty. OpenAI-compatible clients commonly use `-2.0` through `2.0`; the selected model performs final validation.

### `presence_penalty` (number, Default: 0)

Presence penalty. OpenAI-compatible clients commonly use `-2.0` through `2.0`; the selected model performs final validation.

### `stop` (string | array)

A stop sequence or array of stop sequences. The selected model determines the accepted count and behavior.

### `n` (integer, Default: 1)

Number of responses to generate. Use a number such as `1`, not a quoted string.

## Model Parameter Differences

Current text models support minimal streaming and non-streaming Chat requests, but optional parameter acceptance and effects vary by the selected model and its compatibility implementation.

The latest recheck on 2026-09-26 accepted `claude-fable-5` with `temperature: 0` and returned text. The same recheck rejected `claude-sonnet-5` with `top_p: 0.9` with HTTP `400` and `top_p is deprecated`. Omit `top_p` for that model. Acceptance establishes neither an effect on sampling nor a guarantee for other models or later requests; do not assume that all sampling parameters are supported.

The OpenAI checks on 2026-09-26 accepted `stop` for `gpt-5.6-sol` and `gpt-5.6-terra`. Parameter acceptance can change with the upstream and does not prove that a stop sequence is effective.

Native OpenAI-compatible Chat forwarding preserves `top_p` and `stop` in the upstream request. A route that converts Chat to Responses preserves `top_p` but does not forward `stop`. Forwarding a field does not establish upstream support or its effect; neither field has a platform-wide guarantee across routes.

Start with a minimal request when switching models, then verify sampling, stop sequences, and advanced tool parameters separately. For stop sequences, inspect the actual text and stop reason, not only the HTTP status. HTTP 200 does not establish a sampling effect. Output budgets must cover both the model's thinking and its final text.

## Request Example

```json
{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Hello, introduce yourself briefly."
    }
  ],
  "stream": false
}
```

## Response

### `id` (string)

Unique response identifier.

### `object` (string)

Object type, usually `chat.completion` or `chat.completion.chunk` for streaming.

### `created` (integer)

Unix creation timestamp.

### `model` (string)

Model identifier returned in the response.

### `choices` (array)

Generated choices, including message content, index, and finish reason.

### `usage` (object)

Token usage statistics.

### Success Example

```json
{
  "id": "chatcmpl-9876543210",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am an AI assistant that can help with writing, coding, and analysis."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 42,
    "total_tokens": 70
  }
}
```

## Error Response

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for the full code reference, protocol differences, and diagnostic steps.

Chat Completions HTTP errors use a flat JSON body, including upstream HTTP errors returned before an SSE stream starts. For example, HTTP `402` returns:

```json
{
  "code": 40000,
  "message": "Insufficient credit. Required: 30000, Available: 20000",
  "type": "api_error"
}
```

- `code`: numeric platform error code, separate from the HTTP status and not a string
- `message`: human-readable error description
- `type`: `api_error`
- `requestId`: optional request identifier for troubleshooting

| HTTP status | `code` | Meaning |
| --- | --- | --- |
| 400 | 10000 | Invalid request |
| 401 | 20000 | Missing or invalid authentication |
| 402 | 40000 | Insufficient credit |
| 403 | 20001 | Access denied or model unavailable to this key |
| 404 | 30000 | Model or resource not found |
| 409 | 30001 | Request conflict |
| 422 | 10001 | Validation error |
| 429 | 40001 | Rate limit exceeded |
| 500 | 50003 | Internal error |
| 502 | 50000 | Upstream provider error |
| 503 | 50001 | Service unavailable |
| 504 | 50002 | Gateway timeout |

Check the HTTP status first to determine whether the request succeeded, then compare the numeric `code` for application-specific handling. Do not compare `code` with strings such as `"400"`, assume it equals the HTTP status, or parse `message` as a stable error identifier. Missing or incorrectly typed `messages` are rejected with HTTP `400` and `code: 10000` before provider invocation.

This error format applies to Chat Completions HTTP responses, not errors within an already-started SSE stream or other API protocols. Model Catalog and native protocol endpoints have their own documented error formats.

model パラメータでテキストモデルを切り替えられる統一チャット API です。リクエスト形式は OpenAI Chat Completions と互換性があります。

Claude Sonnet 4.6（claude-sonnet-4-6）は上流の供給元では対応していますが、現在 RequestBeam では公開されていません。現時点の連携における既定モデルではありません。モデルを呼び出す前に、自分の API キーによる GET https://api.apihop.ai/v1/models のレスポンスでアクセス権を確認してください。

このエンドポイントは、既定では 1 つの完全な JSON レスポンスを返します。SSE ストリーミングが必要な場合は、stream: true を明示的に設定してください。

text

POST https://api.apihop.ai/v1/chat-completions

認証

すべてのリクエストに Bearer Token 認証が必要です。

http

Authorization: Bearer YOUR_API_KEY

認証に失敗した場合は、次の点を確認してください。

API キーが正しいか
その API Base URL に対してキーが有効か
リクエストヘッダーの綴りが正しいか
プロキシが認証ヘッダーを書き換えていないか

リクエストボディ

modelstring必須既定値: gpt-5.4

ドキュメントに掲載されているテキストモデル ID です（アクセス権は GET https://api.apihop.ai/v1/models で確認してください）。

OpenAI：gpt-5.4、gpt-5.5、gpt-5.6-sol、gpt-5.6-terra、gpt-6-astra
Anthropic：claude-fable-5、claude-fable-5-1、claude-opus-4-6、claude-opus-4-7、claude-opus-4-8、claude-opus-5、claude-opus-5-5、claude-sonnet-5、claude-sonnet-5-5
DeepSeek：deepseek-v4-flash、deepseek-v4-pro、deepseek-v4.1-flash

（V4.1 Flash は別個のモデル ID であり、デプロイと有効化の後にのみ利用できます。GET https://api.apihop.ai/v1/models を確認してください）。

Gemini：gemini-3.6-flash、gemini-3.7-flash、gemini-3.8-flash、gemini-3.5-flash-lite、gemini-4-argon（デプロイと有効化の後）
Kimi：kimi-k3
MiniMax：minimax-m3

完全な一覧と、現在の API キーから見えるモデルについては、モデルカタログを参照してください。最新の利用可否は、自分の API キーによる GET https://api.apihop.ai/v1/models のレスポンスを基準にしてください。ファミリー別のモデル選択に関する注意点や使用例については、DeepSeek、Gemini、Kimi、MiniMax のガイドを参照してください。

messagesobject[]必須

チャットメッセージです。各メッセージには次の項目を含めてください。

role：system、user、assistant のいずれか
content：メッセージの内容

例：

json

  [
    {"role": "system", "content": "You are a helpful Python tutor."},
    {"role": "user", "content": "How should I learn programming?"}
  ]

モデル固有のサンプリング制限： gpt-6-astra は従来の temperature、top_p、top_logprobs を受け付けません。古いクライアントが含める場合でも、これらのフィールドを省略してください。RequestBeam の GPT-6 Astra Playground でも、従来のサンプリングとペナルティの設定は非表示になります。記録された連携の再確認では、claude-sonnet-5 も top_p を拒否したため、このモデルでも省略してください。任意フィールドがプロキシを通過したことは、選択した上流モデルがそのフィールドに対応する証明にはなりません。

temperaturenumber既定値: 1.0

サンプリング温度です。OpenAI 互換クライアントでは通常 0 から 2 を使用しますが、最終的な検証は選択したモデルが行います。

max_tokensinteger

任意の最大出力トークン数で、正の整数を指定します。省略すると、選択したモデルの上流側の既定値を使用します。既定値と上限はモデルや上流の設定によって異なります。

モデルによっては、予算に最終テキストだけでなく推論トークンも含まれます。予算が小さいと、finish_reason: "length" が返される、回答が途中で切れる、最終テキストの生成前に予算を使い切る、といった結果になる可能性があります。予算を増やすと費用が増える場合があります。

max_completion_tokensinteger

互換性のために用意された、任意の max_tokens の代替フィールドです。予算に関する注意事項は同じです。モデルによっては片方のフィールドしか受け付けないため、モデルを切り替えるときは最小限のボディから始めてください。両方を省略すると上流側の既定値を使用します。

streamboolean既定値: false

レスポンスをストリーミングするかどうかを指定します。

true：Server-Sent Events を返す
false：1 つの完全なレスポンスを返す

top_pnumber既定値: 1.0

ニュークリアスサンプリングのパラメータです。OpenAI 互換クライアントでは通常 0 から 1 を使用します。最終的な検証は選択したモデルが行います。

frequency_penaltynumber既定値: 0

頻度ペナルティです。OpenAI 互換クライアントでは通常 -2.0 から 2.0 を使用します。最終的な検証は選択したモデルが行います。

presence_penaltynumber既定値: 0

存在ペナルティです。OpenAI 互換クライアントでは通常 -2.0 から 2.0 を使用します。最終的な検証は選択したモデルが行います。

stopstring | array

停止シーケンス、または停止シーケンスの配列です。受け付ける個数と動作は、選択したモデルによって決まります。

ninteger既定値: 1

生成するレスポンスの数です。引用符付きの文字列ではなく、1 のような数値を使用してください。

モデルによるパラメータの違い

現在のテキストモデルは、最小限のストリーミング・非ストリーミングのチャットリクエストに対応しています。ただし、任意パラメータを受け付けるか、どのような効果があるかは、選択したモデルとその互換性実装によって異なります。

2026-09-26 の直近の再確認では、claude-fable-5 が temperature: 0 を受け付け、テキストを返しました。同じ再確認で、claude-sonnet-5 は top_p: 0.9 を HTTP 400 と top_p is deprecated で拒否しました。このモデルでは top_p を省略してください。受け付けられたことは、サンプリングへの効果も、他のモデルや後のリクエストでの動作も保証しません。すべてのサンプリングパラメータに対応していると想定しないでください。

2026-09-26 の OpenAI の確認では、gpt-5.6-sol と gpt-5.6-terra が stop を受け付けました。パラメータを受け付けるかどうかは上流の変更で変わる場合があり、停止シーケンスが有効に働くことの証明にはなりません。

ネイティブな OpenAI 互換 Chat の転送では、上流リクエストの top_p と stop を保持します。Chat を Responses に変換するルートでは top_p を保持しますが、stop は転送しません。フィールドを転送することは、上流での対応や効果の証明にはなりません。どちらのフィールドも、すべてのルートにわたるプラットフォーム全体の保証はありません。

モデルを切り替えるときは最小限のリクエストから始め、サンプリング、停止シーケンス、高度なツールのパラメータを個別に確認してください。停止シーケンスについては、HTTP ステータスだけでなく実際のテキストと停止理由を確認してください。HTTP 200 はサンプリングへの効果を証明しません。出力予算には、モデルの思考と最終テキストの両方を収める必要があります。

リクエスト例

json

{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Hello, introduce yourself briefly."
    }
  ],
  "stream": false
}

レスポンス

idstring

レスポンスの一意な識別子です。

objectstring

オブジェクトの種類です。通常は chat.completion、ストリーミングでは chat.completion.chunk です。

createdinteger

作成時刻を表す Unix タイムスタンプです。

modelstring

レスポンスに含まれるモデル識別子です。

choicesarray

生成された選択肢です。メッセージの内容、インデックス、終了理由を含みます。

usageobject

トークン使用量の統計です。

成功時の例

json

{
  "id": "chatcmpl-9876543210",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am an AI assistant that can help with writing, coding, and analysis."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 42,
    "total_tokens": 70
  }
}

エラーレスポンス

コードの一覧、プロトコルごとの違い、診断手順については、エラーコードとトラブルシューティングを参照してください。

Chat Completions の HTTP エラーは、SSE ストリーム開始前に返された上流の HTTP エラーも含め、フラットな JSON ボディを使用します。たとえば HTTP 402 では次のように返されます。

json

{
  "code": 40000,
  "message": "Insufficient credit. Required: 30000, Available: 20000",
  "type": "api_error"
}

code：プラットフォームの数値エラーコードです。HTTP ステータスとは別で、文字列ではありません
message：人が読めるエラーの説明です
type：api_error
requestId：トラブルシューティング用の任意のリクエスト識別子です

HTTP ステータス	`code`	意味
400	10000	無効なリクエスト
401	20000	認証情報がないか無効
402	40000	残高不足
403	20001	アクセス拒否、またはこのキーではモデルを利用不可
404	30000	モデルまたはリソースが見つからない
409	30001	リクエストの競合
422	10001	検証エラー
429	40001	レート制限を超過
500	50003	内部エラー
502	50000	上流プロバイダーのエラー
503	50001	サービスを利用不可
504	50002	ゲートウェイのタイムアウト

まず HTTP ステータスでリクエストが成功したかを確認し、その後で数値の code を比較してアプリケーション固有の処理を行ってください。code を "400" のような文字列と比較したり、HTTP ステータスと同じだと想定したり、message を安定したエラー識別子として解析したりしないでください。messages がない場合や型が誤っている場合は、プロバイダーを呼び出す前に HTTP 400 と code: 10000 で拒否されます。

このエラー形式は Chat Completions の HTTP レスポンスに適用されます。すでに開始した SSE ストリーム内のエラーや、他の API プロトコルには適用されません。モデルカタログとネイティブプロトコルのエンドポイントには、それぞれドキュメントに記載された固有のエラー形式があります。