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

# 추론 모델(Reasoning Models)

> Venice API에서 사고 과정이 보이는 추론 모델 사용하기

일부 모델은 답하기 전에 소리 내어 생각합니다. 문제를 단계별로 풀어 나간 뒤 최종 답을 제공합니다. 덕분에 수학, 코드, 논리 중심 작업에서 더 강력한 성능을 발휘합니다.

<div id="reasoning-models-placeholder" />

모델, 가격, context 한도의 전체 목록은 [Models 페이지](/models/overview)에서 확인하세요. 모든 추론 모델이 [`reasoning_effort`](#reasoning-effort) 파라미터를 지원하는 것은 아닙니다. 자세한 내용은 [모델 지원](#model-support)을 참고하세요.

## 출력 읽기

추론 모델은 사고 과정을 별도의 `reasoning_content` 필드로 반환하며, `content`는 깔끔하게 유지합니다:

<CodeGroup>
  ```python Python theme={"dark"}
  response = client.chat.completions.create(
      model="zai-org-glm-5-1",
      messages=[{"role": "user", "content": "What is 15% of 240?"}]
  )

  thinking = response.choices[0].message.reasoning_content
  answer = response.choices[0].message.content
  ```

  ```javascript Node.js theme={"dark"}
  const response = await client.chat.completions.create({
      model: "zai-org-glm-5-1",
      messages: [{ role: "user", content: "What is 15% of 240?" }]
  });

  const thinking = response.choices[0].message.reasoning_content;
  const answer = response.choices[0].message.content;
  ```

  ```bash cURL theme={"dark"}
  curl https://api.venice.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "zai-org-glm-5-1",
      "messages": [{"role": "user", "content": "What is 15% of 240?"}]
    }'
  ```
</CodeGroup>

<Info>
  일부 공급자(Anthropic, Google, OpenAI, Qwen)는 암호화되거나 요약된 추론 토큰을 반환합니다. 이 경우 `reasoning_content`에는 `"[Some reasoning content is encrypted]"` 자리표시자가 포함됩니다.
</Info>

### 스트리밍

스트리밍 시 `reasoning_content`는 최종 답변보다 먼저 delta로 도착합니다:

<CodeGroup>
  ```python Python theme={"dark"}
  stream = client.chat.completions.create(
      model="zai-org-glm-5-1",
      messages=[{"role": "user", "content": "Explain photosynthesis"}],
      stream=True
  )

  for chunk in stream:
      if chunk.choices:
          delta = chunk.choices[0].delta
          if delta.reasoning_content:
              print(delta.reasoning_content, end="")
          if delta.content:
              print(delta.content, end="")
  ```

  ```javascript Node.js theme={"dark"}
  const stream = await client.chat.completions.create({
      model: "zai-org-glm-5-1",
      messages: [{ role: "user", content: "Explain photosynthesis" }],
      stream: true
  });

  for await (const chunk of stream) {
      if (chunk.choices?.[0]?.delta) {
          const delta = chunk.choices[0].delta;
          if (delta.reasoning_content) process.stdout.write(delta.reasoning_content);
          if (delta.content) process.stdout.write(delta.content);
      }
  }
  ```

  ```bash cURL theme={"dark"}
  curl https://api.venice.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "zai-org-glm-5-1",
      "messages": [{"role": "user", "content": "Explain photosynthesis"}],
      "stream": true
    }'
  ```
</CodeGroup>

## Reasoning effort

`reasoning_effort` 파라미터는 모델이 응답하기 전에 얼마나 많이 생각할지를 제어합니다. 더 높은 effort는 더 깊은 추론을 의미하지만 토큰과 지연 시간이 늘어납니다.

### 허용되는 값

| Value     | Description         |
| --------- | ------------------- |
| `none`    | 추론을 완전히 비활성화        |
| `minimal` | 최소한의 effort로 기본 추론  |
| `low`     | 단순한 문제를 위한 가벼운 추론   |
| `medium`  | 중간 복잡도를 위한 균형 잡힌 추론 |
| `high`    | 복잡한 문제를 위한 깊은 추론    |
| `xhigh`   | 매우 깊은 추론            |
| `max`     | 최대 추론 능력            |

<Warning>
  모든 모델이 모든 값을 지원하지는 않습니다. Venice는 가장 가까운 지원 레벨로 **자동 매핑하지 않습니다**. 지원되지 않는 값은 업스트림 공급자에서 400 에러를 반환합니다. 예를 들어 Claude에 `xhigh`를 보내거나 GPT-5.2에 `max`를 보내면 실패합니다.

  확실하지 않다면 `low`, `medium`, `high`를 사용하세요. 가장 널리 지원되는 값입니다.
</Warning>

### 모델 지원

#### OpenAI

| Model                        | Supported values                         |
| ---------------------------- | ---------------------------------------- |
| GPT-5.2                      | `none`, `low`, `medium`, `high`, `xhigh` |
| GPT-5.2 Codex, GPT-5.3 Codex | `low`, `medium`, `high`, `xhigh`         |

#### Anthropic

| Model                                   | Supported values               |
| --------------------------------------- | ------------------------------ |
| Claude Opus 4.6, Opus 4.6 Fast          | `low`, `medium`, `high`, `max` |
| Claude Opus 4.5, Sonnet 4.5, Sonnet 4.6 | `low`, `medium`, `high`        |

#### Google

| Model                  | Supported values                   |
| ---------------------- | ---------------------------------- |
| Gemini 3 Pro Preview   | `low`, `high`                      |
| Gemini 3.1 Pro Preview | `low`, `medium`, `high`            |
| Gemini 3 Flash Preview | `minimal`, `low`, `medium`, `high` |

#### xAI

Grok 모델(Grok 4.1 Fast, Grok Code Fast)은 `reasoning_effort`를 **지원하지 않습니다**. 지정하면 에러가 발생합니다.

#### 그 외 모델

| Model                                       | Supported values        |
| ------------------------------------------- | ----------------------- |
| Qwen 3 235B A22B Thinking, Qwen 3.5 35B A3B | `low`, `medium`, `high` |
| Kimi K2.5                                   | `low`, `medium`, `high` |
| MiniMax M2.5, M2.1                          | `low`, `medium`, `high` |
| GLM 5.1 series                              | 내장 추론만 지원, 설정 불가        |
| DeepSeek R1                                 | 내장 추론만 지원, 설정 불가        |

### 사용법

`reasoning_effort`를 최상위 파라미터로 전달하거나 중첩된 `reasoning.effort` 포맷을 사용하세요:

<CodeGroup>
  ```python Python theme={"dark"}
  response = client.chat.completions.create(
      model="minimax-m25",
      messages=[{"role": "user", "content": "Prove that there are infinitely many primes"}],
      extra_body={"reasoning": {"effort": "high"}}
  )
  ```

  ```javascript Node.js theme={"dark"}
  const response = await client.chat.completions.create({
      model: "minimax-m25",
      messages: [{ role: "user", content: "Prove that there are infinitely many primes" }],
      reasoning: { effort: "high" }
  });
  ```

  ```bash cURL theme={"dark"}
  curl https://api.venice.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "minimax-m25",
      "messages": [{"role": "user", "content": "Prove that there are infinitely many primes"}],
      "reasoning": {"effort": "high"}
    }'
  ```
</CodeGroup>

평탄한 형식 `"reasoning_effort": "high"`도 허용됩니다.

## 추론 비활성화

추론을 비활성화하는 방법은 두 가지가 있습니다:

| Method                     | Syntax                            | How it works                                            |
| -------------------------- | --------------------------------- | ------------------------------------------------------- |
| `reasoning.enabled: false` | `"reasoning": {"enabled": false}` | 공급자에게 추론 파라미터가 전송되지 않게 하는 Venice 차원의 토글. **권장.**        |
| `reasoning.effort: "none"` | `"reasoning": {"effort": "none"}` | 공급자에게 전달되며 처리 방식은 공급자가 결정합니다. 일부 모델(예: GPT-5.x)만 지원합니다. |

해당 옵션을 지원하는 모델에서는 `reasoning.enabled: false`가 더 신뢰할 수 있는 선택입니다:

| Model                                        | 비활성화 가능?                 |
| -------------------------------------------- | ------------------------ |
| GPT-5.2                                      | 예                        |
| GPT-5.2 Codex, GPT-5.3 Codex                 | 예(단, `none` effort는 미지원) |
| Qwen 3 235B A22B Thinking, Qwen 3.5 35B A3B  | 예                        |
| GLM 5.1 series                               | 예                        |
| Claude Opus 4.5/4.6/4.6 Fast, Sonnet 4.5/4.6 | 아니오(항상 추론)               |
| Gemini 3 Pro, 3.1 Pro, 3 Flash               | 아니오(항상 추론)               |
| DeepSeek R1                                  | 아니오(항상 추론)               |

<CodeGroup>
  ```python Python theme={"dark"}
  response = client.chat.completions.create(
      model="openai-gpt-52",
      messages=[{"role": "user", "content": "What's the capital of France?"}],
      extra_body={"reasoning": {"enabled": False}}
  )
  ```

  ```javascript Node.js theme={"dark"}
  const response = await client.chat.completions.create({
      model: "openai-gpt-52",
      messages: [{ role: "user", content: "What's the capital of France?" }],
      reasoning: { enabled: false }
  });
  ```

  ```bash cURL theme={"dark"}
  curl https://api.venice.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai-gpt-52",
      "messages": [{"role": "user", "content": "What is the capital of France?"}],
      "reasoning": {"enabled": false}
    }'
  ```
</CodeGroup>

## 토큰 한도

추론 모델은 가시적인 답변 토큰(`content`)과 추론 토큰(`reasoning_content`)을 모두 생성합니다. 둘 다 토큰 예산에 포함됩니다.

### 토큰 캡 설정

`max_completion_tokens`를 사용해 추론을 포함한 모델 생성 토큰 총량의 상한을 설정하세요:

```json theme={"dark"}
{
  "model": "deepseek-v4-flash",
  "messages": [...],
  "max_completion_tokens": 500
}
```

`max_tokens`도 허용되며 동일하게 동작합니다. 둘 다 설정되어 있으면 `max_completion_tokens`가 우선합니다.

가시적인 출력을 더 많이 받으려면 상한을 올리거나, `reasoning_effort`를 낮추거나, [추론을 비활성화](#disabling-reasoning)하세요.

### 사용량 분해 보기

`usage` 객체는 예산이 어떻게 사용되었는지 보여줍니다:

```json theme={"dark"}
"usage": {
  "completion_tokens": 501,
  "completion_tokens_details": { "reasoning_tokens": 169 },
  "prompt_tokens": 13,
  "total_tokens": 514
}
```

이 예에서는 169 토큰이 추론에, 332 토큰이 가시적 답변에 사용되었습니다. 상한에 도달하면 `finish_reason`은 `length`가 됩니다.

각 모델의 상한값은 [`/v1/models`](/api-reference/endpoint/models/list) endpoint의 `maxCompletionTokens`에서 확인할 수 있습니다.

### 비추론 모델

비추론 모델에서는 `max_tokens`와 `max_completion_tokens`가 동일하게 동작하며, 가시적 출력을 직접 제한합니다.

## 기능 탐색

[`/v1/models`](/api-reference/endpoint/models/list) endpoint에서 모델이 지원하는 기능을 확인하세요:

| Field                     | Meaning                                              |
| ------------------------- | ---------------------------------------------------- |
| `supportsReasoning`       | 모델이 추론 기능(chain-of-thought)을 보유                      |
| `supportsReasoningEffort` | 모델이 `reasoning_effort` / `reasoning.effort` 파라미터를 허용 |

## 모범 사례

* 일반적인 용도에는 `medium`을 기본값으로 사용
* 복잡한 작업(수학, 코드, 분석)에는 `high` 또는 `xhigh` 사용
* 지연 시간에 민감한 애플리케이션에는 `low` 사용
* 추론을 끄려면 `reasoning.enabled: false`를 사용하거나 effort를 `none`으로 설정
* 확실하지 않다면 `low`, `medium`, `high`를 사용. 가장 널리 지원되는 값입니다