Índice da Documentação
Busque o índice completo da documentação em: https://docs.aihubmix.com/llms.txt
Use este arquivo para descobrir todas as páginas disponíveis antes de explorar mais.

Guia do Kimi K3 de julho de 2026: max de esforço de raciocínio, histórico de pensamento, carregamento dinâmico de ferramentas, saída estruturada, cache automático, prefixo parcial e entradas de visão.

Este artigo cobre os novos parâmetros e notas de uso para Kimi K3. No AIHubMix, o K3 está disponível através das APIs de Conclusões de Chat, Respostas e Mensagens compatíveis com Claude. Veja também: documentação oficial da plataforma Moonshot.

As conclusões e respostas de exemplo "Verificadas" em cada seção vêm de chamadas reais feitas em 2026-07-17 através das APIs do AIHubMix (Conclusões de Chat / Respostas / Mensagens).

1. Especificações do Modelo em Resumo

Verificado: ambos os limites de stop são validados, e exceder qualquer um retorna 400; a API de Mensagens aplica a mesma validação a stop_sequences.

❗ Quando uma sequência de parada é atingida, a API de Mensagens não segue a semântica da Anthropic: em testes, stop_reason é "end_turn" (em vez de "stop_sequence"), stop_sequence é null, e o texto visível antes da palavra de parada pode estar vazio. Clientes que dependem desses dois campos para detectar truncamento devem estar cientes.

# parada com 6 entradas / uma entrada de 33 bytes -> HTTP 400
"Solicitação inválida: array de parada muito longo. Esperado um array com comprimento máximo 5, mas recebeu um array com comprimento 6 em vez disso"
"Solicitação inválida: a sequência de parada não deve ser maior que 32, mas recebeu 33 em vez disso"

2. Modo de Pensamento: reasoning_effort Suporta Apenas max

O pensamento do K3 está ativado por padrão, e reasoning_effort suporta apenas um único nível: "max".

Conversas de múltiplas turnos devem passar o histórico de pensamento de volta verbatim: de acordo com a documentação oficial da Moonshot, o K3 é treinado com pensamento preservado, então em conversas de múltiplas turnos a mensagem anterior do assistente deve ser passada de volta completa e não modificada (incluindo o conteúdo de pensamento). A falta de histórico de pensamento leva a uma qualidade de saída instável. Se você usar uma estrutura de gerenciamento de sessões ou uma camada de proxy, confirme que o conteúdo de pensamento é passado de volta sem cortes.

O conteúdo de pensamento é retornado no campo `reasoning_content` da resposta; em conversas de múltiplas turnos, passe a mensagem anterior do assistente (incluindo `reasoning_content`) de volta verbatim.

```text theme={null}
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": "Um caracol está no fundo de um poço de 10 metros. A cada dia, ele sobe 3 metros, mas a cada noite ele escorrega de volta 2 metros. Quantos dias leva para chegar ao topo?"}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)
```

```text theme={null}
# Múltiplos turnos: passe a mensagem anterior do assistente de volta verbatim
messages = [
    {"role": "user", "content": "Qual é a capital da França?"},
    {"role": "assistant", "content": "Paris.", "reasoning_content": "<reasoning_content da resposta anterior>"},
    {"role": "user", "content": "E sua população?"},
]
```

> **Verificado**: a resposta retorna `reasoning_content`; após passar a mensagem anterior do assistente (incluindo `reasoning_content`) de volta verbatim, os turnos subsequentes respondem normalmente.

O conteúdo de pensamento é retornado como um item de saída `reasoning`; em conversas de múltiplas turnos, anexe os itens de saída do turno anterior (`reasoning` + `message`) de volta ao `input` verbatim.

```text theme={null}
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="Responda em uma palavra: capital da França",
)

# Itens de saída observados: ["reasoning", "message"]; texto: "Paris"
# Múltiplos turnos: input = [primeira mensagem do usuário] + response.output + [próxima mensagem do usuário]
# Resposta do segundo turno observada com itens de saída passados de volta: "Berlim"
```

O conteúdo de pensamento é retornado como blocos de conteúdo `thinking` nativos; em conversas de múltiplas turnos, passe os blocos de conteúdo do assistente anterior (incluindo os blocos de pensamento) de volta verbatim.

```text theme={null}
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": "Responda em uma palavra: capital da França"}
    ],
)

# Tipos de blocos de resposta observados: ["thinking", "text"]; texto: "Paris"
# Múltiplos turnos: passe response.content de volta verbatim como a mensagem do assistente
```

3. Parâmetros de Amostragem São Fixos

Os parâmetros de amostragem do K3 são fixos pelo fornecedor: temperature 1.0, top_p 0.95, n 1, e presence_penalty / frequency_penalty 0. A recomendação oficial é omitir esses parâmetros das solicitações.

Nota: os valores de amostragem fixos fazem parte da especificação oficial e não podem ser verificados a partir dos sinais de resposta; siga a recomendação oficial e omita esses parâmetros.

4. Chamada de Ferramentas e Carregamento Dinâmico de Ferramentas

tools suporta até 128 ferramentas; tool_choice suporta forçar e desabilitar chamadas de ferramentas. O K3 também suporta carregamento dinâmico de ferramentas: injetando novas ferramentas no meio da conversa através do campo tools de uma mensagem de sistema (uma forma de mensagem específica para a API de Chat).

`tool_choice` suporta `auto` / `none` / `required`; `required` força o modelo a chamar uma ferramenta. Carregamento dinâmico de ferramentas: a mensagem de sistema que injeta a ferramenta não carrega `content`, as ferramentas injetadas entram em vigor para turnos subsequentes, e a mensagem deve ser incluída novamente em cada solicitação.

```text theme={null}
messages = [
    {"role": "system", "content": "Você é um assistente útil."},
    {"role": "user", "content": "Olá."},
    {"role": "assistant", "content": "Oi, como posso ajudá-lo?"},
    # Injete uma nova ferramenta no meio da conversa: apenas campo tools, sem conteúdo
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_time",
                    "description": "Obter a hora atual",
                    "parameters": {"type": "object", "properties": {}},
                },
            }
        ],
    },
    {"role": "user", "content": "Que horas são agora?"},
]
```

```text theme={null}
# tool_choice="required" com prompt "Olá" -> o modelo é forçado a chamar a ferramenta
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"Nova York\"}"}}]
```

> **Verificado**: `tool_choice: "required"` força uma chamada de ferramenta mesmo para prompts não relacionados; `"none"` suprime chamadas de ferramentas; ferramentas injetadas no meio da conversa através de uma mensagem de sistema sem `content` podem ser chamadas normalmente.

As definições de ferramentas usam uma estrutura plana (`name` no nível superior); forçar uma chamada também usa `tool_choice: "required"`, e as chamadas são retornadas como itens de saída `function_call`. O suporte ao carregamento dinâmico de ferramentas está em progresso; por enquanto, declare todas as ferramentas no parâmetro `tools` de nível superior.

```text theme={null}
response = client.responses.create(
    model="kimi-k3",
    input="Olá",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Obter clima para uma cidade",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice="required",
)

# A saída observada contém: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"Londres\"}"}
```

As ferramentas usam o formato da Anthropic (`input_schema`); force uma chamada com `tool_choice: {"type": "any"}` e desabilite chamadas com `{"type": "none"}`. ❗ **O endpoint oficial de Mensagens do Kimi K3 (compatível com Anthropic) não suporta carregamento dinâmico de ferramentas**: em testes, a mensagem de injeção retorna 200, mas a ferramenta injetada não tem efeito (o modelo não pode 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": "Obter clima para uma cidade",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "Olá"}],
)

# Observado: stop_reason "tool_use"; o conteúdo contém um bloco tool_use chamando get_weather
```

5. Saída Estruturada

A saída estruturada faz com que o modelo retorne conteúdo que se conforma estritamente a um determinado JSON Schema.

`response_format` suporta `json_schema` com modo `strict`.

```text theme={null}
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Paris é a capital da França. Extraia o nome da cidade."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "extract",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
)

# Conteúdo da resposta observado: {"city":"Paris"}
```

> **Verificado**: a saída é um JSON válido que se conforma ao esquema.

A saída estruturada é declarada via `text.format`.

```text theme={null}
response = client.responses.create(
    model="kimi-k3",
    input="Paris é a capital da França. Extraia o nome da cidade.",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        }
    },
)

# Texto de saída observado: {"city":"Paris"}
```

❗ **O endpoint oficial de Mensagens do Kimi K3 (compatível com Anthropic) não suporta saída estruturada**: os campos de saída estruturada são ignorados silenciosamente — a solicitação retorna HTTP 200 com texto livre, sem erro ou aviso de fallback, e a análise JSON a montante falhará. Quando você precisar de saída estruturada, use a API de Conclusões de Chat ou Respostas.

6. O Cache de Contexto é Automático

O cache de contexto do K3 é ativado automaticamente, sem parâmetros necessários. Quando um prefixo longo repetido atinge o cache, a quantidade de acertos é relatada no uso (o nome do campo varia por API). A precificação do cache está na página do modelo.

```text theme={null} # uso da segunda chamada com um prefixo longo idêntico "prompt_tokens_details": {"cached_tokens": 1536} ```

> **Verificado**: a segunda solicitação com um prefixo longo idêntico relata o acerto em `usage.prompt_tokens_details.cached_tokens`.

```text theme={null} # uso da segunda chamada de Respostas com instruções longas idênticas "input_tokens_details": {"cached_tokens": 1536} ``` ```text theme={null} # uso da segunda chamada de Mensagens com um prompt de sistema longo idêntico "cache_read_input_tokens": 1536 ```

7. Conclusão de Prefixo partial

A conclusão de prefixo faz com que o modelo continue gerando a partir de um prefixo dado, bem adequado para conclusão de código e saída controlada por formato.

Passe `"partial": true` na última mensagem do assistente.

```text theme={null}
messages = [
    {"role": "user", "content": "Escreva um haicai sobre o mar."},
    {"role": "assistant", "content": "As ondas se dobram em espuma,", "partial": True},
]

# Prefixo: "As ondas se dobram em espuma,"  ->  continuação retornada pelo modelo
# o sal paira no ar—
# a lua puxa a maré para casa.
```

> **Verificado**: a geração continua a partir do prefixo dado sem repeti-lo.

Passe o prefixo como uma mensagem do assistente no final do array `input`; nenhum parâmetro `partial` é necessário.

```text theme={null}
response = client.responses.create(
    model="kimi-k3",
    input=[
        {"role": "user", "content": "Escreva um haicai sobre o mar."},
        {"role": "assistant", "content": "As ondas se dobram em espuma,"},
    ],
)

# Continuação observada: "o sal paira no ar— / a lua puxa a maré para casa."
```

A mesma capacidade é alcançada com o preenchimento nativo do assistente do protocolo, sem parâmetro `partial` — passe o prefixo como a última mensagem do assistente.

```text theme={null}
response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Escreva um haicai sobre o mar."},
        {"role": "assistant", "content": "As ondas se dobram em espuma,"},
    ],
)

# Continuação observada: "o vento salgado carrega o grito da gaivota— / a maré puxa ..."
```

8. Entrada de Visão

Imagens são passadas como base64; o formato do bloco de conteúdo varia por API.

```text theme={null} messages = [ { "role": "user", "content": [ {"type": "text", "text": "Qual é a cor dominante desta imagem? Uma palavra."}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,"}}, ], } ]

# Conteúdo da resposta observado: "Vermelho"  (entrada: um PNG sólido vermelho de 64x64)
```

> **Verificado**: a entrada de imagem base64 funciona, e o modelo descreve corretamente a imagem de teste.

```text theme={null} input = [ { "role": "user", "content": [ {"type": "input_text", "text": "Qual é a cor dominante desta imagem? Uma palavra."}, {"type": "input_image", "image_url": "data:image/png;base64,"}, ], } ]

# Texto de saída observado: "Vermelho"
```

```text theme={null} messages = [ { "role": "user", "content": [ {"type": "text", "text": "Qual é a cor dominante desta imagem? Uma palavra."}, {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": ""}}, ], } ]

# Texto da resposta observado: "Vermelho"
```

9. Referência Verificada: Latência e Uso de uma Tarefa Longa de Chamada Única

O pensamento do K3 é fixo no nível máximo, então solicitações únicas para tarefas complexas levam significativamente mais tempo do que em modelos típicos. Dados medidos de uma tarefa de geração de jogo em HTML de arquivo único (um prompt com uma imagem de referência, gerada em um único tiro sem iteração): a solicitação única levou 2.541 segundos (cerca de 42 minutos), com 74.994 tokens de conclusão, dos quais 54.486 (73%) eram tokens de pensamento; a saída final foi de 1.275 linhas de código executável diretamente, com finish_reason stop.

Recomendações do lado do cliente:

• Defina timeouts do cliente para minutos ou mais, e prefira streaming para tarefas longas;
• Deixe bastante margem em max_completion_tokens — neste caso, o pensamento sozinho consumiu 54.486 tokens.

10. Capacidade × Matriz de Suporte da API

Cada célula na tabela abaixo foi verificada em 2026-07-17 através de chamadas reais para as APIs de produção do AIHubMix; cada célula mostra a sintaxe do parâmetro / campo para a API correspondente.

FAQ

Quais APIs o K3 suporta no AIHubMix?
Conclusões de Chat (/v1/chat/completions), Respostas (/v1/responses), e a API de Mensagens compatível com Claude (/v1/messages).

O pensamento pode ser desativado ou reduzido?
Não. O pensamento do K3 está ativado por padrão, e reasoning_effort suporta apenas o único nível "max".

Por que o reasoning_content deve ser passado de volta em conversas de múltiplas turnos?
O K3 é treinado com pensamento preservado; a Moonshot exige que a mensagem anterior do assistente seja passada de volta completa e não modificada. A falta de histórico de pensamento leva a uma qualidade de saída instável.

Quais são os limites no parâmetro stop?
No máximo 5 sequências de parada, cada uma não maior que 32 bytes; exceder qualquer um dos limites retorna um erro 400.

A API de Mensagens suporta saída estruturada?
❗ Não. O endpoint oficial de Mensagens do Kimi K3 ignora silenciosamente os campos de saída estruturada (retornando 200 com texto livre e sem erro). Para saída estruturada, use response_format em Conclusões de Chat ou text.format em Respostas.

Por que solicitações únicas do K3 demoram tanto?
O pensamento do K3 é fixo no nível máximo, e os tokens de pensamento representam uma grande parte em tarefas complexas (73% dos tokens de conclusão no caso medido). Defina timeouts do cliente para minutos ou mais e use streaming.

Para preços e status em tempo real, veja a página do modelo Kimi K3; para mais modelos, visite a galeria de modelos.

Última atualização: 2026-07-17