Guia Prático do Kimi K3: Novos Parâmetros e Matriz de Suporte de API

Este artigo aborda os novos parâmetros e notas de uso do Kimi K3. No AIHubMix, o K3 está disponível pelas APIs Chat Completions, Responses e Messages compatível com Claude. Veja também: documentação oficial da plataforma Moonshot.

As conclusões "Verificado" e as respostas de exemplo de cada seção vêm de chamadas reais feitas em 17/07/2026 pelas APIs do AIHubMix (Chat Completions / Responses / Messages).

1. Especificações do Modelo em Resumo

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

❗ Quando uma sequência de parada é atingida, a API Messages não segue a semântica da Anthropic: nos 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 levar isso em conta.

# 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 Suporta Apenas max

O thinking do K3 vem ativado por padrão, e reasoning_effort suporta apenas um nível: "max".

Conversas com múltiplos turnos devem devolver o histórico de thinking sem alterações: segundo a documentação oficial da Moonshot, o K3 é treinado com thinking preservado, portanto, em conversas com múltiplos turnos, a mensagem anterior do assistente deve ser devolvida completa e sem modificações (incluindo o conteúdo de thinking). A ausência do histórico de thinking leva a uma qualidade de saída instável. Se você usa um framework de gerenciamento de sessão ou uma camada de proxy, confirme que o conteúdo de thinking é devolvido sem cortes.
Chat Completions

O conteúdo de thinking é retornado no campo reasoning_content da resposta; em conversas com múltiplos turnos, devolva a mensagem anterior do assistente (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; após devolver a mensagem anterior do assistente (incluindo reasoning_content) sem alterações, os turnos seguintes respondem normalmente.
Responses

O conteúdo de thinking é retornado como um item de saída reasoning; em conversas com múltiplos turnos, anexe os itens de saída do turno anterior (reasoning + message) de volta a input sem alterações.

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"

Messages

O conteúdo de thinking é retornado como blocos de conteúdo thinking nativos; em conversas com múltiplos turnos, devolva os blocos de conteúdo anteriores do assistente (incluindo os blocos de 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 São Fixos

Os parâmetros de amostragem do K3 são fixados pelo provedor do modelo: temperature 1.0, top_p 0.95, n 1, e presence_penalty / frequency_penalty 0. A recomendação oficial é omitir esses parâmetros nas requisições.

Nota: os valores fixos de amostragem fazem parte da especificação oficial e não podem ser verificados pelos sinais da 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 permite forçar e desabilitar chamadas de ferramentas. O K3 também suporta carregamento dinâmico de ferramentas: injetar novas ferramentas no meio da conversa pelo campo tools de uma mensagem de sistema (um formato de mensagem específico da API Chat).
Chat Completions

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 ferramentas não tem content, as ferramentas injetadas passam a valer nos turnos seguintes, e a mensagem deve ser incluída novamente em cada requisiçã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 para prompts não relacionados; "none" suprime chamadas de ferramentas; ferramentas injetadas no meio da conversa por uma mensagem de sistema sem content podem ser chamadas normalmente.
Responses

As definições de ferramentas usam 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 andamento; por enquanto, 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\"}"}

Messages

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 Messages (compatível com Anthropic) do Kimi K3 não suporta carregamento dinâmico de ferramentas: nos testes, a mensagem que injeta 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 que segue estritamente um JSON Schema fornecido.
Chat Completions

response_format suporta json_schema com 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 é um JSON válido conforme o schema.
Responses

A saída estruturada é declarada via 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"}

Messages

❗ 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 erro nem aviso de fallback, e a análise de JSON nas etapas seguintes falhará. Quando precisar de saída estruturada, use a API Chat Completions ou Responses.

6. Cache de Contexto é Automático

O cache de contexto do K3 é ativado automaticamente, sem necessidade de parâmetros. Quando um prefixo longo repetido atinge o cache, a quantidade de acertos é informada em usage (o nome do campo varia conforme a API). Os preços do cache estão na página do modelo.
Chat Completions

# 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 informa o acerto em usage.prompt_tokens_details.cached_tokens.
Responses

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

Messages

# usage of the second Messages call with an identical long system prompt
"cache_read_input_tokens": 1536

7. Completação de Prefixo com partial

A completação de prefixo faz o modelo continuar gerando a partir de um prefixo dado, muito útil para completação de código e saídas com formato controlado.
Chat Completions

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

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 dado, sem repeti-lo.
Responses

Passe o prefixo como uma mensagem do assistente no fim do array input; não é necessário 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."

Messages

A mesma capacidade é obtida com o prefill nativo de assistente do protocolo, sem o parâmetro partial: passe o prefixo como a última mensagem do assistente.

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 de Visão

As imagens são enviadas em base64; o formato dos blocos de conteúdo varia conforme a API.
Chat Completions

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, e o modelo descreve corretamente a imagem de teste.
Responses

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

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: Latência e Uso de uma Tarefa Longa em Chamada Única

O thinking do K3 fica fixado no nível máximo, então requisições únicas para tarefas complexas levam bem mais tempo do que em modelos típicos. Dados medidos a partir de uma tarefa de geração de jogo HTML em arquivo único (um prompt com uma imagem de referência, gerado de uma só vez, sem iteração): a requisiçã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 thinking; a saída final foi de 1,275 linhas de código diretamente executável, com finish_reason stop.

Recomendações do lado do cliente:

• Configure timeouts do cliente para minutos ou mais, e prefira streaming para tarefas longas;
• Deixe margem suficiente em max_completion_tokens: neste caso, somente o thinking consumiu 54,486 tokens.

10. Matriz de Suporte Capacidade × API

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

FAQ

Quais APIs o K3 suporta no AIHubMix?
Chat Completions (/v1/chat/completions), Responses (/v1/responses) e a API Messages compatível com Claude (/v1/messages).

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

Por que o reasoning_content precisa ser enviado de volta em conversas com várias etapas?
O K3 é treinado com pensamento preservado; a Moonshot exige que a mensagem anterior do assistente seja devolvida completa e sem alterações. Sem o histórico de pensamento, a qualidade da saída fica instável.

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

A Messages API oferece suporte a saída estruturada?
❗ Não. O endpoint oficial Messages do Kimi K3 (compatível com Anthropic) ignora silenciosamente os campos de saída estruturada (retornando 200 com texto livre e sem erro). Para saída estruturada, use response_format no Chat Completions ou text.format no Responses.

Por que as requisições únicas do K3 demoram tanto?
O pensamento do K3 fica fixado no nível máximo, e os tokens de pensamento representam uma grande parcela 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, consulte a página do modelo Kimi K3; para mais modelos, visite a galeria de modelos.

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