"temperature is deprecated for this model": causas e solução — temperature na API do Claude e a nova versão de API 2026-10-21

Se a API do Claude retornar o erro a seguir, a causa é que você está enviando um valor diferente do padrão para temperature (ou top_p ou top_k) a um modelo Claude 4.7 ou posterior. A correção é remover esses três parâmetros das suas requisições. Na nova versão da API 2026-10-21, lançada em outubro de 2026, enviar qualquer um deles retorna um erro 400 para todos os modelos, independentemente do valor.

400 invalid_request_error
`temperature` is deprecated for this model.

Exemplo de resposta quando um valor diferente do padrão é enviado a um modelo Claude 4.7 ou posterior (relatado por usuários). A documentação oficial não informa se a mensagem de erro retornada pela nova versão da API é a mesma.

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    temperature=0.2,
    messages=[...],
)

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[...],
)

Com base na documentação oficial da Anthropic (consultada em 26 de outubro de 2026), este artigo explica as duas situações em que esse erro aparece, o que acontece ao atualizar o SDK, as mudanças a fazer junto com a nova versão da API e como corrigir o erro parecido anthropic-version: header is required. As versões da API são identificadas por cor: 2023-06-01 (a versão anterior) e 2026-10-21 (a nova versão).

1. As duas situações em que o erro aparece

A API do Claude escolhe a versão da API pelo cabeçalho da requisição anthropic-version. Se haverá erro depende da combinação entre o modelo que você usa e a versão da API.

Fontes: Anthropic, "Migrating to API version 2026-10-21" (modelos Claude 4.7 e posteriores aceitam apenas o valor padrão; Sonnet 4.6 e outros aceitam outros valores; com 2026-10-21, todos os modelos retornam 400 mesmo com o valor padrão), e os guias de migração de cada modelo (Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1; o guia do Fable 5.1 diz que ele tem as mesmas restrições de amostragem do Opus 5). Consultado em 26 de outubro de 2026.

As células marcadas com "400" na tabela correspondem às duas situações a seguir.

1. Situação 1: você enviou um valor diferente do padrão com 2023-06-01 a um modelo Claude 4.7 ou posterior (primeira linha da tabela, coluna 2023-06-01)
2. Situação 2: você enviou qualquer um dos três com 2026-10-21, independentemente do modelo ou do valor (coluna da direita da tabela)

A mensagem de erro do início, `temperature` is deprecated for this model., aparece na situação 1, em uma resposta da API que um usuário relatou no GitHub (exemplo relatado). A documentação oficial da Anthropic não inclui a própria mensagem de erro; ela apenas diz que a requisição retorna um erro 400.

Em resumo, remover os três parâmetros corrige as duas situações. Se você alterava valores em um modelo mais antigo, observe que removê-los muda a variação das respostas (veja a seção 2).

2. A correção, e como obter sempre a mesma resposta

1. Remova os três parâmetros das suas requisiçõesRemova temperature, top_p e top_k das requisições da Messages API e de cada requisição do Message Batches. Se um arquivo de configuração ou uma função wrapper define um valor padrão para eles, remova-o também ali.
2. O que acontece depois da remoçãoSe você não enviar os três, o próximo token é escolhido com os valores padrão (temperature tem padrão 1.0). Os valores padrão de top_p e top_k não são informados como números, então não enviá-los é a opção mais segura. Isso é igual a não enviar os três nas versões anteriores da API. Os modelos Claude 4.7 ou posteriores já aceitam apenas valores padrão, então o comportamento deles não muda.
3. Se você quer sempre a mesma respostaNão existe uma configuração que substitua isso. O guia de migração da Anthropic recomenda orientar o comportamento do modelo por meio de prompts. Ele também diz que, mesmo com temperature = 0, nunca houve garantia de respostas idênticas nos modelos anteriores. Se você só quer padronizar o formato da resposta, pode usar as Structured outputs (saídas estruturadas), que permitem definir um formato JSON e fazer o modelo retorná-lo.

A exceção é quando você usa um modelo que aceita outros valores, como o Claude Sonnet 4.6, e reduziu o valor para diminuir a variação das respostas. Com a nova versão da API, é preciso removê-lo, e esse efeito se perde. A orientação da Anthropic é manter essa requisição em 2023-06-01 ou deixar de enviar o parâmetro. Para manter 2023-06-01, fique na versão principal atual do SDK (1.x no Python) ou, se você chama o HTTP diretamente, mantenha o cabeçalho como anthropic-version: 2023-06-01. O guia de migração não explica como escolher uma versão antiga da API por requisição com o novo SDK.

Como corrigir em TypeScript e HTTP

// TypeScript (@anthropic-ai/sdk): remova temperature
const msg = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});

# HTTP (corpo JSON): não inclua as linhas de temperature, top_p e top_k
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Hello, Claude"}]
}

3. Encontrando onde o seu código envia os parâmetros

Se você não sabe onde está o erro, procure no código os nomes dos três parâmetros. Mesmo que você não tenha escrito o código, valores padrão costumam ser definidos em arquivos de configuração, funções compartilhadas ou variáveis de ambiente.

# macOS, Linux, WSL: procure no projeto (sem diferenciar maiúsculas e minúsculas)
grep -rniE "temperature|top_p|top_k" --exclude-dir={node_modules,.venv,venv,.git,dist} \
  --include="*.py" --include="*.ts" --include="*.js" --include="*.json" \
  --include="*.yaml" --include="*.yml" --include="*.toml" --include=".env*" .

# Windows (PowerShell)
Get-ChildItem -Recurse -Include *.py,*.ts,*.js,*.json,*.yaml,*.yml,*.toml,.env* |
  Where-Object { $_.FullName -notmatch "node_modules|\\.?venv|\\.git\\|\\dist\\" } |
  Select-String -Pattern "temperature|top_p|top_k"

As regras da nova versão da API valem para as requisições da Messages API, as de contagem de tokens e cada requisição do Message Batches (guia de migração da Anthropic).

4. O que acontece quando você atualiza o SDK

Os SDKs oficiais enviam automaticamente a versão da API que estava atual quando a versão principal foi lançada. A partir das versões de SDK da tabela abaixo, eles enviam 2026-10-21, e os três parâmetros removidos também sumiram dos tipos do SDK (guia de migração da Anthropic). Por isso, ao atualizar o SDK, o problema pode aparecer primeiro como um erro de verificação de tipos ou de "argumento inesperado", e não como um 400 da API. Se você adiciona parâmetros ao corpo sem passar pelos tipos (por exemplo, usando um recurso que envia campos extras no corpo, ou enviando requisições diretamente por HTTP), a API retorna um 400. A correção é a mesma nos dois casos: remova os três parâmetros.

Fonte: Anthropic, "Migrating to API version 2026-10-21", seção Upgrade steps. Se você chama a API sem usar um SDK, defina o cabeçalho anthropic-version como 2026-10-21 para usar a nova versão da API.

A nova versão da API está disponível na Claude API, no Claude Platform on AWS, no Claude no Google Cloud (tanto gerenciado pela Anthropic quanto pelo Google) e no Microsoft Foundry. No Amazon Bedrock, a nova versão só está disponível para os modelos Claude 4.7 ou posteriores. Se você chama modelos mais antigos ali, a Anthropic recomenda manter a versão atual do seu SDK (ou o seu anthropic-version atual) (Versions).

Passos para atualizar o SDK

1. Mude para a nova versão da APIAtualize o SDK para a versão da tabela acima. Se você chama o HTTP diretamente, defina anthropic-version: 2026-10-21.
2. Corrija as mudanças incompatíveisRemova os três parâmetros e corrija os itens da tabela da seção 5 que se aplicam a você. Também confira as mudanças na forma de escrever com os novos SDKs (como nomes de tipos) em "SDK and CLI changes" no guia de migração.
3. Teste com a nova versão da API antes de publicarAntes de colocar em produção, teste se as suas requisições funcionam com a nova versão da API. Publique a atualização do SDK e as correções juntas.

Fonte: Anthropic, "Migrating to API version 2026-10-21", seção Upgrade steps (Switch to 2026-10-21 → Update your code for the breaking changes → Test against 2026-10-21).

5. Outras mudanças para corrigir com a nova versão da API

Se você passar para a nova versão da API, há outras mudanças além de temperature. (A linha da chave de API é uma mudança apenas do SDK e da CLI; não faz diferença se você chama o HTTP diretamente.) Corrija apenas as que se aplicam a você (seção Breaking changes do mesmo guia de migração).

6. Como corrigir anthropic-version: header is required

O erro a seguir aparece quando a requisição não tem o cabeçalho da versão da API.

400 invalid_request_error
anthropic-version: header is required

Os SDKs oficiais enviam a versão da API automaticamente, então esse erro aparece principalmente quando você chama o HTTP diretamente, sem SDK. Por exemplo, há relatos no GitHub de casos em que um cliente ou ferramenta feito para a OpenAI aponta para a URL da API do Claude e tenta listar os modelos (/v1/models) (exemplo 1, exemplo 2).

A correção é adicionar o cabeçalho. Para um código novo, use 2026-10-21; para que o código atual funcione sem mudanças, use 2023-06-01.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{"model": "claude-opus-5-5", "max_tokens": 1024,
       "messages": [{"role": "user", "content": "Hello, Claude"}]}'

Fonte: Anthropic, "Versions" (o cabeçalho anthropic-version é obrigatório nas requisições; os SDKs o enviam automaticamente). A mensagem de erro vem de uma resposta da API que um usuário relatou no GitHub. A API aceita a chave de API nos cabeçalhos x-api-key e Authorization: Bearer (guia de migração).

Se a ferramenta que você usa não permite adicionar cabeçalhos, verifique se ela oferece suporte à API do Claude (e se não está chamando a API no formato da OpenAI).

Resumo

FAQ

P. Posso enviar temperature com o valor 1.0 (o valor padrão)?

Com a nova versão da API 2026-10-21, enviá-lo retorna 400 mesmo com o valor padrão. Se você chama um modelo Claude 4.7 ou posterior com 2023-06-01, o valor padrão funciona, mas não há motivo para enviá-lo, então remover é a opção mais segura.

P. Eu usava temperature = 0 para obter sempre a mesma resposta. O que usar no lugar?

Não existe uma configuração que substitua isso. O guia de migração da Anthropic diz que, mesmo com temperature = 0, nunca houve garantia de respostas idênticas. Se você quer padronizar o formato da resposta (como campos de JSON), use as Structured outputs, e especifique em detalhe a redação e os critérios de decisão no prompt.

P. Posso continuar usando a versão atual sem passar para a nova versão da API?

Sim. A Anthropic diz que mantém os campos de entrada e saída existentes dentro de cada versão da API, e que 2023-06-01 continua podendo ser especificada como antes. A página Versions não informa quando 2023-06-01 será desativada (Versions, consultada em 26 de outubro de 2026). No entanto, para os modelos Claude 4.7 ou posteriores, um temperature ou outro valor diferente do padrão continua retornando 400 mesmo com 2023-06-01. A Anthropic também recomenda usar a versão mais nova da API sempre que possível, e atualizar o SDK muda você automaticamente para a nova versão.

P. Troquei para um modelo Claude 4.7 ou posterior e apareceu um erro

Depois de trocar para um modelo Claude 4.7 ou posterior, um temperature ou outro valor diferente do padrão retorna 400, mesmo que a versão da API seja a mesma. Para outros pontos a corrigir ao trocar de modelo (como as configurações de thinking e o prefill), veja o "Guia de migração do Claude Opus 4.7".