Chat Completions Umum | Dokumentasi 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 API Hop. 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. API Hop'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.

API chat terpadu untuk beralih model teks melalui parameter model. Format permintaannya kompatibel dengan OpenAI Chat Completions.

Claude Sonnet 4.6 (claude-sonnet-4-6) didukung penyedia hulu tetapi saat ini tidak dipublikasikan di API Hop. Model ini bukan pilihan integrasi bawaan yang aktif. Sebelum memanggil model apa pun, pastikan akses melalui respons GET https://api.apihop.ai/v1/models Anda sendiri.

Secara bawaan, endpoint ini mengembalikan satu respons JSON lengkap. Tetapkan stream: true secara eksplisit jika memerlukan streaming SSE.

text

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

Autentikasi

Semua permintaan memerlukan autentikasi Bearer Token.

http

Authorization: Bearer YOUR_API_KEY

Jika autentikasi gagal, periksa:

Apakah API Key benar
Apakah kunci berlaku untuk URL Dasar API ini
Apakah ejaan header permintaan benar
Apakah proksi menulis ulang header otorisasi

Isi

modelstringwajibBawaan: gpt-5.4

ID model teks yang didokumentasikan (konfirmasi akses dengan 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 adalah ID model tersendiri, hanya tersedia setelah diterapkan dan diaktifkan; periksa 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 (setelah diterapkan dan diaktifkan)
Kimi: kimi-k3
MiniMax: minimax-m3

Lihat Katalog Model untuk daftar lengkap dan model yang terlihat oleh API Key saat ini. Gunakan respons GET https://api.apihop.ai/v1/models Anda sendiri sebagai sumber ketersediaan terkini. Lihat panduan DeepSeek, Gemini, Kimi, dan MiniMax untuk catatan pemilihan dan contoh khusus tiap keluarga.

messagesobject[]wajib

Pesan chat. Setiap pesan harus mencakup:

role: system, user, atau assistant
content: isi pesan

Contoh:

json

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

Batas sampling khusus model: gpt-6-astra tidak menerima temperature, top_p, atau top_logprobs lama; hilangkan kolom tersebut meskipun klien lama menyertakannya. Playground GPT-6 Astra API Hop juga menyembunyikan kontrol sampling dan penalti lama. claude-sonnet-5 menolak top_p dalam pemeriksaan ulang integrasi yang didokumentasikan, jadi hilangkan juga untuk model tersebut. Meneruskan kolom opsional melalui proksi tidak membuktikan bahwa model upstream yang dipilih mendukungnya.

temperaturenumberBawaan: 1.0

Temperatur sampling. Klien kompatibel OpenAI biasanya menggunakan 0 hingga 2, tetapi model yang dipilih menentukan keputusan validasi akhir.

max_tokensinteger

Maksimum token keluaran opsional, berupa bilangan bulat positif. Hilangkan kolom ini untuk menggunakan nilai bawaan upstream bagi model yang dipilih; nilai bawaan dan batas maksimum berbeda menurut model dan konfigurasi upstream.

Bergantung pada model, anggaran dapat mencakup token penalaran serta teks akhir. Anggaran kecil dapat menyebabkan finish_reason: "length", memotong jawaban, atau habis sebelum teks akhir. Menaikkannya dapat meningkatkan biaya.

max_completion_tokensinteger

Alternatif kompatibilitas opsional untuk max_tokens, dengan pertimbangan anggaran yang sama. Model mungkin hanya menerima salah satu kolom ini, jadi mulai dengan isi minimal saat beralih model. Hilangkan keduanya untuk menggunakan nilai bawaan upstream.

streambooleanBawaan: false

Apakah respons dikirim secara streaming.

true: kembalikan Server-Sent Events
false: kembalikan satu respons lengkap

top_pnumberBawaan: 1.0

Parameter nucleus sampling. Klien kompatibel OpenAI biasanya menggunakan 0 hingga 1; model yang dipilih melakukan validasi akhir.

frequency_penaltynumberBawaan: 0

Penalti frekuensi. Klien kompatibel OpenAI biasanya menggunakan -2.0 hingga 2.0; model yang dipilih melakukan validasi akhir.

presence_penaltynumberBawaan: 0

Penalti kehadiran. Klien kompatibel OpenAI biasanya menggunakan -2.0 hingga 2.0; model yang dipilih melakukan validasi akhir.

stopstring | array

Urutan penghenti atau larik urutan penghenti. Model yang dipilih menentukan jumlah dan perilaku yang diterima.

nintegerBawaan: 1

Jumlah respons yang akan dibuat. Gunakan angka seperti 1, bukan string dalam tanda kutip.

Perbedaan Parameter Model

Model teks saat ini mendukung permintaan Chat minimal dengan dan tanpa streaming, tetapi penerimaan dan efek parameter opsional berbeda menurut model yang dipilih dan implementasi kompatibilitasnya.

Pemeriksaan ulang terbaru pada 2026-09-26 menerima claude-fable-5 dengan temperature: 0 dan mengembalikan teks. Pemeriksaan ulang yang sama menolak claude-sonnet-5 dengan top_p: 0.9, dengan HTTP 400 dan top_p is deprecated. Hilangkan top_p untuk model tersebut. Penerimaan tidak membuktikan efek pada sampling maupun menjamin model lain atau permintaan berikutnya; jangan berasumsi semua parameter sampling didukung.

Pemeriksaan OpenAI pada 2026-09-26 menerima stop untuk gpt-5.6-sol dan gpt-5.6-terra. Penerimaan parameter dapat berubah mengikuti upstream dan tidak membuktikan bahwa urutan penghenti efektif.

Penerusan Chat native yang kompatibel OpenAI mempertahankan top_p dan stop dalam permintaan upstream. Rute yang mengonversi Chat ke Responses mempertahankan top_p tetapi tidak meneruskan stop. Penerusan kolom tidak membuktikan dukungan atau efeknya di upstream; tidak ada jaminan di seluruh platform untuk kedua kolom tersebut lintas rute.

Mulai dengan permintaan minimal saat beralih model, lalu verifikasi sampling, urutan penghenti, dan parameter alat lanjutan secara terpisah. Untuk urutan penghenti, periksa teks dan alasan penghentian yang sebenarnya, bukan hanya status HTTP. HTTP 200 tidak membuktikan efek sampling. Anggaran keluaran harus mencakup pemikiran model serta teks akhirnya.

Contoh Permintaan

json

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

Respons

idstring

Pengenal respons unik.

objectstring

Tipe objek, biasanya chat.completion atau chat.completion.chunk untuk streaming.

createdinteger

Stempel waktu pembuatan Unix.

modelstring

Pengenal model yang dikembalikan dalam respons.

choicesarray

Pilihan yang dihasilkan, termasuk isi pesan, indeks, dan alasan penyelesaian.

usageobject

Statistik penggunaan token.

Contoh Berhasil

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

Respons Kesalahan

Lihat Kode Kesalahan dan Pemecahan Masalah untuk referensi kode lengkap, perbedaan protokol, dan langkah diagnosis.

Kesalahan HTTP Chat Completions menggunakan isi JSON datar, termasuk kesalahan HTTP upstream yang dikembalikan sebelum stream SSE dimulai. Contohnya, HTTP 402 mengembalikan:

json

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

code: kode kesalahan numerik platform, terpisah dari status HTTP dan bukan string
message: deskripsi kesalahan yang dapat dibaca manusia
type: api_error
requestId: pengenal permintaan opsional untuk pemecahan masalah

Status HTTP	`code`	Makna
400	10000	Permintaan tidak valid
401	20000	Autentikasi tidak ada atau tidak valid
402	40000	Kredit tidak cukup
403	20001	Akses ditolak atau model tidak tersedia untuk kunci ini
404	30000	Model atau sumber daya tidak ditemukan
409	30001	Konflik permintaan
422	10001	Kesalahan validasi
429	40001	Batas laju terlampaui
500	50003	Kesalahan internal
502	50000	Kesalahan penyedia upstream
503	50001	Layanan tidak tersedia
504	50002	Gateway melewati batas waktu

Periksa status HTTP terlebih dahulu untuk menentukan apakah permintaan berhasil, lalu bandingkan code numerik untuk penanganan khusus aplikasi. Jangan membandingkan code dengan string seperti "400", menganggapnya sama dengan status HTTP, atau menguraikan message sebagai pengenal kesalahan yang stabil. messages yang tidak ada atau bertipe salah ditolak dengan HTTP 400 dan code: 10000 sebelum pemanggilan penyedia.

Format kesalahan ini berlaku untuk respons HTTP Chat Completions, bukan kesalahan dalam stream SSE yang sudah dimulai atau protokol API lainnya. Katalog Model dan endpoint protokol native memiliki format kesalahan terdokumentasi masing-masing.