Como Usar a API Claude Fable 5.1: Passo a Passo com Apidog

Como usar o Claude Fable 5.1 na API: esforço, streaming, ferramentas e cache

O Claude Fable 5.1 foi lançado em 1º de setembro de 2026. Na API, o ID exato do modelo é claude-fable-5-1, sem sufixo de data. O preço é o mesmo do Fable 5: US$ 10 por milhão de tokens de entrada e US$ 50 por milhão de tokens de saída. As leituras de cache custam US$ 0,25 por milhão de tokens. O modelo também introduz três mudanças incompatíveis com o Fable 5.

Experimente o Apidog hoje

Este guia mostra como obter uma chave, fazer a primeira chamada, controlar o esforço, usar streaming, trabalhar com ferramentas sem tool_choice forçado, configurar fallbacks, receber atualizações de progresso e verificar o cache. Todos os exemplos usam HTTP puro com JSON, portanto podem ser criados e depurados no Apidog antes da integração com sua aplicação.

Se você estiver migrando um serviço Fable 5 ou Opus 5, consulte também o guia completo de migração. Para conhecer o modelo, comece por o que é o Claude Fable 5.1.

Antes da primeira chamada: três situações que retornam 400

1. Pensamento não pode ser desativado. O Fable 5.1 usa pensamento adaptativo em todas as solicitações. Omita thinking ou envie {"type": "adaptive"}. Os valores {"type": "disabled"} e {"type": "enabled", "budget_tokens": N} retornam 400. Controle os gastos com output_config.effort.

2. Uso forçado de ferramentas foi removido. tool_choice: {"type": "any"} e {"type": "tool", "name": "..."} retornam:
   

   tool_choice: type "tool" and "any" are not supported for this model

Use a estratégia descrita na seção sobre ferramentas.

1. A organização precisa de retenção de dados de 30 dias. O Fable 5.1 é um Modelo Abrangente (Covered Model). Organizações ou workspaces com retenção zero recebem 400 invalid_request_error. Se a primeira chamada falhar apesar de o corpo parecer correto, verifique essa configuração.

Esses requisitos estão documentados em Novidades no Claude Fable 5.1.

Passo 1: obtenha uma chave de API

Faça login no Claude Console, abra as configurações da organização, acesse as chaves de API e crie uma chave. Copie-a imediatamente: ela não poderá ser consultada novamente.

Exporte a chave em vez de gravá-la no código:

export ANTHROPIC_API_KEY="sk-ant-..."

No Apidog, crie uma variável de ambiente chamada ANTHROPIC_API_KEY e use {{ANTHROPIC_API_KEY}} no cabeçalho. Assim, a chave não fica armazenada no corpo da solicitação.

Passo 2: envie a primeira solicitação

Crie um POST para https://api.anthropic.com/v1/messages com estes cabeçalhos:

• x-api-key
• anthropic-version: 2023-06-01
• content-type: application/json

curl https://api.anthropic.com/v1/messages \
  -H "x-[REDACTED CREDENTIAL] \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5-1",
    "max_tokens": 16000,
    "messages": [
      {"role": "user", "content": "Explain the difference between idempotent and safe HTTP methods, with one example each."}
    ]
  }'

A mesma chamada usando o SDK oficial para Python:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Explain the difference between idempotent and safe HTTP methods, with one example each."}],
)

if response.stop_reason == "refusal":
    print("declined:", response.stop_details.category if response.stop_details else None)
else:
    for block in response.content:
        if block.type == "text":
            print(block.text)

Adote dois hábitos desde a primeira chamada:

• Verifique stop_reason antes de ler content. Uma recusa do classificador retorna HTTP 200 com um array de conteúdo vazio.
• Defina max_tokens com margem suficiente. O limite inclui tokens de pensamento e tokens de resposta, e o pensamento está sempre ativo.

A resposta contém um bloco thinking cujo texto fica vazio quando o display padrão é omitted. Isso é esperado. Ao enviar a resposta de volta, preserve esse bloco sem alterações.

Passo 3: controle custo e profundidade com effort

O parâmetro effort é a principal alavanca do Fable 5.1. Ele fica dentro de output_config e aceita low, medium, high, xhigh e max. O padrão é high.

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "output_config": {"effort": "medium"},
  "messages": [
    {
      "role": "user",
      "content": "Summarize this changelog in five bullets."
    }
  ]
}

A documentação do parâmetro effort recomenda começar com high e testar os demais níveis com suas próprias avaliações. Repita os testes mesmo que já tenha feito uma avaliação no Fable 5: os mesmos nomes não representam a mesma quantidade de pensamento em modelos diferentes.

Observe também:

• medium pode se aproximar do Fable 5 com custo menor.
• low pode ser competitivo com Opus e Sonnet em custo por tarefa.
• Em low, o modelo pode usar ferramentas de busca e recuperação com menos frequência.
• Em xhigh e max, o modelo pode criar um entregável longo no pensamento e depois escrevê-lo novamente. Reserve tokens suficientes para as duas etapas.

Alterando o esforço durante a conversa

No Fable 5.1, é possível alterar o esforço a partir da próxima mensagem do usuário sem invalidar o prefixo em cache. Para isso, use uma mensagem system vazia com output_config.

Esse recurso exige o cabeçalho beta mid-conversation-output-config-2026-07-01 e client.beta.messages:

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    output_config={"effort": "high"},
    betas=["mid-conversation-output-config-2026-07-01"],
    messages=[
        {"role": "user", "content": "Plan a migration from SQLite to PostgreSQL in three short steps."},
        {"role": "assistant", "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."},
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "Summarize the plan in one sentence."},
    ],
)

Reduzir o esforço dessa forma é confiável. Para aumentos maiores, como de low para xhigh, faça uma mudança mais ampla. O guia de parâmetros de esforço para Opus 5 detalha os cinco níveis; a semântica também se aplica ao Fable 5.1.

Passo 4: transmita a resposta

Em tarefas difíceis, o Fable 5.1 pode levar minutos com esforço alto. Use streaming para respostas potencialmente longas. O SDK exige streaming quando max_tokens se aproxima do limite de 128.000 tokens, evitando timeouts HTTP.

with client.messages.stream(
    model="claude-fable-5-1",
    max_tokens=64000,
    messages=[{"role": "user", "content": "Write a test plan for a rate-limited public API."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()

print(final.stop_reason, final.usage.output_tokens)

No Apidog, respostas em streaming são renderizadas conforme chegam. Isso ajuda a medir quanto tempo o modelo passa pensando antes do primeiro token de texto.

Passo 5: use ferramentas sem forçá-las

A definição de ferramentas permanece igual à do Fable 5. A diferença está em como solicitar uma chamada.

No Fable 5.1, tool_choice: {"type": "tool", ...} retorna 400, pois uma chamada forçada poderia interromper o pensamento adaptativo. Use:

1. tool_choice: {"type": "auto"};
2. o nome da ferramenta na instrução;
3. strict: true e additionalProperties: false no schema.

record_summary_tool = {
    "name": "record_summary",
    "description": "Record the structured summary of the document.",
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {"summary": {"type": "string"}},
        "required": ["summary"],
        "additionalProperties": False,
    },
}

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    tools=[record_summary_tool],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "Summarize: The meeting moved to Thursday. Call the record_summary tool with your result.",
        }
    ],
)

Para obter JSON sem uma chamada de ferramenta, use saídas estruturadas com output_config.format.

Se a aplicação exigir uma ferramenta específica naquela rodada, adicione uma mensagem system depois da última mensagem do usuário, nomeando a ferramenta e informando que a chamada é necessária. tool_choice: {"type": "none"} continua disponível para rodadas que não devem usar ferramentas.

O loop do agente permanece o mesmo:

1. Quando stop_reason for tool_use, execute cada bloco tool_use.
2. Envie todos os blocos tool_result em uma mensagem do usuário.
3. Preserve a resposta do assistente exatamente como foi retornada, incluindo os blocos de pensamento.

Consulte o guia de uso estrito de ferramentas e o guia de pensamento preservado.

Em loops longos, o Fable 5.1 pode emitir uma chamada por turno, enquanto o Fable 5 agrupava várias. Para solicitar chamadas independentes no mesmo turno, acrescente uma mensagem system com escopo de turno:

Primeiro liste privadamente o que você precisa em seguida; depois solicite cada item que não dependa do resultado de outro nesta única resposta.

Envie essa mensagem com clear_at: "next_user_message" e o beta mid-conversation-system-clear-at-2026-08-21. Mantenha as cópias anteriores no histórico.

Passo 6: configure fallbacks para recusas

O Fable 5.1 executa classificadores de segurança. Uma solicitação recusada retorna HTTP 200 com:

• stop_reason: "refusal"
• stop_details.category: cyber, bio, frontier_llm, reasoning_extraction ou general_harms

Uma recusa antes de qualquer saída não é faturada.

Por padrão, use fallbacks. A opção mais simples é fallbacks: "default" com o beta server-side-fallback-2026-07-01. Para o Fable 5.1, os modelos permitidos são claude-opus-4-8 e claude-opus-5.

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
    messages=[{"role": "user", "content": "Audit this authentication middleware for logic bugs."}],
)

fallback_ran = any(
    entry.type == "fallback_message" for entry in (response.usage.iterations or [])
)
if fallback_ran and response.stop_reason != "refusal":
    print("served by", response.model)

O campo model de nível superior identifica o modelo que respondeu, e um bloco fallback_message marca a transição. Preserve esse bloco ao ecoar a rodada.

fallbacks não funciona na API de Lotes nem está disponível no Bedrock, Google Cloud ou Foundry. Nesses ambientes, registre o BetaRefusalFallbackMiddleware do SDK no cliente. Consulte o guia de tratamento de recusas para detalhes sobre faturamento, roteamento persistente e tentativas manuais.

Passo 7: receba atualizações de progresso

Durante turnos longos, o Fable 5.1 pode produzir notas curtas sobre o que encontrou e fará em seguida. Essas notas chegam como blocos thinking imediatamente antes de chamadas de ferramentas.

Para recebê-las como texto sem expor o raciocínio completo, use display: "updates" e o beta thinking-display-updates-2026-08-18:

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive",
    "display": "updates"
  },
  "tools": [],
  "messages": [
    {
      "role": "user",
      "content": "Review the PRs open against our billing service."
    }
  ]
}

Renderize qualquer bloco thinking com texto não vazio como uma linha de status. O Fable 5.1 produz menos atualizações que o Fable 5; remova prompts que instruam o modelo a guardar descobertas para a resposta final se sua interface depender dessa narração.

Passo 8: confirme a taxa de cache de US$ 0,25

O cache de prompt é onde a principal mudança de preço aparece. Coloque cache_control no prefixo estável e verifique o objeto usage:

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    system=[
        {
            "type": "text",
            "text": LONG_STABLE_SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Which endpoints in the spec lack an error schema?"}],
)

u = response.usage
print(u.input_tokens, u.cache_creation_input_tokens, u.cache_read_input_tokens)

Na primeira solicitação, cache_creation_input_tokens deve ser diferente de zero. Para o TTL de cinco minutos, esses tokens custam US$ 12,50 por milhão. Em uma segunda solicitação dentro de cinco minutos, cache_read_input_tokens deve ser diferente de zero e custará US$ 0,25 por milhão.

Se as leituras permanecerem em zero, audite o prefixo em busca de:

• timestamps no prompt do sistema;
• JSON com ordenação variável;
• arrays de ferramentas diferentes entre as chamadas.

O prompt mínimo armazenável em cache é de 512 tokens. Como uma falha de cache custa 40 vezes mais que uma leitura, manter o cache aquecido é especialmente importante no Fable 5.1.

Mensagens de sistema com escopo de turno e esforço por mensagem permitem alterar o comportamento sem reiniciar a sessão. Evite reconstruir o system ou editar turnos anteriores: essas mudanças invalidam o cache e também os blocos de pensamento.

Consulte a documentação de Cache de prompt e o detalhamento de preços do Fable 5.1.

Teste o fluxo completo no Apidog

Salve cada etapa em uma coleção do Apidog:

• primeira chamada;
• variantes de esforço;
• streaming;
• loop de ferramentas;
• fallback;
• verificação de cache.

Use variáveis de ambiente para a chave e o modelo. Assim, alternar uma coleção entre claude-fable-5 e claude-fable-5-1 exige apenas uma edição.

Adicione asserções para verificar que:

• stop_reason não é refusal nos prompts benignos de teste;
• usage.cache_read_input_tokens é maior que zero na segunda solicitação;
• nenhuma entrada de input_transformations possui reason: "prefix_binding_mismatch" ao usar o cabeçalho de ligação de pensamento.

Execute a coleção antes e depois de alterar o harness. Você também pode baixar o Apidog e reutilizar a coleção como verificação de CI pelo Apidog CLI.

Erros e armadilhas comuns

• 400 tool_choice: type "tool" and "any" are not supported for this model
  
  Use auto, mencione a ferramenta na instrução e defina strict: true.

• 400 com thinking: {"type": "disabled"}
  
  Remova o campo e reduza o esforço com output_config.effort.

• 400 invalid_request_error com corpo válido
  
  Verifique a retenção de dados de 30 dias da organização ou workspace.

• 400 Invalid signature in thinking block. The block is bound to a different conversation.
  
  O código editou um turno anterior, o prompt do sistema ou o array de ferramentas. Consulte o guia de pensamento preservado.

• Blocos de pensamento vazios
  
  Isso é esperado com display: "omitted". Use summarized ou updates para renderizar informações.

• Leituras de cache iguais a zero
  
  O prefixo é volátil. Procure timestamps e objetos não ordenados.

• Falha de validação da Camada de Prioridade
  
  O Fable 5.1 não suporta a Camada de Prioridade; o Fable 5 suporta.

FAQ

Qual é o ID do Claude Fable 5.1 na API?

Use claude-fable-5-1.

No Amazon Bedrock, use anthropic.claude-fable-5-1. Google Cloud, Microsoft Foundry e Claude Platform na AWS usam claude-fable-5-1.

Preciso de um cabeçalho beta?

Não para o modelo base, pensamento adaptativo, esforço, ferramentas ou cache. O cabeçalho padrão é:

anthropic-version: 2023-06-01

Cabeçalhos beta são necessários apenas para:

• esforço por mensagem;
• mensagens de sistema com escopo de turno;
• atualizações de progresso;
• fallbacks do lado do servidor;
• controles de ligação de pensamento.

Posso forçar uma chamada de ferramenta?

Não. tool_choice com any ou tool retorna 400. Use auto, nomeie a ferramenta no prompt e defina strict: true, ou use saídas estruturadas para extrair JSON.

Qual é a saída máxima?

A Messages API aceita até 128.000 tokens. Use streaming para respostas grandes. A API de Lotes beta de 300.000 tokens não está listada para o Fable 5.1.

Como vejo as leituras de cache mais baratas?

Verifique usage.cache_read_input_tokens em uma solicitação repetida. No Fable 5.1, esses tokens custam US$ 0,25 por milhão, contra US$ 1 no Fable 5 e US$ 0,50 no Opus 5.

O guia da API Fable 5 ainda é válido?

Em grande parte. O guia da API Fable 5 cobre o mesmo endpoint, mas seus exemplos de uso forçado de ferramentas retornam 400 no Fable 5.1. Ele também não inclui esforço por mensagem nem atualizações de progresso.