AiHubMix Documentation Hub

Guia prático do Kimi K3: modo de raciocínio, carregamento dinâmico de ferramentas e cache de contexto

Este artigo apresenta os novos parâmetros do 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. 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.

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

Chat Completions
Responses
Messages

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.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_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)

# 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": "<reasoning_content from the previous response>"},
    {"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.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_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.

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_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).

Chat Completions
Responses
Messages

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.

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?"},
]

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

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.

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.

Chat Completions
Responses
Messages

response_format suporta json_schema e o modo strict.

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.

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"}

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.

Chat Completions
Responses
Messages

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

# usage of the second Responses call with identical long instructions
"input_tokens_details": {"cached_tokens": 1536}

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

Chat Completions
Responses
Messages

Envie "partial": true na última mensagem assistant.

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.

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.

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.

Chat Completions
Responses
Messages

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

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,<BASE64>"},
        ],
    }
]

# Observed output text: "Red"

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": "<BASE64>"}},
        ],
    }
]

# 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; mais modelos na galeria de modelos. Última atualização: 2026-07-17

​1. Visão geral das especificações do modelo

​2. Modo de raciocínio: reasoning_effort só aceita o nível max

​3. Parâmetros de amostragem com valores fixos

​4. Chamada de ferramentas e carregamento dinâmico de ferramentas

​5. Saída estruturada

​6. Cache de contexto ativado automaticamente

​7. Continuação de prefixo com partial

​8. Entrada visual

​9. Referência verificada: tempo e uso de uma chamada única em tarefa longa

​10. Matriz de suporte capacidade × API

​Perguntas frequentes (FAQ)