> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok 모델 시리즈 가이드

> APIYI의 xAI Grok 4.x 시리즈(grok-4.5 / grok-4.3 / grok-4.20 / grok-build-0.1)는 OpenAI 호환 + Responses API 이중 엔드포인트를 제공하며, 웹 검색 / X 검색 / 코드 실행 / MCP 서버 측 도구가 정상 동작함을 검증했습니다. 표시된 가격은 xAI 공식 가격과 일치합니다.

Grok은 xAI의 대표 모델 패밀리입니다. 현재 세대(Grok 4.x)는 5개의 제품 라인—플래그십 범용, 장문 컨텍스트 표준, 추론/비추론 변형, 코드 중심, 멀티 에이전트 협업—으로 구성되며, 모두 APIYI에서 사용할 수 있습니다. **xAI의 공식 API 자체가 OpenAI 호환입니다**(Chat Completions + Responses API). 별도의 독자 프로토콜이 없으므로, OpenAI SDK로 APIYI를 통해 Grok을 호출하면 공식 서버 측 도구(web search, X search, code execution, Remote MCP)를 포함한 전체 기능을 사용할 수 있습니다.

이 문서 그룹은 2026년 7월 13일(UTC+8)에 APIYI 게이트웨이에 대해 수행한 전체 실사용 테스트 — 56개의 요청/응답 로그 — 를 바탕으로 하므로, 여기에 명시된 모든 기능 경계는 검증되었습니다.

<Note>
  **🚀 하이라이트**: grok-4.5는 2026년 7월 8일에 출시된 xAI의 최신 플래그십(지식 기준일 2026년 2월)으로, 코딩 및 에이전트형 작업을 위해 설계되었습니다. grok-4.3과 grok-4.20 시리즈는 **1M-token 컨텍스트 윈도우**를 제공하며, Responses API 도구인 **web\_search / x\_search / code\_interpreter / MCP는 모두 APIYI에서 정상 동작하는 것으로 검증되었고**, X search는 Grok만의 고유한 기능입니다. 또한 네이티브 responses 지원 덕분에 Grok은 [OpenAI Codex에 바로 연결할 수 있습니다](/ko/scenarios/programming/codex-cli).
</Note>

## 모델 라인업

<CardGroup cols={3}>
  <Card title="grok-4.5" icon="trophy">
    **플래그십 · 코드 및 일반**

    xAI의 가장 지능적인 모델로, 500K 컨텍스트를 제공하며 코딩, 에이전틱 작업, 지식 작업을 위해 설계되었습니다.
  </Card>

  <Card title="grok-4.3" icon="scale">
    **표준 주력 모델**

    플래그십 가격의 약 60% 수준에 1M 컨텍스트를 제공하며, 일상적인 채팅과 중간 수준의 추론에 균형 잡힌 선택입니다.
  </Card>

  <Card title="grok-4.20 변형" icon="split">
    **추론 / 비추론**

    `-reasoning` 및 `-non-reasoning`은 같은 가격과 1M 컨텍스트를 공유합니다. 사고 과정을 원하시는지에 따라 선택하십시오.
  </Card>

  <Card title="grok-build-0.1" icon="code">
    **코드 중심**

    256K 컨텍스트와 시리즈 내 최저 가격을 제공하여, 고빈도 코드 완성과 가벼운 코딩 작업에 이상적입니다.
  </Card>

  <Card title="grok-4.20-multi-agent-beta-0309" icon="users">
    **멀티 에이전트 협업**

    여러 에이전트가 복잡한 리서치 작업을 병렬로 수행합니다. 특수 과금 프로필이 적용됩니다. [Multi-Agent Model](/ko/api-capabilities/grok/multi-agent)을 참조하십시오.
  </Card>

  <Card title="더 많은 기능 페이지" icon="book-open">
    채팅/추론/비전: [Chat 및 추론](/ko/api-capabilities/grok/chat); 실시간 검색: [웹 및 X 검색](/ko/api-capabilities/grok/web-search).
  </Card>
</CardGroup>

## 가격

표시된 가격은 xAI의 공식 가격과 일치합니다(2026-07-13에 APIYI 가격 API와 항목별로 대조하여 검증했습니다). APIYI의 할인은 [충전 프로모션](/ko/faq/recharge-promotions)에서 비롯됩니다.

| 모델 ID                             | 컨텍스트 | 입력                 | 출력                 | 포지셔닝                 |
| --------------------------------- | ---- | ------------------ | ------------------ | -------------------- |
| `grok-4.5`                        | 500K | \$2.00 / 1M tokens | \$6.00 / 1M tokens | 플래그십: 코드 / 에이전트 / 범용 |
| `grok-4.3`                        | 1M   | \$1.25 / 1M tokens | \$2.50 / 1M tokens | 표준 주력                |
| `grok-4.20-0309-reasoning`        | 1M   | \$1.25 / 1M tokens | \$2.50 / 1M tokens | 추론 변형                |
| `grok-4.20-0309-non-reasoning`    | 1M   | \$1.25 / 1M tokens | \$2.50 / 1M tokens | 비추론(빠르고 저비용)         |
| `grok-4.20-multi-agent-beta-0309` | 1M   | \$1.25 / 1M tokens | \$2.50 / 1M tokens | 멀티 에이전트(과금 증폭!)      |
| `grok-build-0.1`                  | 256K | \$1.00 / 1M tokens | \$2.00 / 1M tokens | 코드 중심                |

<Info>
  * 별칭 `grok-code-fast` / `grok-code-fast-1`도 호출할 수 있습니다(연결성 검증 완료). 가격은 [모델 정보 페이지](/ko/api-capabilities/model-info)를 참조하십시오.
  * 캐시된 입력 tokens는 할인된 요율로 과금됩니다. Grok 프리픽스 캐싱은 **자동입니다 — 별도 설정이 필요하지 않습니다**; [캐시 과금](/ko/faq/cache-billing)을 참조하십시오.
  * 표시 가격은 xAI 공식 가격과 일치합니다. 더 낮은 실효 비용을 위해 [충전 프로모션](/ko/faq/recharge-promotions)을 함께 적용하십시오.
</Info>

## 검증된 기능 매트릭스

2026-07-13 (UTC+8)에 APIYI 게이트웨이를 대상으로 테스트했습니다(✅ 작동 검증됨; — 미포함, 동일한 아키텍처에서는 동일할 것으로 예상됨):

| 기능                        |  grok-4.5  |  grok-4.3  | 4.20-reasoning | 4.20-non-reasoning | grok-build-0.1 | multi-agent |
| ------------------------- | :--------: | :--------: | :------------: | :----------------: | :------------: | :---------: |
| 기본 채팅                     |      ✅     |      ✅     |        ✅       |          ✅         |        ✅       |      ✅      |
| 스트리밍(usage 포함)            |      ✅     |      ✅     |        ✅       |          ✅         |        ✅       |      ✅      |
| 연쇄 사고 `reasoning_content` | ✅ 기본적으로 켜짐 | ✅ 기본적으로 켜짐 |        ✅       |      ❌ 설계상 꺼짐      |   ✅ 기본적으로 켜짐   |     내부용만    |
| `reasoning_effort` 파라미터   |      ✅     |      —     |   ❌ 명시적으로 거부됨  |          —         |        —       |      —      |
| 구조화된 출력(json\_schema)     |      ✅     |      ✅     |        ✅       |          —         |        ✅       |      ✅      |
| 함수 호출 / 도구 사용             |      ✅     |      ✅     |        —       |          —         |        ✅       |      —      |
| 비전 입력(이미지 이해)             |      ✅     |      ✅     |        —       |          ✅         |        —       |      —      |
| 프롬프트 캐싱(자동)               |      ✅     |      ✅     |        ✅       |          ✅         |        ✅       |      ✅      |
| Responses API + 서버 측 도구   |      ✅     |      —     |        —       |          —         |        —       |      —      |

## 엔드포인트

| 엔드포인트                  | 메서드    | 용도                                                          |
| ---------------------- | ------ | ----------------------------------------------------------- |
| `/v1/chat/completions` | `POST` | 채팅 / 추론 / 함수 호출 / 구조화된 출력 / 비전 (모든 모델이 공유함; `model`를 통해 선택) |
| `/v1/responses`        | `POST` | Responses API: 웹 검색, X 검색, 코드 실행, Remote MCP 및 기타 서버 측 도구   |

### Codex에서 바로 사용하기

Grok은 `/v1/responses`를 기본적으로 지원하므로, 네이티브 responses 프로토콜을 통해 **OpenAI Codex**(데스크톱 앱 / IDE 확장 / CLI)에서 실행되는 몇 안 되는 비-OpenAI 모델 중 하나입니다. `model = "grok-4.5"`와 `wire_api = "responses"`를 `config.toml`에 설정하면 5분 안에 연결되며, Codex의 에이전트 기능(도구 호출, 추론 항목 등)도 모두 네이티브 프로토콜로 동작합니다. 이에 비해 APIYI의 Claude / Gemini는 OpenAI 호환 채팅 모드(`wire_api = "chat"` 폴백)에서만 실행되며, 이 경우 Codex / 에이전트 시나리오에서 프로토콜 호환성 문제가 발생합니다. 전체 설정 단계는 [Codex 통합 가이드](/ko/scenarios/programming/codex-cli)를 참조하십시오.

<Warning>
  **다음은 APIYI에서 지원되지 않습니다**(검증됨 — 다음 함정은 피하십시오):

  * **레거시 Completions (`/v1/completions`)**: 상위 계층에서 거부됨 — 전체 Grok 4.x 라인은 추론 아키텍처이며 공식 수준에서 원시 텍스트 completion을 지원하지 않습니다
  * **레거시 라이브 검색 파라미터 `search_parameters`**: xAI에서 제거됨(410 확인됨). 모든 라이브 검색은 Responses API 도구를 통해 이루어집니다 — [Web 및 X 검색](/ko/api-capabilities/grok/web-search)을 참조하십시오
  * **Batch API / Files**: 게이트웨이를 통해 라우팅되지 않으며, 키 풀 모드에는 적용되지 않습니다
  * **Deferred Completions (`deferred: true`)**: 이 파라미터는 **조용히 무시됩니다** — 요청은 동기적으로 실행되며 정상적으로 과금됩니다. 이에 의존하지 마십시오
  * **Collections Search (RAG / file\_search)**: xAI 콘솔에서 미리 구축된 collections가 필요하며, 키 풀 모드에는 적용되지 않습니다
  * **Context Compaction (`/v1/responses/compact`)**, **Priority Processing (`service_tier: "priority"` — 테스트에서는 기본값으로 폴백됩니다)**, **WebSocket 모드**, **mTLS 인증**: 모두 지원되지 않습니다
</Warning>

## 빠른 시작

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.apiyi.com/v1/chat/completions" \
    -H "Authorization: Bearer sk-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "grok-4.5",
      "messages": [
        {"role": "user", "content": "Introduce yourself in one sentence"}
      ]
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-your-api-key",
      base_url="https://api.apiyi.com/v1"
  )

  resp = client.chat.completions.create(
      model="grok-4.5",
      messages=[{"role": "user", "content": "Introduce yourself in one sentence"}]
  )
  print(resp.choices[0].message.content)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    apiKey: 'sk-your-api-key',
    baseURL: 'https://api.apiyi.com/v1',
  });

  const resp = await client.chat.completions.create({
    model: 'grok-4.5',
    messages: [{ role: 'user', content: 'Introduce yourself in one sentence' }],
  });
  console.log(resp.choices[0].message.content);
  ```
</CodeGroup>

<Tip>
  **어떤 모델을 선택할지**: 기본값으로 `grok-4.3`를 사용합니다 (1M 컨텍스트, 균형 잡힌 가격); 코딩 에이전트와 복잡한 작업에는 `grok-4.5`로 업그레이드합니다; 빠르고 저비용의 응답이 필요할 때는 `grok-4.20-0309-non-reasoning`를 사용합니다 (체인 오브 소트 없이, 가장 저렴한 출력); 고빈도 코드 자동완성에는 `grok-build-0.1`를 사용합니다; 그리고 복잡한 리서치 작업에서만 멀티 에이전트 모델을 사용하십시오 (과금 증폭에 유의하십시오).
</Tip>

## 추론 token에 대한 과금 참고

`grok-4.5` / `grok-4.3` / `grok-build-0.1` **기본적으로 내부적으로 추론합니다**: 응답에는 `reasoning_content`가 포함되며, 추론 token은 출력 과금에 포함됩니다. 테스트에서는 짧은 답변이 보이는 token은 30개뿐이었지만 출력 token 586개가 과금되었고(그중 556개는 추론 token이었습니다). 비용에 민감한 짧은 질의응답의 경우 `grok-4.20-0309-non-reasoning`로 전환하십시오. 자세한 내용은 [Chat & 추론](/ko/api-capabilities/grok/chat)에서 확인하십시오.

## FAQ

<AccordionGroup>
  <Accordion title="Grok에는 자체 네이티브 API 형식이 있습니까?">
    별도의 독자 프로토콜은 없습니다. xAI의 공식 REST API는 OpenAI 호환입니다: `/v1/chat/completions` (chat)와 `/v1/responses` (Responses API 및 서버 측 tools)입니다. OpenAI SDK의 대상으로 `https://api.apiyi.com/v1`를 지정하면 전체 기능을 사용할 수 있으며, “호환 모드 다운그레이드”는 없습니다.
  </Accordion>

  <Accordion title="웹 검색은 어떻게 활성화합니까?">
    Responses API를 사용하십시오: `tools: [{"type": "web_search"}]` (또는 `x_search`). Chat Completions의 기존 `search_parameters` 필드는 xAI에 의해 제거되었으며(410 확인됨) — 사용하지 마십시오. [Web 및 X 검색](/ko/api-capabilities/grok/web-search)을 참조하십시오.
  </Accordion>

  <Accordion title="모델이 자신을 Grok 4라고 소개합니다 — 요청이 잘못된 모델에 도달한 것입니까?">
    이는 정상입니다. 모든 Grok 4.x 모델은 자신을 단순히 “Grok 4”라고만 식별하며(멀티 에이전트 모델은 자신을 Oppie라고 부릅니다), 4.5 / 4.3 같은 정확한 버전 번호는 보고하지 않습니다. 모델의 자기소개가 아니라 요청과 응답의 `model` 필드를 통해 식별을 확인하십시오.
  </Accordion>

  <Accordion title="캐싱에 설정이 필요합니까?">
    필요 없습니다. Grok 프리픽스 캐싱은 자동입니다. `usage.prompt_tokens_details.cached_tokens`(테스트에서는 동일한 접두사의 두 번째 요청이 2688/2735 token에 캐시 적중했습니다). 게이트웨이는 키 풀 모드로 실행되므로 적중률에 대해 합리적인 기대를 가지십시오 — [캐시 과금](/ko/faq/cache-billing)을 참조하십시오.
  </Accordion>

  <Accordion title="컨텍스트 윈도우를 초과하면 어떻게 됩니까?">
    400 오류가 발생합니다. 한도는 모델마다 다릅니다: grok-4.5는 500K, grok-4.3과 4.20 시리즈는 1M, grok-build-0.1은 256K입니다. 더 긴 콘텐츠는 요약하거나, 청크로 나누거나, RAG 검색을 사용하십시오.
  </Accordion>

  <Accordion title="실패한 요청도 과금됩니까?">
    4xx 클라이언트 오류(잘못된 매개변수 / 인증 실패)는 과금되지 않습니다. token이 실제로 반환된 요청은 실제 사용량 기준으로 과금됩니다. `deferred: true`는 조용히 무시되며 — 요청은 실제로는 동기적으로 실행되고 정상적으로 과금됩니다.
  </Accordion>
</AccordionGroup>

## 관련 문서

<CardGroup cols={2}>
  <Card title="채팅 및 추론" icon="message-square" href="/ko/api-capabilities/grok/chat">
    스트리밍, 사고 과정, 구조화된 출력, 함수 호출, 비전, 캐싱
  </Card>

  <Card title="웹 및 X 검색" icon="globe" href="/ko/api-capabilities/grok/web-search">
    Responses API의 web\_search / x\_search 도구를 직접 다루는 방법
  </Card>

  <Card title="코드 실행 및 MCP" icon="terminal" href="/ko/api-capabilities/grok/code-execution-mcp">
    서버 측 Python 샌드박스 및 Remote MCP 통합
  </Card>

  <Card title="멀티 에이전트 모델" icon="users" href="/ko/api-capabilities/grok/multi-agent">
    멀티 에이전트 모델의 기능과 과금 프로필
  </Card>

  <Card title="Codex에서 Grok 사용" icon="code" href="/ko/scenarios/programming/codex-cli">
    네이티브 responses 프로토콜, 5분 만에 Codex에 연결
  </Card>

  <Card title="Grok 4.5 출시 심층 분석" icon="newspaper" href="/en/news/grok-4-5-launch">
    xAI의 최신 플래그십에 대한 심층 분석
  </Card>

  <Card title="모델 정보" icon="database" href="/ko/api-capabilities/model-info">
    사용 가능한 모든 모델과 그룹
  </Card>
</CardGroup>