Ortak sohbet tamamlamaları | API Belgeleri

# 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 parametresiyle metin modelleri arasında geçiş sağlayan birleşik sohbet API’si. İstek biçimi OpenAI Chat Completions ile uyumludur.

Claude Sonnet 4.6 (claude-sonnet-4-6) üst sağlayıcı tarafından desteklenir ancak şu anda RequestBeam’de yayımlanmamıştır. Etkin bir entegrasyon varsayılanı değildir. Herhangi bir modeli çağırmadan önce kendi GET https://api.apihop.ai/v1/models yanıtınızla erişimi doğrulayın.

Bu uç nokta varsayılan olarak tek bir tam JSON yanıtı döndürür. SSE akışı gerektiğinde stream: true değerini açıkça ayarlayın.

text

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

Kimlik doğrulama

Tüm istekler Bearer belirteciyle kimlik doğrulama gerektirir.

http

Authorization: Bearer YOUR_API_KEY

Kimlik doğrulama başarısızsa şunları kontrol edin:

API anahtarının doğru olup olmadığı
Anahtarın bu API temel URL’si için geçerli olup olmadığı
İstek başlığının doğru yazılıp yazılmadığı
Bir proxy’nin yetkilendirme başlığını yeniden yazıp yazmadığı

İstek gövdesi

modelstringzorunluVarsayılan: gpt-5.4

Belgelenen metin modeli kimlikleri (erişimi GET https://api.apihop.ai/v1/models ile doğrulayın):

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 ayrı bir model kimliğidir ve yalnızca dağıtım ve etkinleştirme sonrası kullanılabilir; kontrol edin: 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 (dağıtım ve etkinleştirme sonrası)
Kimi: kimi-k3
MiniMax: minimax-m3

Tam liste ve geçerli API anahtarının görebildiği modeller için Model kataloğuna bakın. Güncel kullanılabilirlik kaynağı olarak kendi GET https://api.apihop.ai/v1/models yanıtınızı kullanın. Aileye özgü seçim notları ve örnekler için DeepSeek, Gemini, Kimi ve MiniMax kılavuzlarına bakın.

messagesobject[]zorunlu

Sohbet mesajları. Her mesaj şunları içermelidir:

role: system, user veya assistant
content: mesaj içeriği

Örnek:

json

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

Modele özgü örnekleme sınırları: gpt-6-astra, eski temperature, top_p veya top_logprobs alanlarını kabul etmez; eski bir istemci eklese bile bunları atlayın. RequestBeam GPT-6 Astra Playground eski örnekleme ve ceza kontrollerini de gizler. claude-sonnet-5, belgelenmiş entegrasyon tekrar kontrolünde top_p alanını reddetmiştir; bu modelde de atlayın. İsteğe bağlı alanın proxy’den geçirilmesi, seçilen üst modelin alanı desteklediğini kanıtlamaz.

temperaturenumberVarsayılan: 1.0

Örnekleme sıcaklığı. OpenAI uyumlu istemciler genellikle 0 ile 2 kullanır, ancak son doğrulama kararını seçilen model verir.

max_tokensinteger

Pozitif tam sayı olarak isteğe bağlı azami çıktı tokenı. Seçilen modelin üst sağlayıcı varsayılanını kullanmak için alanı atlayın; varsayılanlar ve üst sınırlar modele ve sağlayıcı yapılandırmasına göre değişir.

Modele bağlı olarak bütçe hem akıl yürütme tokenlarını hem nihai metni kapsayabilir. Küçük bütçe finish_reason: "length" oluşturabilir, yanıtı kesebilir veya nihai metinden önce tükenebilir. Artırmak maliyeti artırabilir.

max_completion_tokensinteger

max_tokens için aynı bütçe hususlarına sahip isteğe bağlı uyumluluk alternatifi. Model bu alanlardan yalnızca birini kabul edebilir; model değiştirirken asgari gövdeyle başlayın. Üst sağlayıcı varsayılanı için ikisini de atlayın.

streambooleanVarsayılan: false

Yanıtın akış halinde döndürülüp döndürülmeyeceği.

true: Server-Sent Events döndürür
false: tek bir tam yanıt döndürür

top_pnumberVarsayılan: 1.0

Çekirdek örnekleme parametresi. OpenAI uyumlu istemciler genellikle 0 ile 1 kullanır; son doğrulamayı seçilen model yapar.

frequency_penaltynumberVarsayılan: 0

Sıklık cezası. OpenAI uyumlu istemciler genellikle -2.0 ile 2.0 kullanır; son doğrulamayı seçilen model yapar.

presence_penaltynumberVarsayılan: 0

Varlık cezası. OpenAI uyumlu istemciler genellikle -2.0 ile 2.0 kullanır; son doğrulamayı seçilen model yapar.

stopstring | array

Bir durdurma dizisi veya durdurma dizileri dizisi. Kabul edilen sayıyı ve davranışı seçilen model belirler.

nintegerVarsayılan: 1

Üretilecek yanıt sayısı. Tırnaklı dize yerine 1 gibi sayı kullanın.

Model parametresi farkları

Mevcut metin modelleri asgari akışlı ve akışsız Chat isteklerini destekler; ancak isteğe bağlı parametrelerin kabulü ve etkileri seçilen modele ve uyumluluk uygulamasına göre değişir.

2026-09-26 tarihli son tekrar kontrolü, claude-fable-5 için temperature: 0 değerini kabul edip metin döndürdü. Aynı kontrol, claude-sonnet-5 için top_p: 0.9 değerini HTTP 400 ve top_p is deprecated ile reddetti. Bu modelde top_p atlayın. Kabul, örnekleme etkisini kanıtlamaz ve diğer modelleri ya da sonraki istekleri garanti etmez; tüm örnekleme parametrelerinin desteklendiğini varsaymayın.

2026-09-26 tarihli OpenAI kontrolleri, gpt-5.6-sol ve gpt-5.6-terra için stop kabul etti. Parametre kabulü üst sağlayıcıya göre değişebilir ve durdurma dizisinin etkili olduğunu kanıtlamaz.

Yerel OpenAI uyumlu Chat iletimi, üst sağlayıcı isteğinde top_p ve stop alanlarını korur. Chat’i Responses’a dönüştüren rota top_p değerini korur ancak stop iletmez. Bir alanı iletmek üst sağlayıcı desteğini veya etkisini kanıtlamaz; iki alanın da tüm rotalarda platform çapında garantisi yoktur.

Model değiştirirken asgari istekle başlayın; ardından örneklemeyi, durdurma dizilerini ve gelişmiş araç parametrelerini ayrı ayrı doğrulayın. Durdurma dizilerinde yalnızca HTTP durumunu değil, gerçek metni ve durma nedenini inceleyin. HTTP 200 örnekleme etkisini kanıtlamaz. Çıktı bütçeleri hem modelin düşünmesini hem nihai metni kapsamalıdır.

İstek örneği

json

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

Yanıt

idstring

Benzersiz yanıt kimliği.

objectstring

Nesne türü; genellikle chat.completion, akışta chat.completion.chunk.

createdinteger

Unix oluşturulma zaman damgası.

modelstring

Yanıtta döndürülen model kimliği.

choicesarray

Mesaj içeriği, indeks ve bitiş nedeni dahil üretilen seçenekler.

usageobject

Token kullanım istatistikleri.

Başarılı yanıt örneği

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

Hata yanıtı

Tam kod başvurusu, protokol farkları ve tanılama adımları için Hata kodları ve sorun giderme sayfasına bakın.

Chat Completions HTTP hataları, SSE akışı başlamadan döndürülen üst sağlayıcı HTTP hataları dahil düz JSON gövdesi kullanır. Örneğin HTTP 402 şunu döndürür:

json

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

code: HTTP durumundan ayrı, dize olmayan sayısal platform hata kodu
message: insan tarafından okunabilir hata açıklaması
type: api_error
requestId: sorun giderme için isteğe bağlı istek kimliği

HTTP durumu	`code`	Anlamı
400	10000	Geçersiz istek
401	20000	Eksik veya geçersiz kimlik doğrulama
402	40000	Yetersiz bakiye
403	20001	Erişim reddedildi veya model bu anahtara açık değil
404	30000	Model veya kaynak bulunamadı
409	30001	İstek çakışması
422	10001	Doğrulama hatası
429	40001	Hız sınırı aşıldı
500	50003	İç hata
502	50000	Üst sağlayıcı hatası
503	50001	Hizmet kullanılamıyor
504	50002	Ağ geçidi zaman aşımı

İsteğin başarılı olup olmadığını belirlemek için önce HTTP durumunu kontrol edin; sonra uygulamaya özgü işlem için sayısal code değerini karşılaştırın. code değerini "400" gibi dizelerle karşılaştırmayın, HTTP durumuna eşit olduğunu varsaymayın veya message alanını kararlı hata kimliği olarak ayrıştırmayın. Eksik ya da yanlış türde messages, sağlayıcı çağrılmadan önce HTTP 400 ve code: 10000 ile reddedilir.

Bu hata biçimi Chat Completions HTTP yanıtları içindir; başlamış SSE akışındaki hatalara veya diğer API protokollerine uygulanmaz. Model kataloğu ve yerel protokol uç noktalarının kendi belgelenmiş hata biçimleri vardır.