# Gemini 4 Argon — /chat/completions

Gemini 4 Argon Beta는 텍스트 대화, 스트리밍과 Low / Medium / High 세 단계 사고를 지원하며 기본값은 Low입니다. OpenAI SDK로 사용하며 사고 토큰은 출력으로 과금합니다.

**엔드포인트:** `POST https://nezhagate.com/v1/chat/completions`

## 빠른 시작

두 단계면 됩니다: 요청 보내기 → 스트리밍으로 답변 받기. YOUR_API_KEY를 내 키로 바꾸면 아래 명령을 그대로 실행할 수 있습니다. 엔드포인트가 OpenAI Chat Completions와 같으므로 기존 OpenAI 코드는 `base_url`과 `model`만 바꾸면 됩니다.

**1단계 · 요청 보내기**

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-argon", "messages": [{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}]}'
```

응답(HTTP 200)

```
{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "gemini-4-argon",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "광합성은 식물이 햇빛을 이용해 이산화탄소와 물을 당으로 바꾸고 산소를 내보내는 과정입니다.",
        "reasoning_content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 186,
    "total_tokens": 204,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 144}
  }
}
```

`message.content`는 답변이고 `message.reasoning_content`는 사고 과정입니다. `usage`는 이 요청에 과금되는 토큰 수이며, 사고 토큰은 `completion_tokens`에 포함되어 출력 요금으로 과금됩니다.

**2단계 · 스트리밍으로 받기(권장)**

```
curl -N https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-argon", "stream": true, "messages": [{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}]}'
```

스트림은 표준 SSE입니다. 각 청크의 본문은 `choices[0].delta.content`에 담기고, 마지막 청크에는 `usage`가 담기며, 스트림은 `data: [DONE]`으로 끝납니다. 답변이 길거나 모델이 먼저 생각해야 할 때는 스트리밍을 쓰세요. 비스트리밍 요청은 약 10분이 지나면 연결이 끊깁니다.

**Python(OpenAI SDK)**

```
from openai import OpenAI

client = OpenAI(base_url="https://nezhagate.com/v1", api_key="YOUR_API_KEY")

# 1. 질문 하나에 답변 하나
resp = client.chat.completions.create(
    model="gemini-4-argon",
    messages=[{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}],
)
print(resp.choices[0].message.content)

# 2. 스트리밍
stream = client.chat.completions.create(
    model="gemini-4-argon",
    messages=[{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

## 인증
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 사양 한눈에 보기

| 입력과 출력이 공유하는 컨텍스트 | 약 100만 토큰 |
| --- | --- |
| 입력 | 텍스트 |
| 사고 | `low / medium / high`를 선택하며 기본값은 `low`입니다. 모든 단계의 토큰 단가는 같습니다. |
| 도구 호출 | 보장하지 않음: `tools`가 무시되고 모델이 바로 답할 수 있음 |
| 웹 검색 | 지원(`web_search: true`, 검색 자체는 무료) |
| 엔드포인트 | /v1/chat/completions |
| 스트리밍 | 지원(`stream: true`, SSE) |
| 과금 방식 | 토큰 단위: 입력, 출력(사고 포함), 캐시 적중에 각각 요금 적용, 실패하면 과금되지 않음 |

## 요청 파라미터

`POST /v1/chat/completions`의 요청 본문(JSON)이며, OpenAI Chat Completions와 같습니다. 자주 쓰는 파라미터와 이 모델에서의 실제 동작은 다음과 같습니다:

| 파라미터 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| model | string | 예 | 모델 ID: `gemini-4-argon`. |
| messages | array | 예 | 대화 메시지 배열입니다. 각 메시지에는 `role`(`system`, `user`, `assistant`, `tool` 중 하나)과 `content`가 있습니다. 여러 턴에 걸친 대화는 이전 메시지를 순서대로 모두 보내세요. |
| stream | boolean | 아니오 | `true`면 SSE로 스트리밍하며, 마지막 청크에 `usage`가 담깁니다. 기본값은 `false`입니다. |
| max_tokens | integer | 아니오 | 사고를 포함한 요청 출력 길이입니다. 이 Beta는 엄격한 출력 상한을 보장하지 않습니다. 비용 관리를 위해 프롬프트에서 길이를 제한하고 작업을 나누세요. |
| temperature / top_p | number | 아니오 | 샘플링 매개변수를 보낼 수 있으나 이 Beta에서는 제어 효과를 별도로 검증하지 않았습니다. |
| reasoning_effort | string | 아니오 | `low / medium / high`를 선택하며 기본값은 `low`입니다. 모든 단계의 토큰 단가는 같습니다. |
| web_search | boolean | 아니오 | `true`면 먼저 웹 검색을 하고 그 결과를 참고 자료로 모델에 넘깁니다. 자세한 내용은 아래를 보세요. |

먼저 이 페이지의 매개변수를 사용하세요. 도구 호출, 멀티모달 입력과 JSON 모드는 현재 보장하지 않습니다.

## 가격

토큰 단위로 과금하며, 아래 요금(100만 토큰당)은 실시간으로 반영됩니다. 성공한 요청의 실제 사용량만 과금하고, 실패, 시간 초과, 거부된 요청은 과금하지 않습니다. 1크레딧 = $0.005.

| 종류 | 100만 토큰당 가격(USD) | 100만 토큰당 크레딧 |
| --- | --- | --- |
| 입력 | $0.50 | 100 |
| 출력(사고 포함) | $3.00 | 600 |
| 캐시 적중 | $0.05 | 10 |

예를 들어 입력 2,000 토큰, 출력 1,000 토큰(사고 포함)인 요청 한 건은 약 $0.004입니다.

## 사고(Thinking)

`reasoning_effort`를 `low`, `medium` 또는 `high`로 설정합니다. 생략하면 `low`입니다.

표시 가능한 사고는 `reasoning_content`로 반환됩니다. `usage.completion_tokens`는 사고와 답변을 포함하므로 사고 토큰을 다시 더하지 마세요.

세 단계의 단가는 같습니다. 사고 강도가 높으면 출력 토큰을 더 소비할 수 있습니다.

사고 토큰은 `usage.completion_tokens`에 포함되어 출력 요금으로 과금됩니다(일부 모델은 `completion_tokens_details.reasoning_tokens`에 따로 표시합니다).

```
{
  "model": "gemini-4-argon",
  "messages": [{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}],
  "reasoning_effort": "medium"
}
```

## 프롬프트 캐싱

자동 암시적 캐시를 지원합니다. 긴 입력을 반복하면 적중할 수 있으며 실제 적중분은 일반 입력 단가의 1/10로 계산합니다. 매번 적중을 보장하지 않으며 명시적 캐시 생성은 제공하지 않습니다.

`usage.prompt_tokens`는 전체 입력입니다. `usage.prompt_tokens_details.cached_tokens`는 그중 캐시 적중분입니다. 실제 적중분에만 캐시 단가를 적용합니다.

## 웹 검색

선택적 게이트웨이 `web_search`는 검색한 텍스트를 모델에 전달합니다. 모델 자체 검색이나 도구 지원이 검증되었다는 의미는 아닙니다.

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-argon", "web_search": true, "messages": [{"role": "user", "content": "오늘 주요 기술 뉴스를 알려 줘"}]}'
```

## Beta 제공 범위

- 텍스트 대화, 스트리밍과 세 단계 사고를 검증했습니다. 도구, 멀티모달 입력과 JSON 모드는 아직 검증하지 않았습니다.

- 공식 컨텍스트는 약 100만 토큰이며 입력과 출력이 공유합니다. 긴 입력 검색은 검증했지만 전체 창이나 백만 토큰 출력은 검증하지 않았습니다.

- 긴 작업은 나누어 실행하세요. `max_tokens`는 검증된 엄격한 예산 상한이 아닙니다. 실패 요청은 과금하지 않으며 출력 후 중단은 실제 사용량으로 정산합니다.

## 오류와 환불

오류는 `error` 객체(`message`, `type`, `code`, `param`)로 돌아옵니다. HTTP 상태 코드와 `code`로 판단하고, `message` 문구로는 판단하지 마세요. 실패한 요청은 과금되지 않으며, 전체 목록은 [오류 코드](https://nezhagate.com/ko/docs/guide/errors)에 있습니다.

| HTTP | code | 원인 | 조치 |
| --- | --- | --- | --- |
| 400 | invalid_messages / invalid_role / invalid_max_tokens | 채팅 요청의 `messages`가 없거나 비어 있거나 형식이 잘못되었거나, `role`이 허용된 값이 아니거나, `max_tokens`가 양의 정수가 아닙니다. 문제가 된 필드는 `param`에 표시됩니다. | `param`이 가리키는 필드를 고치세요. |
| 400 | model_not_found | 모델 ID의 철자가 틀렸거나, `model`이 없거나, 이 엔드포인트에서 쓸 수 없는 모델입니다(예: 이미지 엔드포인트에 채팅 모델을 지정한 경우). | `GET /v1/models` 또는 [API 레퍼런스](https://nezhagate.com/ko/docs/api)에 있는 모델 ID를 쓰세요. |
| 400 | max_tokens_too_small | 추론 모델이 `max_tokens`를 모두 사고에 써서 답변을 쓰지 못했습니다(비스트리밍 채팅). | `max_tokens`를 늘린 뒤 다시 시도하세요. |
| 4xx | invalid_request | 모델 제공사가 요청을 거부했습니다(예: 컨텍스트가 너무 길거나 지원하지 않는 파라미터). 상태 코드와 `message`는 모델 제공사가 보낸 그대로 전달되며, `code`는 모델 제공사가 준 값입니다. | `message`에 적힌 대로 요청을 고치세요. |
| 401 | invalid_api_key | 키가 없거나, 삭제되었거나, 비활성화되었습니다. 계정이 비활성화된 경우에도 나옵니다. | 콘솔의 「API Keys」 페이지에서 이 키를 확인하세요. |
| 402 | insufficient_quota | 이 요청의 크레딧을 예약하기에 잔액이 부족합니다. 게이트웨이는 요청에 들 수 있는 최대 비용을 먼저 예약하므로, 동시 호출이 몰릴 때도 이 오류가 날 수 있습니다. | 동시 호출이 몰린 경우라면 몇 초 기다린 뒤 다시 시도하고, 그렇지 않으면 충전하세요. |
| 403 | permission_denied | 이 모델이 키의 모델 허용 목록에 없습니다. | 허용 목록에 있는 모델을 쓰거나, 콘솔에서 허용 목록을 수정하세요. |
| 429 | rate_limit_exceeded | 이 키에 설정한 분당 요청 수를 넘었습니다(최근 60초 기준). `Retry-After` 헤더는 붙지 않습니다. | 몇 초 기다린 뒤 다시 시도하거나, 콘솔에서 이 키의 한도를 올리세요. |
| 429 | rate_limit_exceeded | 이 모델의 모든 회선이 가득 차서 요청을 보내지 못했습니다. 채팅 엔드포인트에서만 나오며, 이미지와 영상 작업은 거절되지 않고 대기열에서 기다립니다. OpenAI 호환 엔드포인트는 `Retry-After`를 붙입니다. | `Retry-After`의 초만큼 기다린 뒤 다시 시도하세요. |
| 502 | upstream_timeout | 회선이 시간 초과되었습니다. 첫 토큰이 너무 늦게 오는 경우도 포함됩니다. | 다시 시도하세요. 긴 답변에는 `stream: true`를 쓰세요. |
| 502 | upstream_unavailable | 회선에 오류가 났거나 잠시 쓸 수 없습니다. | 잠시 후 다시 시도하세요. |
| 502 | upstream_busy | 모델 제공사가 요청 빈도를 제한하고 있습니다. 모델 제공사의 429는 그대로 전달되지 않고 이 502로 바뀌어 돌아옵니다. | 잠시 후 다시 시도하세요. |
| 502 | empty_completion | 모델 제공사가 빈 내용을 돌려주었습니다. 요청 내용에 대한 판정이 아닙니다. | 다시 시도하세요. |
| 503 | model_maintenance | 모델이 점검 중이라 요청을 받지 않습니다. 점검 중에는 다른 모델이 대신 답변하지도 않습니다. | 점검이 끝나면 다시 시도하세요. 진행 상황은 [서비스 상태](https://nezhagate.com/ko/status)에서 볼 수 있습니다. |

스트리밍이 출력을 시작한 뒤 실패하면 상태 코드는 바뀌지 않습니다. 오류는 `error`가 담긴 데이터 줄로 오거나, 스트림이 그냥 끝납니다(`data: [DONE]` 없이). 이런 경우 중단된 것으로 처리하세요.