> ## 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.

# Kimi K3.1 Pro 개요

> Kimi K3.1 Pro 및 고속 모델에 공식 릴레이로 액세스하여 모델 선택, OpenAI 호환 요청, 추론 강도, 스트리밍, tools 호출, 캐시 매개변수를 사용할 수 있으며 테스트 제한이 적용됩니다.

## 개요

**Kimi K3.1 Pro**는 소프트웨어 개발, 복잡한 추론, 다단계 도구 워크플로를 위한 Moonshot AI의 추론 모델입니다. APIYI는 공식 릴레이 모델 `kimi-k3.1-pro` 및 `kimi-k3.1-pro-highspeed`를 제공합니다. 두 모델은 동일한 요청 형식을 사용하며, `model`를 변경하여 모델을 전환할 수 있습니다.

> [!NOTE]
>
> **Pro로 시작한 다음, 워크플로에 더 짧은 지연 시간이 필요하면 Highspeed를 선택하세요.** 두 모델 모두 항상 추론을 사용하며, `reasoning_effort`로 추론 깊이를 제어합니다. Highspeed는 입력, 출력 및 캐시 쓰기 요금이 더 높습니다.

> [!WARNING]
>
> **1시간 캐싱은 이 테스트 실행에서 통과하지 못했으므로 검증된 기능으로 나열되지 않습니다.** 기본 채팅, 스트리밍 및 도구 호출은 통과했습니다. 공식 매개변수와 테스트 한계는 캐싱 섹션을 참조하세요.

> **[빠른 시작](#quick-start)**
>
> OpenAI SDK 또는 HTTP를 사용하여 Chat Completions를 호출합니다.

> **[모델 및 요금](#model-selection-and-pricing)**
>
> 캐시 요금을 포함하여 Pro와 Highspeed를 비교합니다.

> **[추론 및 도구](#tool-calls)**
>
> 추론 강도를 선택하고 도구 호출 기록을 유지합니다.

> **[컨텍스트 캐싱](#context-caching)**
>
> 공식 캐시 매개변수와 APIYI 테스트의 한계를 확인합니다.

## 모델 선택 및 가격

두 모델 모두 실제 token 사용량을 기준으로 과금되며, **APIYI의 현재 설정된 요율은 공식 가격과 일치합니다**. 아래 모든 요율은 **token 100만 개당 USD** 기준입니다. 일반 입력 및 출력 요금을 확인했으며, 캐시 요율은 설정된 가격으로, 이번 테스트 실행에서 확인한 캐시 과금액은 아닙니다:

| 과금 항목 | `kimi-k3.1-pro` | `kimi-k3.1-pro-highspeed` |
| - | - | - |
| 일반 입력 | \$2.00 | \$4.00 |
| 추론을 포함한 출력 | \$10.00 | \$20.00 |
| 캐시 읽기, 설정 요율 | \$0.20 | \$0.20 |
| 캐시 쓰기: 5분, 설정 요율 | \$2.00 | \$4.00 |
| 캐시 쓰기: 1시간, 설정 요율 | \$4.00 | \$8.00 |

> [!NOTE]
>
> 모델 가격은 공식 제공업체의 가격과 일치하며 변경될 수 있습니다. 이 표는 참고용이며, 상단 탐색 메뉴의 **모델 가격** 탭이 기준 정보입니다: [모델 가격](https://docs.apiyi.com/en/models/index.md).

| 모델 | 권장 용도 | 선택 가이드 |
| - | - | - |
| `kimi-k3.1-pro` | 개발, 추론, 문서 처리 및 배치 도구 작업 | 비용을 가장 중요하게 고려할 때 기본으로 선택하는 모델 |
| `kimi-k3.1-pro-highspeed` | 더 빠른 응답이 필요한 대화형 에이전트 및 워크플로 | 지연 시간을 줄이는 대신 token 가격이 더 높습니다 |

### 충전 보너스 적용 시 실질 비용

[20% 보너스 프로모션](https://docs.apiyi.com/ko/faq/recharge-promotions.md) 대상 충전의 경우, 결제 금액 1단위당 사용 가능한 크레딧 1.2단위가 제공됩니다. 따라서 실질 비용은 표시된 가격의 `1 ÷ 1.2 ≈ 83.33%`입니다.

보너스는 사용 가능한 크레딧을 늘리며, 표시된 모델 가격은 그대로 유지됩니다. 자격 요건, 보너스 요율 및 현재 약관은 프로모션 페이지에서 확인하십시오.

## 기본 기능 테스트

APIYI는 \*\*2026-10-25 (UTC+8)\*\*에 두 모델에서 다음 기본 사례를 검증했습니다.

| 기능 | `kimi-k3.1-pro` | `kimi-k3.1-pro-highspeed` |
| - | - | - |
| 비스트리밍 텍스트 채팅 | 통과 | 통과 |
| 스트리밍 텍스트 출력 | 통과 | 통과 |
| JSON 객체 출력 | 통과 | 통과 |
| 함수 호출 및 도구 결과 왕복 | 통과 | 통과 |
| 이미지 이해 | 통과 | 통과 |
| 기본 Responses 요청 | 통과 | 통과 |
| 기본 Messages 요청 | 명시적 샘플링 매개변수 설정 시 통과 | 명시적 샘플링 매개변수 설정 시 통과 |
| 일반 입력 및 출력 과금 로그 | 표시된 요율과 일치 | 표시된 요율과 일치 |

이 가이드에서는 주로 Chat Completions를 사용합니다. 기존 Responses 통합에서도 `POST /v1/responses`을 사용할 수 있습니다. 이미지 테스트에는 Base64 데이터를 사용했습니다.

`POST /v1/messages`에 대한 기본 요청도 통과했습니다. 기본 샘플링 매개변수 변환으로 인한 오류를 방지하려면 `top_p: 0.95` 및 `temperature: 1`을 명시적으로 설정하십시오.

> [!NOTE]
>
> 이 테스트에서는 기본 요청, 의미적 결과, 일반 입력 및 출력 요금을 확인했습니다. 모든 매개변수, 최대 컨텍스트 또는 장시간 실행 동작을 다루지는 않습니다. 아래에 설명된 대로 캐시 수명과 과금은 별도로 확인해야 합니다.

## 빠른 시작

APIYI 토큰을 사용해 `POST /v1/chat/completions`을 호출합니다. `reasoning_effort: "low"`로 시작한 다음, 더 깊은 추론이 필요한 작업에서는 값을 높입니다.

```bash cURL theme={null}
curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro",
    "messages": [
      {"role": "user", "content": "Explain the difference between Python dictionaries and lists, with one use case for each."}
    ],
    "reasoning_effort": "low",
    "max_completion_tokens": 8192
  }'
```

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

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1",
    timeout=300,
)

response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[
        {"role": "user", "content": "Explain the difference between Python dictionaries and lists, with one use case for each."}
    ],
    reasoning_effort="low",
    max_completion_tokens=8192,
)

message = response.choices[0].message
print(message.content)
print(response.usage)
```

> [!TIP]
>
> 구성에서 모델 이름을 유지합니다. 고속 모드를 사용하려면 모델 이름을 `kimi-k3.1-pro-highspeed`으로 변경하고 나머지 통합은 그대로 재사용합니다.

## 추론 및 주요 매개변수

두 모델 모두 **항상 추론을 사용합니다**. `reasoning_effort`로 깊이를 조정하고, Kimi K2.5의 `enable_thinking` 스위치는 그대로 가져오지 마십시오.

| 매개변수 | 사용법 |
| - | - |
| `reasoning_effort` | `low`, `high` 또는 `max`을 사용합니다. 공식 기본값은 `max`입니다 |
| `max_completion_tokens` | 추론과 최종 답변을 합산한 출력 예산입니다 |
| `stream` | 스트리밍을 사용하려면 `true`로 설정합니다 |
| `stream_options.include_usage` | 최종 스트리밍 사용량을 받으려면 `true`으로 설정합니다 |
| `tools` | 애플리케이션에서 실행할 함수를 정의합니다 |
| `prompt_cache_options` | 암시적 컨텍스트 캐싱과 캐시 유지 시간을 구성합니다 |

> [!WARNING]
>
> 추론과 답변을 위한 `max_completion_tokens`을 충분히 확보하십시오. 추론 중 예산을 모두 사용하면 최종 답변이 비어 있거나 불완전할 수 있습니다. `finish_reason`을 확인하고 필요한 경우 예산을 늘리십시오.

공식 샘플링 값은 `temperature=1`, `top_p=0.95`, `n=1`, `presence_penalty=0`, `frequency_penalty=0`로 고정되어 있습니다. 채팅 완성 예시에서는 이 값들을 생략합니다. 메시지에서는 위에 설명된 대로 샘플링 매개변수를 명시적으로 설정하십시오. 다른 모델에서 호환되지 않는 설정을 그대로 가져오지 마십시오.

### 응답 읽기

최종 답변은 `choices[0].message.content`에 있습니다. 추론은 `choices[0].message.reasoning_content`에 반환됩니다. 답변은 `content`에서 확인하고, 인터페이스에 표시되는 경우 `reasoning_content`은 별도로 처리하십시오.

추론 token에는 출력 요율이 적용됩니다. 눈에 보이는 답변 길이가 아니라 응답 `usage`과 콘솔 로그를 바탕으로 비용을 추정하십시오.

## 스트리밍

추론 및 답변 텍스트는 각각 `delta.reasoning_content` 및 `delta.content`에 도착합니다. 최종 사용량 청크의 `choices` 배열이 비어 있을 수 있으므로, 선택 항목을 읽기 전에 `chunk.usage`을 확인합니다.

```python theme={null}
stream = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "user", "content": "Design a task queue with retry handling."}],
    reasoning_effort="low",
    max_completion_tokens=8192,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.usage is not None:
        print("\nUsage:", chunk.usage)
    if not chunk.choices:
        continue

    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        # Render reasoning separately from the final answer.
        pass
    if delta.content:
        print(delta.content, end="", flush=True)
```

## 도구 호출

모델은 함수 이름과 인수를 생성하고, 애플리케이션은 이를 실행합니다. 모델이 `tool_calls`을 반환하면 `reasoning_content` 및 `tool_calls`를 포함한 **전체 assistant 메시지**를 기록에 추가합니다. 그런 다음 일치하는 `tool_call_id`와 함께 각 도구 결과를 추가하고 다음 요청을 보냅니다.

```python theme={null}
import json

messages = [{"role": "user", "content": "Check the delivery status of order A100."}]
tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Get the delivery status of an order",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
            "additionalProperties": False,
        },
    },
}]

response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=messages,
    tools=tools,
    reasoning_effort="low",
    max_completion_tokens=8192,
)
message = response.choices[0].message
messages.append(message.model_dump(exclude_none=True))

if message.tool_calls:
    for call in message.tool_calls:
        arguments = json.loads(call.function.arguments)
        # Example result; validate arguments and query your order service in production.
        result = {"order_id": arguments["order_id"], "status": "shipped"}
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

    final = client.chat.completions.create(
        model="kimi-k3.1-pro",
        messages=messages,
        tools=tools,
        reasoning_effort="low",
        max_completion_tokens=8192,
    )
    print(final.choices[0].message.content)
else:
    print(message.content)
```

> [!WARNING]
>
> 도구 호출 라운드에서는 전체 assistant 메시지를 보존합니다. `reasoning_content` 또는 `tool_calls`를 누락하면 후속 추론이나 도구 결과 일치에 문제가 생길 수 있습니다. 요청된 작업을 실행하기 전에 도구 이름, 인수 및 실행 권한을 확인합니다.

## 컨텍스트 캐싱

공식 캐싱 메커니즘은 반복해서 사용하는 긴 시스템 지침, 참고 문서, 코드 컨텍스트를 위한 것입니다. 안정적인 콘텐츠를 먼저 배치하고 변경되는 질문은 마지막에 둡니다.

> [!WARNING]
>
> **1시간 캐싱은 이번 테스트 실행에서 통과하지 못했으며, APIYI에서 지원된다고 검증되지 않았습니다.** 두 모델 모두 5분 및 1시간 정책에 대해 서로 다른 긴 접두사를 사용해 테스트했습니다. 요청은 성공했지만 유효한 캐시 읽기 또는 캐시 쓰기 횟수는 반환되지 않았습니다. 약 5.5분 후에 반복한 네 건의 요청과 이후 짧은 간격으로 반복한 요청 모두 캐시 적중을 보이지 않았습니다. 1시간 요청 로그에는 1시간 캐시 쓰기 과금이 아닌 일반 입력 과금이 표시되었습니다.

이 결과는 이번 테스트 실행에 대한 설명이며, 모든 요청에서 캐싱이 지원되지 않는다는 점을 입증하지는 않습니다. 자체 요청에서 캐시 사용 및 이에 부합하는 과금이 확인될 때까지 일반 입력 과금을 예산에 반영하십시오. 아래 매개변수와 동작은 공식 형식을 참조한 것입니다.

### 캐시 수명 선택

채팅 완료 API에서는 **최상위 요청 필드** `prompt_cache_options`를 사용합니다. 기본 수명은 5분입니다. 1시간 수명을 요청하려면 다음과 같이 설정합니다.

```python theme={null}
response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[
        {"role": "system", "content": LONG_STABLE_CONTEXT},
        {"role": "user", "content": "List three key findings from the reference material."},
    ],
    reasoning_effort="low",
    max_completion_tokens=8192,
    extra_body={
        "prompt_cache_options": {"mode": "implicit", "ttl": "1h"}
    },
)
print(response.usage)
```

`LONG_STABLE_CONTEXT`는 재사용하려는 긴 텍스트를 나타냅니다. 이후 요청에서도 해당 접두사를 동일하게 유지하고 마지막 질문을 바꾸십시오.

> [!NOTE]
>
> **최초 캐시 쓰기가 캐시 수명을 결정합니다.** 기존 5분 캐시에 `ttl: "1h"`를 보내도 수명이 1시간으로 늘어나지 않습니다. 캐시 적중이 발생하면 기존 수명이 갱신됩니다. 정책을 비교할 때는 각 정책에 서로 다른 새 접두사를 사용하십시오.

### 읽기 및 쓰기 과금 방식

* **캐시 읽기:** 재사용된 접두사 token에는 캐시 읽기 요율이 적용됩니다.
* **캐시 쓰기:** 새로 캐시된 접두사 token에는 선택한 5분 또는 1시간 쓰기 요율이 적용됩니다.
* **일반 입력:** 캐시된 부분을 제외한 입력에는 일반 입력 요율이 적용됩니다.
* **출력:** 추론 및 최종 답변에는 출력 요율이 적용됩니다.

이는 공식 과금 항목입니다. 이번 테스트 실행에서는 일반 입력 및 출력 과금은 확인했지만, 캐시 읽기 또는 캐시 쓰기 정산은 확인하지 못했습니다. 응답 `usage`, 캐시 읽기 및 캐시 생성 필드, 콘솔 과금 로그를 비교하십시오. 매개변수가 수락되었다는 사실만으로는 충분하지 않습니다.

## 기술 사양 및 통합 팁

| 항목 | 세부 정보 |
| - | - |
| 모델 ID | `kimi-k3.1-pro`, `kimi-k3.1-pro-highspeed` |
| 공식 컨텍스트 윈도우 | 1,048,576 tokens |
| 이 가이드의 주요 엔드포인트 | `POST https://api.apiyi.com/v1/chat/completions` |
| 추론 | 항상 활성화되어 있습니다. `reasoning_effort`을 사용해 `low`, `high` 또는 `max`를 선택합니다. |
| 최종 답변 필드 | `choices[0].message.content` |
| 추론 필드 | `choices[0].message.reasoning_content` |
| 공식 캐시 옵션 | 기본값은 5분이며, 1시간을 요청할 수 있습니다. 위의 검증 제한을 참조하세요. |

**1. 낮은 추론 수준으로 시작하기**

긴 컨텍스트를 추가하기 전에 짧은 요청을 보내 모델 이름, 토큰, 응답 파서를 검증합니다.

**2. 추론 예산 설정하기**

사용량과 `finish_reason`에 따라 `max_completion_tokens`을 조정합니다. 더 복잡한 작업에는 `reasoning_effort`을 늘립니다.

**3. 오래 실행되는 작업 스트리밍하기**

추론 텍스트와 답변 텍스트를 별도로 처리하고, 최종 사용량을 확인하며, 클라이언트와 프록시에 충분한 타임아웃을 설정합니다.

**4. 확장하기 전에 캐시 사용량 확인하기**

고정된 긴 접두사를 사용해 요청을 반복한 다음, 캐시 사용량과 과금 로그를 비교하여 워크플로에서 캐시 적중이 발생하는지 확인합니다.

## FAQ

> **Highspeed를 선택하면 무엇이 달라집니까?**
>
> 두 모델은 동일한 통합 형식을 사용합니다. Highspeed는 token 가격이 더 높은 대신 지연 시간을 줄이는 데 중점을 둡니다. 실제 속도는 prompt 길이, 추론 노력, 출력 길이, 현재 부하에 따라 달라지므로 실제 워크로드로 평가하시기 바랍니다.

> **Kimi K2.5에서처럼 추론을 비활성화할 수 있습니까?**
>
> K3.1 Pro 모델은 항상 추론을 사용합니다. 기존 `enable_thinking` 매개변수를 그대로 사용하는 대신 `reasoning_effort: "low"`을 선택해 오버헤드를 제어하시기 바랍니다.

> **청구되는 출력량이 화면에 표시되는 답변보다 많은 이유는 무엇입니까?**
>
> 출력 사용량에는 추론 tokens가 포함됩니다. 화면에 표시되는 답변 길이는 총 출력 사용량을 나타내지 않습니다. 응답 `usage` 및 콘솔 로그를 확인하시기 바랍니다.

> **ttl을 1h로 설정하면 기존 캐시의 유효 기간을 1시간으로 변경할 수 있습니까?**
>
> 공식 메커니즘에서는 기존 캐시가 처음 설정된 유효 기간을 유지하므로 `ttl: "1h"`하려면 새 접두사가 필요합니다. APIYI의 테스트에서는 1시간 유지 또는 쓰기 요금이 확인되지 않았습니다. 매개변수가 성공적으로 수락되었다고 해서 지원이 입증된 것은 아닙니다.

> **20% 충전 보너스는 비용에 어떤 영향을 줍니까?**
>
> 조건을 충족하는 충전으로 결제 금액의 1.2배에 해당하는 크레딧을 제공하므로 실효 비용은 정가의 `1 ÷ 1.2 ≈ 83.33%`입니다. 적용 대상은 [프로모션 약관](https://docs.apiyi.com/ko/faq/recharge-promotions.md)을 확인하시기 바랍니다.

## 관련 문서

* [API 매뉴얼](https://docs.apiyi.com/ko/api-manual.md)
* [함수 호출](https://docs.apiyi.com/ko/api-capabilities/openai/function-calling.md)
* [추론 모델 응답](https://docs.apiyi.com/ko/api-capabilities/openai/reasoning-models.md)
* [모델 가격](https://docs.apiyi.com/en/models/index.md)
* [충전 보너스](https://docs.apiyi.com/ko/faq/recharge-promotions.md)

공식 참조: `platform.moonshot.ai/docs/guide/kimi-k3-1-pro-quickstart`, `platform.kimi.ai/docs/guide/context-caching`, `platform.moonshot.ai/docs/pricing/chat`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.