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

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: 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 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"
"Solicitação inválida: a sequência de parada não deve ser maior que 32, mas recebeu 33"

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 interações devem passar o histórico de pensamento de volta verbatim: de acordo com a documentação oficial da Moonshot, o K3 é treinado com o pensamento preservado, então em conversas de múltiplas interações a mensagem anterior do assistente deve ser passada de volta completa e não modificada (incluindo o conteúdo do 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ão ou uma camada de proxy, confirme que o conteúdo do pensamento é passado de volta sem cortes.
Conclusões de Chat

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

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 desce 2 metros. Quantos dias leva para chegar ao topo?"}
    ],
)

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

# Múltiplas interações: 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, as interações subsequentes respondem normalmente.
Respostas

O conteúdo do pensamento é retornado como um item de saída reasoning; em conversas de múltiplas interações, anexe os itens de saída da interação anterior (reasoning + message) de volta ao input verbatim.

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",
)

# Tipos de itens de saída observados: ["reasoning", "message"]; texto: "Paris"
# Múltiplas interações: input = [primeira mensagem do usuário] + response.output + [próxima mensagem do usuário]
# Resposta da segunda interação observada com itens de saída passados de volta: "Berlim"

Mensagens

O conteúdo do pensamento é retornado como blocos nativos de conteúdo thinking; em conversas de múltiplas interações, passe os blocos de conteúdo anteriores do assistente (incluindo os blocos de pensamento) de volta verbatim.

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últiplas interações: 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 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 das solicitações.

Nota: os valores de amostragem fixos são 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).
Conclusões 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 as interações subsequentes, e a mensagem deve ser incluída novamente em cada solicitação.

messages = [
    {"role": "system", "content": "Você é um assistente útil."},
    {"role": "user", "content": "Olá."},
    {"role": "assistant", "content": "Oi, como posso ajudar você?"},
    # Injete uma nova ferramenta no meio da conversa: campo tools apenas, 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?"},
]

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

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.

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",
)

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

Mensagens

As ferramentas usam o formato da Anthropic (input_schema); force uma chamada com tool_choice: {"type": "any"} e desabilite chamadas com {"type": "none"}. ❗ A API oficial de Mensagens do Kimi K3 (compatível com Anthropic) não suporta carregamento dinâmico de ferramentas: nos 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.

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 Esquema JSON.
Conclusões de Chat

response_format suporta json_schema com modo strict.

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

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

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

Mensagens

❗ A API 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.
Conclusões de Chat

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

# uso da segunda chamada de Respostas com instruções longas idênticas
"input_tokens_details": {"cached_tokens": 1536}

Mensagens

# 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.
Conclusões de Chat

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

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

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

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

Mensagens

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.

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.
Conclusões de Chat

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

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

# Texto de saída observado: "Vermelho"

Mensagens

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

# Texto de 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 HTML de arquivo único (um prompt com uma imagem de referência, gerado em um único disparo 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 diretamente executável, com finish_reason stop.

Recomendações do lado do cliente:

• Defina os tempos limite do cliente para minutos ou mais, e prefira streaming para tarefas longas;
• Deixe bastante margem em max_completion_tokens: neste caso, apenas o pensamento 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 reasoning_content deve ser passado de volta em conversas de múltiplas interações?
O K3 é treinado com o 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 do 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 as 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 os tempos limite 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