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

> Official-relay access to Kimi K3.1 Pro and Highspeed: model selection, OpenAI-compatible requests, reasoning effort, streaming, tool calls, and cache parameters with test limits.

## Overview

**Kimi K3.1 Pro** is Moonshot AI's reasoning model for software development, complex reasoning, and multi-step tool workflows. APIYI provides the official-relay models `kimi-k3.1-pro` and `kimi-k3.1-pro-highspeed`. Both use the same request format; switch between them by changing `model`.

> [!NOTE]
>
> **Start with Pro, then choose Highspeed if your workflow needs lower latency.** Both models always use reasoning, with `reasoning_effort` controlling its depth. Highspeed has higher input, output, and cache-write prices.

> [!WARNING]
>
> **One-hour caching did not pass this test run and is not listed as a verified capability.** Basic chat, streaming, and tool calls passed. See the caching section for official parameters and test limits.

> **[Quick Start](#quick-start)**
>
> Call Chat Completions with the OpenAI SDK or HTTP.

> **[Models and Pricing](#model-selection-and-pricing)**
>
> Compare Pro and Highspeed, including cache charges.

> **[Reasoning and Tools](#tool-calls)**
>
> Select reasoning effort and preserve tool-call history.

> **[Context Caching](#context-caching)**
>
> Review official cache parameters and the limits of APIYI's tests.

## Model Selection and Pricing

Both models are billed by actual token usage, and **APIYI's current configured rates match official prices**. All rates below are in **USD per 1M tokens**. Regular-input and output charges were checked; cache rates are configured prices, not cache charges verified by this test run:

| Billing category | `kimi-k3.1-pro` | `kimi-k3.1-pro-highspeed` |
| - | - | - |
| Regular input | \$2.00 | \$4.00 |
| Output, including reasoning | \$10.00 | \$20.00 |
| Cache read, configured rate | \$0.20 | \$0.20 |
| Cache write: 5 minutes, configured rate | \$2.00 | \$4.00 |
| Cache write: 1 hour, configured rate | \$4.00 | \$8.00 |

> [!NOTE]
>
> Model prices align with the official provider and may change. This table is a reference; the **Model Pricing** tab in the top navigation is authoritative: [Model Pricing](https://docs.apiyi.com/en/models/index.md).

| Model | Suggested use | Selection guide |
| - | - | - |
| `kimi-k3.1-pro` | Development, reasoning, document processing, and batch tool tasks | The default when cost matters most |
| `kimi-k3.1-pro-highspeed` | Interactive agents and workflows that need faster responses | Higher token prices in exchange for lower latency |

### Effective Cost with Top-up Bonuses

For top-ups that qualify for the [20% bonus promotion](https://docs.apiyi.com/en/faq/recharge-promotions.md), each unit paid provides 1.2 units of usable credit. Effective cost is therefore `1 ÷ 1.2 ≈ 83.33%` of the listed price.

The bonus increases available credit; listed model prices stay the same. Check the promotion page for eligibility, bonus rates, and current terms.

## Basic Capability Tests

APIYI verified the following basic cases for both models on **2026-10-25 (UTC+8)**:

| Capability | `kimi-k3.1-pro` | `kimi-k3.1-pro-highspeed` |
| - | - | - |
| Non-streaming text chat | Passed | Passed |
| Streaming text output | Passed | Passed |
| JSON object output | Passed | Passed |
| Function calls and tool-result round trip | Passed | Passed |
| Image understanding | Passed | Passed |
| Basic Responses request | Passed | Passed |
| Basic Messages request | Passed with explicit sampling parameters | Passed with explicit sampling parameters |
| Regular-input and output billing logs | Matched listed rates | Matched listed rates |

This guide primarily uses Chat Completions. Existing Responses integrations can also use `POST /v1/responses`. The image test used Base64 data.

Basic requests to `POST /v1/messages` also passed. Explicitly set `top_p: 0.95` and `temperature: 1` to avoid errors from default sampling-parameter conversion.

> [!NOTE]
>
> These tests checked basic requests, semantic results, and regular-input and output charges. They do not cover every parameter, maximum context, or long-running behavior. Cache lifetime and billing require separate checks, as described below.

## Quick Start

Use an APIYI Token to call `POST /v1/chat/completions`. Start with `reasoning_effort: "low"`, then increase it for tasks that require deeper reasoning.

```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]
>
> Keep the model name in configuration. To use Highspeed, change it to `kimi-k3.1-pro-highspeed` and reuse the rest of your integration.

## Reasoning and Key Parameters

Both models **always use reasoning**. Control depth with `reasoning_effort`; do not carry over the Kimi K2.5 `enable_thinking` switch.

| Parameter | Usage |
| - | - |
| `reasoning_effort` | `low`, `high`, or `max`; the official default is `max` |
| `max_completion_tokens` | Output budget for reasoning and the final answer combined |
| `stream` | Set to `true` for streaming |
| `stream_options.include_usage` | Set to `true` to receive final streaming usage |
| `tools` | Define functions that your application executes |
| `prompt_cache_options` | Configure implicit context caching and its lifetime |

> [!WARNING]
>
> Allow enough `max_completion_tokens` for reasoning and the answer. If reasoning exhausts the budget, the final answer may be empty or incomplete. Check `finish_reason` and increase the budget when needed.

The official sampling values are fixed at `temperature=1`, `top_p=0.95`, `n=1`, `presence_penalty=0`, and `frequency_penalty=0`. The Chat Completions examples omit them; for Messages, explicitly set the sampling parameters as described above. Avoid carrying incompatible settings over from another model.

### Reading the Response

The final answer is in `choices[0].message.content`. Reasoning is returned in `choices[0].message.reasoning_content`. Read `content` for the answer, and handle `reasoning_content` separately if your interface displays it.

Reasoning tokens are billed at the output rate. Estimate cost from response `usage` and console logs rather than visible answer length.

## Streaming

Reasoning and answer text arrive in `delta.reasoning_content` and `delta.content`, respectively. A final usage chunk may have an empty `choices` array, so check `chunk.usage` before reading choices.

```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

The model generates function names and arguments; your application executes them. When the model returns `tool_calls`, append the **complete assistant message**, including `reasoning_content` and `tool_calls`, to history. Then append each tool result with its matching `tool_call_id` and send the next request.

```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]
>
> Preserve the full assistant message in tool-call rounds. Dropping `reasoning_content` or `tool_calls` can disrupt subsequent reasoning or tool-result matching. Validate tool names, arguments, and execution permissions before running a requested operation.

## Context Caching

The official caching mechanism is intended for repeated long system instructions, reference documents, and code context. Put stable content first and changing questions last.

> [!WARNING]
>
> **One-hour caching did not pass this test run and is not a verified APIYI capability.** Both models were tested with separate long prefixes for 5-minute and 1-hour policies. Requests succeeded but returned no effective cache-read or cache-write counts. Neither the four requests repeated after approximately 5.5 minutes nor subsequent short-interval repetitions showed cache hits. Logs for the 1-hour requests showed regular-input charges rather than 1-hour cache-write charges.

These results describe this test run; they do not establish that caching is unsupported for every request. Budget for regular-input charges until your own requests show cache usage and matching billing. The parameters and behavior below are references to the official format.

### Choosing a Cache Lifetime

Chat Completions uses the **top-level request field** `prompt_cache_options`. The default lifetime is 5 minutes. To request a 1-hour lifetime:

```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` represents the long text you want to reuse. Keep that prefix identical in later requests and replace the final question.

> [!NOTE]
>
> **The first cache write determines its lifetime.** Sending `ttl: "1h"` for an existing 5-minute cache does not upgrade it. A hit refreshes the original lifetime. Compare policies using a different fresh prefix for each one.

### How Reads and Writes Are Billed

* **Cache read:** reused prefix tokens are charged at the cache-read rate.
* **Cache write:** new cached prefix tokens are charged at the chosen 5-minute or 1-hour write rate.
* **Regular input:** input outside the cached portion is charged at the regular input rate.
* **Output:** reasoning and the final answer are charged at the output rate.

These are the official billing categories. This test run verified regular-input and output charges, but did not verify cache-read or cache-write settlement. Compare response `usage`, cache-read and cache-creation fields, and console billing logs; parameter acceptance alone is insufficient.

## Technical Specifications and Integration Tips

| Item | Details |
| - | - |
| Model IDs | `kimi-k3.1-pro`, `kimi-k3.1-pro-highspeed` |
| Official context window | 1,048,576 tokens |
| Main endpoint in this guide | `POST https://api.apiyi.com/v1/chat/completions` |
| Reasoning | Always enabled; select `low`, `high`, or `max` with `reasoning_effort` |
| Final answer field | `choices[0].message.content` |
| Reasoning field | `choices[0].message.reasoning_content` |
| Official cache options | 5 minutes by default; 1 hour can be requested; see the verification limits above |

**1. Start with low reasoning effort**

Send a short request to validate the model name, Token, and response parser before adding long context.

**2. Budget for reasoning**

Adjust `max_completion_tokens` based on usage and `finish_reason`. Increase `reasoning_effort` for more complex tasks.

**3. Stream long-running tasks**

Handle reasoning and answer text separately, read final usage, and allow sufficient timeouts in clients and proxies.

**4. Verify cache usage before scaling**

Repeat requests with a fixed long prefix, then compare cache usage and billing logs to confirm hits in your workflow.

## FAQ

> **What changes when I select Highspeed?**
>
> Both models use the same integration format. Highspeed targets lower latency at higher token prices. Actual speed depends on prompt length, reasoning effort, output length, and current load; evaluate it with your own workload.

> **Can I disable reasoning as I could with Kimi K2.5?**
>
> K3.1 Pro models always use reasoning. Select `reasoning_effort: "low"` to control overhead rather than carrying over the old `enable_thinking` parameter.

> **Why is billed output larger than the visible answer?**
>
> Output usage includes reasoning tokens. Visible answer length does not represent total output usage; check response `usage` and console logs.

> **Can I change an existing cache to one hour by setting ttl to 1h?**
>
> Under the official mechanism, an existing cache keeps its initial lifetime, so `ttl: "1h"` requires a fresh prefix. APIYI's tests did not verify 1-hour retention or write charges; successful parameter acceptance is not proof of support.

> **How does a 20% top-up bonus affect cost?**
>
> A qualifying top-up provides 1.2 times the paid amount in credit, making effective cost `1 ÷ 1.2 ≈ 83.33%` of list price. See the [promotion terms](https://docs.apiyi.com/en/faq/recharge-promotions.md) for eligibility.

## Related Docs

* [API Manual](https://docs.apiyi.com/en/api-manual.md)
* [Function Calling](https://docs.apiyi.com/en/api-capabilities/openai/function-calling.md)
* [Reasoning Model Responses](https://docs.apiyi.com/en/api-capabilities/openai/reasoning-models.md)
* [Model Pricing](https://docs.apiyi.com/en/models/index.md)
* [Top-up Bonuses](https://docs.apiyi.com/en/faq/recharge-promotions.md)

Official references: `platform.moonshot.ai/docs/guide/kimi-k3-1-pro-quickstart`, `platform.kimi.ai/docs/guide/context-caching`, and `platform.moonshot.ai/docs/pricing/chat`.


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