공통 채팅 완성 | 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에는 현재 공개되지 않았습니다. 활성 연동의 기본 모델이 아닙니다. 모델을 호출하기 전에 자신의 GET https://api.apihop.ai/v1/models 응답으로 접근 가능 여부를 확인하세요.

이 엔드포인트는 기본적으로 완전한 JSON 응답 하나를 반환합니다. SSE 스트리밍이 필요하면 stream: true를 명시하세요.

text

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

인증

모든 요청에는 Bearer 토큰 인증이 필요합니다.

http

Authorization: Bearer YOUR_API_KEY

인증에 실패하면 다음을 확인하세요:

API 키가 올바른지
키가 이 API 기본 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 키에 표시되는 모델은 모델 카탈로그를 확인하세요. 현재 가용성은 자신의 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: 완전한 응답 하나 반환

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 같은 숫자를 사용하세요.

모델 매개변수 차이

현재 텍스트 모델은 최소 스트리밍 및 비스트리밍 Chat 요청을 지원하지만 선택적 매개변수의 수락 여부와 효과는 선택한 모델 및 호환 구현에 따라 다릅니다.

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 오류는 평면 JSON 본문을 사용하며 SSE 시작 전에 반환되는 공급자 HTTP 오류도 포함합니다. 예를 들어 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 프로토콜에는 적용되지 않습니다. 모델 카탈로그와 기본 프로토콜 엔드포인트에는 각각 문서화된 오류 형식이 있습니다.