> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Guia prático do Kimi K3: parâmetros e suporte das três APIs
> Guia de julho de 2026 do Kimi K3: reasoning_effort max, ferramentas dinâmicas, saída estruturada, cache automático e exemplos nas três APIs da AIHubMix.
> Este artigo apresenta os novos parâmetros do [Kimi K3](https://aihubmix.com/model/kimi-k3) e os pontos de atenção na chamada. Na AIHubMix, o K3 pode ser chamado pelas APIs Chat Completions, Responses e Messages (compatível com Claude). Leitura complementar: [documentação oficial da plataforma Moonshot](https://platform.moonshot.ai/docs).
>
> As conclusões marcadas como "Verificado" e os retornos de exemplo de cada seção provêm de chamadas reais feitas em 2026-07-17 pelas APIs da AIHubMix (Chat Completions / Responses / Messages).
## 1. Visão geral das especificações do modelo
| Item | Valor |
| :--------------------- | :----------------------------------------------------------------------------- |
| Janela de contexto | 1M tokens |
| Saída máxima | `max_completion_tokens` padrão 131.072, máximo 1.048.576 |
| Modalidades de entrada | Texto, imagem (para entrada de vídeo, veja a documentação oficial da Moonshot) |
| Modo de raciocínio | Ativado por padrão; `reasoning_effort` só aceita `"max"` |
| Sequências de parada | `stop` aceita no máximo 5 entradas, cada uma com até 32 bytes |
> **Verificado**: os dois limites de `stop` são validados e o excesso retorna 400; o `stop_sequences` da API Messages aplica a mesma validação.
>
> ❗ **Ao acionar uma sequência de parada, a API Messages não responde conforme a semântica da Anthropic**: nos testes, `stop_reason` retornou `"end_turn"` (em vez de `"stop_sequence"`), `stop_sequence` retornou `null`, e o texto visível anterior à sequência de parada pode vir vazio. Clientes que dependem desses dois campos para identificar o motivo do truncamento devem ficar atentos.
```text theme={null}
# stop with 6 entries / a 33-byte entry -> HTTP 400
"Invalid request: stop array too long. Expected an array with maximum length 5, but got an array with length 6 instead"
"Invalid request: stop sequence must not be longer than 32, but got 33 instead"
```
## 2. Modo de raciocínio: `reasoning_effort` só aceita o nível `max`
O raciocínio do K3 vem ativado por padrão, e `reasoning_effort` só aceita o nível `"max"`.
**Em conversas multi-turno, o histórico de raciocínio deve ser devolvido sem alterações**: segundo a orientação oficial da Moonshot, o K3 foi treinado com preserved thinking; em conversas multi-turno é necessário devolver a mensagem assistant do turno anterior **completa e sem alterações** (incluindo o conteúdo de raciocínio). A ausência do histórico de raciocínio causa instabilidade na qualidade da saída. Ao usar frameworks de gerenciamento de sessão ou camadas de proxy, confirme que o conteúdo de raciocínio não é cortado antes do reenvio.
O conteúdo de raciocínio é retornado no campo `reasoning_content` da resposta; em multi-turno, devolva a mensagem assistant do turno anterior (incluindo `reasoning_content`) sem alterações.
```text theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://aihubmix.com/v1",
api_key="",
)
completion = client.chat.completions.create(
model="kimi-k3",
reasoning_effort="max",
messages=[
{"role": "user", "content": "A snail is at the bottom of a 10-meter well. Each day it climbs 3 meters, but each night it slides back 2 meters. How many days does it take to reach the top?"}
],
)
print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)
```
```text theme={null}
# Multi-turn: pass the previous assistant message back verbatim
messages = [
{"role": "user", "content": "What is the capital of France?"},
{"role": "assistant", "content": "Paris.", "reasoning_content": ""},
{"role": "user", "content": "And its population?"},
]
```
> **Verificado**: a resposta retorna `reasoning_content`; depois de devolver a mensagem assistant do turno anterior (incluindo `reasoning_content`) sem alterações, os turnos seguintes respondem normalmente.
O conteúdo de raciocínio é retornado como item de saída `reasoning`; em multi-turno, reinsira os itens de saída do turno anterior (`reasoning` + `message`) sem alterações no `input`.
```text theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://aihubmix.com/v1",
api_key="",
)
response = client.responses.create(
model="kimi-k3",
input="Answer in one word: capital of France",
)
# Observed response.output item types: ["reasoning", "message"]; text: "Paris"
# Multi-turn: input = [first user message] + response.output + [next user message]
# Observed second-turn answer with output items passed back: "Berlin"
```
O conteúdo de raciocínio é retornado como bloco de conteúdo nativo `thinking`; em multi-turno, devolva os blocos de conteúdo da mensagem assistant do turno anterior (incluindo os blocos thinking) sem alterações.
```text theme={null}
from anthropic import Anthropic
client = Anthropic(
api_key="",
base_url="https://aihubmix.com"
)
response = client.messages.create(
model="kimi-k3",
max_tokens=4096,
messages=[
{"role": "user", "content": "Answer in one word: capital of France"}
],
)
# Observed response.content block types: ["thinking", "text"]; text: "Paris"
# Multi-turn: pass response.content back verbatim as the assistant message
```
## 3. Parâmetros de amostragem com valores fixos
Os parâmetros de amostragem do K3 têm valores fixos definidos oficialmente: `temperature` 1.0, `top_p` 0.95, `n` 1, `presence_penalty` / `frequency_penalty` 0. A recomendação oficial é não enviar esses parâmetros na requisição.
> **Observação**: os valores fixos de amostragem são especificação oficial e não podem ser verificados por sinais da resposta; siga a recomendação oficial e omita esses parâmetros.
## 4. Chamada de ferramentas e carregamento dinâmico de ferramentas
`tools` aceita no máximo 128 ferramentas; `tool_choice` permite forçar ou desativar chamadas. O K3 também suporta carregamento dinâmico de ferramentas: no meio da conversa, novas ferramentas podem ser injetadas pelo campo `tools` de uma mensagem system (formato de mensagem exclusivo da API Chat).
`tool_choice` aceita `auto` / `none` / `required`; `required` força o modelo a chamar uma ferramenta. Carregamento dinâmico de ferramentas: a mensagem system que injeta ferramentas não leva `content`, as ferramentas injetadas valem para os turnos seguintes, e cada requisição precisa repetir a injeção.
```text theme={null}
messages = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello."},
{"role": "assistant", "content": "Hi, how can I help you?"},
# Inject a new tool mid-conversation: tools field only, no content
{
"role": "system",
"tools": [
{
"type": "function",
"function": {
"name": "get_time",
"description": "Get the current time",
"parameters": {"type": "object", "properties": {}},
},
}
],
},
{"role": "user", "content": "What time is it now?"},
]
```
```text theme={null}
# tool_choice="required" with prompt "Hello" -> the model is forced to call the tool
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]
```
> **Verificado**: `tool_choice: "required"` força uma chamada de ferramenta mesmo em perguntas sem relação; `"none"` suprime chamadas de ferramenta; ferramentas injetadas no meio da conversa por mensagem system sem `content` podem ser chamadas normalmente.
A definição de ferramenta usa estrutura plana (`name` no nível superior); a chamada forçada também usa `tool_choice: "required"`, e a chamada é retornada como item de saída `function_call`. O suporte ao carregamento dinâmico de ferramentas está em andamento; por ora, declare todas as ferramentas no parâmetro `tools` de nível superior.
```text theme={null}
response = client.responses.create(
model="kimi-k3",
input="Hello",
tools=[{
"type": "function",
"name": "get_weather",
"description": "Get weather for a city",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}],
tool_choice="required",
)
# Observed output contains: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}
```
As ferramentas usam o formato Anthropic (`input_schema`); a chamada forçada é `tool_choice: {"type": "any"}` e a desativação é `{"type": "none"}`. ❗ **O endpoint oficial Messages (compatível com Anthropic) do Kimi K3 não suporta carregamento dinâmico de ferramentas**: nos testes, a injeção da mensagem retorna 200, mas a ferramenta injetada não tem efeito (o modelo não consegue chamá-la); declare todas as ferramentas no parâmetro `tools` de nível superior.
```text theme={null}
response = client.messages.create(
model="kimi-k3",
max_tokens=4096,
tools=[{
"name": "get_weather",
"description": "Get weather for a city",
"input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}],
tool_choice={"type": "any"},
messages=[{"role": "user", "content": "Hello"}],
)
# Observed: stop_reason "tool_use"; content contains a tool_use block calling get_weather
```
## 5. Saída estruturada
A saída estruturada faz o modelo retornar conteúdo em estrita conformidade com um JSON Schema fornecido.
`response_format` suporta `json_schema` e o modo `strict`.
```text theme={null}
completion = client.chat.completions.create(
model="kimi-k3",
messages=[
{"role": "user", "content": "Paris is the capital of France. Extract the city name."}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "extract",
"strict": True,
"schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
},
)
# Observed response content: {"city":"Paris"}
```
> **Verificado**: a saída é JSON válido em conformidade com o schema.
A saída estruturada é declarada por `text.format`.
```text theme={null}
response = client.responses.create(
model="kimi-k3",
input="Paris is the capital of France. Extract the city name.",
text={
"format": {
"type": "json_schema",
"name": "extract",
"strict": True,
"schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
}
},
)
# Observed output text: {"city":"Paris"}
```
❗ **O endpoint oficial Messages (compatível com Anthropic) do Kimi K3 não suporta saída estruturada**: os campos de saída estruturada são ignorados silenciosamente — a requisição retorna HTTP 200 com texto livre, sem qualquer erro ou aviso de degradação, e o parse de JSON no cliente falhará. Quando precisar de saída estruturada, use as APIs Chat Completions ou Responses.
## 6. Cache de contexto ativado automaticamente
O cache de contexto do K3 é ativado automaticamente, sem necessidade de qualquer parâmetro. Quando um prefixo longo repetido acerta o cache, a quantidade de acertos é reportada no usage (o nome do campo varia conforme a API). Os preços de cache estão na [página do modelo](https://aihubmix.com/model/kimi-k3).
```text theme={null}
# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 1536}
```
> **Verificado**: a segunda requisição com o mesmo prefixo longo reporta os acertos em `usage.prompt_tokens_details.cached_tokens`.
```text theme={null}
# usage of the second Responses call with identical long instructions
"input_tokens_details": {"cached_tokens": 1536}
```
```text theme={null}
# usage of the second Messages call with an identical long system prompt
"cache_read_input_tokens": 1536
```
## 7. Continuação de prefixo com `partial`
A continuação de prefixo faz o modelo continuar a geração a partir de um prefixo fornecido, útil para completar código e produzir saída em formato controlado.
Envie `"partial": true` na última mensagem assistant.
```text theme={null}
messages = [
{"role": "user", "content": "Write a haiku about the sea."},
{"role": "assistant", "content": "Waves fold into foam,", "partial": True},
]
# Prefix: "Waves fold into foam," -> continuation returned by the model
# salt hangs in the air—
# moon pulls the tide home.
```
> **Verificado**: a geração continua a partir do prefixo fornecido, sem repeti-lo.
Envie o prefixo como mensagem assistant no final do array `input`, sem o parâmetro `partial`.
```text theme={null}
response = client.responses.create(
model="kimi-k3",
input=[
{"role": "user", "content": "Write a haiku about the sea."},
{"role": "assistant", "content": "Waves fold into foam,"},
],
)
# Observed continuation: "salt hangs in the air— / moon pulls the tide home."
```
A mesma capacidade é obtida com o pré-preenchimento de assistant nativo do protocolo, sem o parâmetro `partial` — basta enviar o prefixo como última mensagem assistant.
```text theme={null}
response = client.messages.create(
model="kimi-k3",
max_tokens=4096,
messages=[
{"role": "user", "content": "Write a haiku about the sea."},
{"role": "assistant", "content": "Waves fold into foam,"},
],
)
# Observed continuation: "salt wind carries the gull's cry— / tide pulls ..."
```
## 8. Entrada visual
As imagens são enviadas em base64; a forma do bloco de conteúdo varia conforme a API.
```text theme={null}
messages = [
{
"role": "user",
"content": [
{"type": "text", "text": "What is the dominant color of this image? One word."},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,"}},
],
}
]
# Observed response content: "Red" (input: a 64x64 solid red PNG)
```
> **Verificado**: a entrada de imagem em base64 funciona; o modelo descreveu corretamente o conteúdo da imagem de teste.
```text theme={null}
input = [
{
"role": "user",
"content": [
{"type": "input_text", "text": "What is the dominant color of this image? One word."},
{"type": "input_image", "image_url": "data:image/png;base64,"},
],
}
]
# Observed output text: "Red"
```
```text theme={null}
messages = [
{
"role": "user",
"content": [
{"type": "text", "text": "What is the dominant color of this image? One word."},
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": ""}},
],
}
]
# Observed response text: "Red"
```
## 9. Referência verificada: tempo e uso de uma chamada única em tarefa longa
O raciocínio do K3 é fixado no nível max, e o tempo de uma requisição única em tarefas complexas é significativamente maior do que em modelos convencionais. Dados verificados de uma tarefa de geração de jogo HTML em arquivo único (um único prompt com imagem de referência, geração única, sem iteração): a requisição levou 2.541 segundos (cerca de 42 minutos), com 74.994 completion tokens, dos quais 54.486 (73%) foram de raciocínio; o resultado final, produzido de uma vez, foi um código de 1.275 linhas executável diretamente, com `finish_reason` igual a `stop`.
Recomendações do lado do cliente:
* Configure timeouts de cliente na escala de minutos ou mais; em tarefas longas, priorize o retorno em streaming;
* Dê folga suficiente a `max_completion_tokens` — neste exemplo, só o raciocínio consumiu 54.486 tokens.
## 10. Matriz de suporte capacidade × API
Cada célula da tabela abaixo reflete o resultado de chamadas reais verificadas em 2026-07-17 pelas APIs de produção da AIHubMix; o conteúdo da célula indica a forma do parâmetro / campo na API correspondente.
| Capacidade | Chat Completions | Responses | Messages |
| :---------------------------------------- | :-------------------------------------------- | :------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| Retorno do conteúdo de raciocínio | ✅ campo `reasoning_content` | ✅ item de saída `reasoning` | ✅ bloco de conteúdo `thinking` |
| Reenvio do histórico de raciocínio | ✅ mensagem assistant devolvida sem alterações | ✅ itens de saída devolvidos sem alterações | ✅ blocos de conteúdo devolvidos sem alterações |
| Forçar / desativar chamada de ferramentas | ✅ `tool_choice: "required"` / `"none"` | ✅ `tool_choice: "required"` | ✅ `{"type": "any"}` / `{"type": "none"}` |
| Carregamento dinâmico de ferramentas | ✅ mensagem system com `tools` (sem `content`) | ➖ Em andamento | ❗ Endpoint oficial Messages (compatível com Anthropic) não suporta |
| Saída estruturada | ✅ `response_format` (json\_schema + strict) | ✅ `text.format` (json\_schema) | ❗ Endpoint oficial não suporta; campos **ignorados silenciosamente** (200 + texto livre); use Chat / Responses |
| Medição de acertos do cache automático | ✅ `usage.prompt_tokens_details.cached_tokens` | ✅ `usage.input_tokens_details.cached_tokens` | ✅ `usage.cache_read_input_tokens` |
| Continuação de prefixo | ✅ `"partial": true` | ✅ pré-preenchimento de assistant | ✅ pré-preenchimento de assistant (nativo do protocolo) |
| Entrada visual | ✅ `image_url` (base64) | ✅ `input_image` (base64) | ✅ bloco de conteúdo `image` (base64) |
| Sequências de parada | ✅ `stop` (limites validados) | ➖ Em andamento | ❗ `stop_sequences` valida os mesmos limites, mas ao acionar não retorna `stop_reason: "stop_sequence"` / valor de `stop_sequence` |
## Perguntas frequentes (FAQ)
**Quais APIs o K3 suporta na AIHubMix?**
Chat Completions (`/v1/chat/completions`), Responses (`/v1/responses`) e Messages compatível com Claude (`/v1/messages`).
**É possível desativar o raciocínio ou reduzir sua intensidade?**
Não. O raciocínio do K3 vem ativado por padrão, e `reasoning_effort` só aceita o nível `"max"`.
**Por que conversas multi-turno precisam devolver `reasoning_content`?**
O K3 foi treinado com preserved thinking; a orientação oficial é devolver a mensagem assistant do turno anterior completa e sem alterações. A ausência do histórico de raciocínio causa instabilidade na qualidade da saída.
**Quais são os limites do parâmetro `stop`?**
No máximo 5 sequências de parada, cada uma com até 32 bytes; o excesso retorna erro 400.
**A API Messages suporta saída estruturada?**
❗ Não. O endpoint oficial Messages (compatível com Anthropic) do Kimi K3 ignora silenciosamente os campos de saída estruturada (retorna 200 com texto livre, sem erro). Para saída estruturada, use `response_format` em Chat Completions ou `text.format` em Responses.
**Por que uma requisição única do K3 demora tanto?**
O raciocínio do K3 é fixado no nível max, e em tarefas complexas a proporção de tokens de raciocínio é alta (73% dos completion tokens no caso verificado). Recomenda-se configurar o timeout do cliente na escala de minutos ou mais e usar retorno em streaming.
***
Preços e status em tempo real na [página do modelo Kimi K3](https://aihubmix.com/model/kimi-k3); mais modelos na [galeria de modelos](https://aihubmix.com/models).
Última atualização: 2026-07-17