Escolha uma versão da API Claude Sonnet para um fluxo de edição

Uma integração de edição carrega mais do que o nome de um modelo: ela pode depender de uma configuração de amostragem, de uma chamada de função forçada ou de um analisador de respostas. Uma troca de versão pode mudar as três coisas antes de mudar a qualidade da edição.

Escolha o Sonnet 5 para uma integração nova, o Sonnet 5.5 quando precisar de respostas com mais de 64.000 tokens, ficção sem censura ou a faixa de esforço mais ampla, e o Sonnet 4.6 para os controles temperature, top_p ou top_k. O Sonnet 5 também aceita chamadas de ferramenta forçadas; o 5.5 não. Trocar apenas o ID do modelo quebra a requisição: o Sonnet 5 e o 5.5 retornam erro 400 para campos de amostragem, e o 5.5 também rejeita a escolha de ferramenta forçada. Remova esses campos por versão antes de comparar qualquer resposta.

A tabela descreve os contratos hospedados da SpicyAPI. O guia de migração do Sonnet 5.5 da Anthropic explica as mudanças nativas entre versões; os nomes de campos e os valores padrão dele não são intercambiáveis com esta interface. Os preços abaixo são em USD por milhão de tokens.

O que cada versão aceita

Os IDs são anthropic/claude-sonnet-4.5/chat, anthropic/claude-sonnet-5/chat, anthropic/claude-sonnet-5.5/chat e anthropic/claude-sonnet-4.6/chat; as páginas são 4.5, 5, 5.5 e 4.6. Os quatro usam o mesmo formato de requisição de /v1/chat/completions e também aceitam stop, tools e parallel_tool_calls.

O Sonnet 4.6 é uma opção intermediária de migração. Ele já tem a janela de 1M e reasoning_effort, mas ainda aceita temperature. Passar do 4.5 para o 4.6 mantém o formato da requisição, aumenta a tarifa de entrada em 11%, eleva o nível de Suavizado para Sem censura e usa esforço de raciocínio médio por padrão; é a passagem do 4.6 para o 5 que remove a amostragem.

O nível de conteúdo importa para ficção e roleplay. O Sonnet 5 é Filtrado; o Sonnet 4.5 e o 4.6 muitas vezes suavizaram ou recusaram pedidos de ficção adulta de maior intensidade nos nossos testes. O Sonnet 5.5 entregou essas cenas testadas sem suavizar nem recusar, o que o torna a melhor escolha aqui para trabalho com ficção adulta. Uma resposta suavizada ainda pode ser cobrada. A SpicyAPI não adiciona nenhum filtro de conteúdo no nível da plataforma; especifique a cena fictícia e as restrições de edição na mensagem de sistema.

Qual escolher

• Integração de texto nova, sem conteúdo adulto: Sonnet 5. Tem as tarifas mais baixas, janela de 1M e três níveis de esforço.
• Entregas longas ou ficção voltada para adultos: Sonnet 5.5. É o único que pode escrever mais de 64.000 tokens em uma resposta, o único com none (sem raciocínio) e é Sem censura.
• Controles de amostragem: continue em uma integração 4.5 fixada ou passe para o 4.6 pela janela de 1M. Chamadas de função forçadas sem amostragem: o Sonnet 5 as aceita com tarifas mais baixas; use-o no lugar do 5.5 quando a chamada precisar ser forçada.
• Um manuscrito inteiro de 300.000 tokens em uma só chamada: isso é uma questão de contexto e custo, tratada no guia de manuscritos longos com o Sonnet 4.6.

Preço: considere o tokenizador e a saída cobrada

O Sonnet 5 e o 5.5 usam um tokenizador mais novo. O guia de migração da Anthropic diz que o mesmo texto produz cerca de 30% mais tokens do que no 4.x, dependendo do conteúdo; por isso, compare o custo por tarefa, não por token. Para um trabalho ilustrativo de 20.000 tokens de entrada e 2.000 de saída no 4.5, suponha um aumento de 30% nas duas contagens no 5 e no 5.5:

Nesse cenário, o Sonnet 5 fica cerca de 9% abaixo do 4.5; a economia não é fixa para todos os documentos. As contagens de saída precisam incluir o raciocínio cobrado. Definir o esforço como low pode reduzir o raciocínio, mas não o desliga; aqui só o 5.5 expõe none. Leia o uso da sua tarefa real antes de tratar a estimativa como orçamento.

As tarifas do Sonnet 5.5 são cerca de 5,3% maiores que as do Sonnet 5, e essa é a diferença com contagens cobradas e categorias de cache idênticas. Reconte os prompts longos após uma mudança de tokenizador: um aumento hipotético de 30% transformaria um prompt de 190.000 tokens em 247.000, ainda abaixo do teto de entrada de 1M, mas com outra fatura.

Teste a edição no Playground

Use esta pequena edição de checagem de fatos antes de migrar um fluxo maior:

Source A: the gallery reopened to staff in April. Source B: the public launch event was in June. Draft: "The gallery reopened to the public in April." Preserve the distinction between staff access and the public event. Return the corrected sentence and one sentence explaining the change.

1. Abra a página do modelo Sonnet 5.5 indicada acima e escolha Playground. Coloque as duas fontes e o rascunho na mensagem do usuário, com "Edit from the supplied sources only" como instrução de sistema.
2. Use esforço low para esta edição de linha. Execute-a depois de revisar o custo e confira se a resposta mantém abril para o acesso da equipe e junho para o evento público, sem inventar uma data exata.
3. Teste o mesmo texto no Sonnet 5 para um fluxo de edição mais barato e sem conteúdo adulto. Mantenha o texto-fonte inalterado para poder avaliar a edição em si.

Escolha uma versão para a edição que você realmente entrega

Para a revisão de um capítulo de 700 palavras com um pacote de fontes de 20.000 tokens, nenhuma dessas versões precisa de seu contexto ou de sua saída máxima. A escolha útil é se os controles da requisição e a adequação do conteúdo servem. O Sonnet 5 é o ponto de partida de menor preço para uma edição comum. Um editor de ficção adulta também deve considerar o nível Filtrado dele antes de torná-lo o padrão para o manuscrito inteiro. Por isso, uma sinopse não explícita e a revisão de uma cena madura na mesma aplicação podem exigir modelos diferentes.

Se você quer três formulações alternativas no 4.5 ou no 4.6, os controles de amostragem deles oferecem uma forma aceita de variar a geração. Isso não significa que aumentar a temperatura conserte uma lógica de história ruim. Um parágrafo que dá a um personagem uma informação que ele ainda não conhece precisa da regra de conhecimento e do trecho-fonte; não precisa de mais aleatoriedade. No 5 ou no 5.5, não invente um campo de amostragem equivalente. Peça três alternativas com abordagens declaradas diferentes: diálogo mais curto, menos exposição ou uma revelação mais tardia.

Para uma edição assistida por ferramenta, imagine que o rascunho cita o empregador de um personagem, mas o banco de dados oficial da série tem o registro atual. No 4.5, no 4.6 ou no 5, a escolha de ferramenta exposta pode exigir uma consulta. No 5.5, auto pode produzir uma resposta sem a consulta. Se sua aplicação precisa verificar o empregador, faça a leitura antes de pedir a edição ou não aceite uma resposta sem o resultado de consulta exigido. Uma frase no prompt não dá a auto a mesma garantia de uma chamada forçada. Os exemplos nativos de thinking ou output_config do guia de migração da Anthropic não devem ser colados sem alteração nesta requisição.

O resultado significativo do exemplo é uma frase que preserve tanto o acesso da equipe em abril quanto o lançamento público em junho. "The gallery reopened in June" é amplo demais se a equipe já podia entrar em abril. "The gallery held its public launch in June, after reopening to staff in April" é uma correção humana aceitável. Uma versão nova que produz uma redação mais bonita, mas perde essa distinção, não melhorou o trabalho de edição.

Migre a requisição

Uma integração 4.5 pode usar temperature: 0.2, top_p: 0.9 e uma função submit_edit forçada. Passar para o 5 rejeita os campos de amostragem; passar para o 5.5 rejeita tanto a amostragem quanto a escolha de ferramenta forçada.

1. Remova a amostragem no 5 e no 5.5. Apague temperature, top_p e top_k dessas requisições. Campos não suportados retornam 400 unsupported_parameter antes de uma tarefa ser criada ou cobrada; mantenha uma lista de campos permitidos por modelo em vez de enviar um único objeto de parâmetros compartilhado.
2. Use uma ferramenta automática no 5.5. Mantenha a função submit_edit e peça-a no prompt de sistema, mas defina tool_choice como auto. Não existe response_format aqui e o 5.5 pode pular a função, então valide os argumentos retornados. Se seu fluxo exige uma chamada forçada, o Sonnet 5 a suporta com tarifas mais baixas.
3. Deixe espaço para a resposta. O raciocínio consome parte de max_tokens: um limite de 1.024 tokens pode acabar antes de aparecer texto visível. Use esforço low para uma edição de linha e high para fontes conflitantes. O Sonnet 5 para em high; ele não aceita xhigh nem max do 5.5.
4. Use streaming em edições mais longas. O exemplo curto abaixo usa uma resposta JSON normal. Chamadas grandes podem ultrapassar o limite de cerca de 100 segundos da borda da rede; use streaming nelas e monte texto e argumentos de ferramenta separadamente. O guia de texto e streaming cobre eventos de conclusão e uso.
5. Termine a conversa com uma mensagem do usuário. Ao migrar do 4.5, mova para a instrução de sistema a abertura ou a dica de formato desejada, em vez de terminar com um prefill do assistente.

Os nomes dos esforços também mudam de significado. A Anthropic recalibrou os níveis do 5.5, então high não é equivalente entre versões. A SpicyAPI define medium como padrão tanto no 5 quanto no 5.5, enquanto a API nativa do 5.5 da Anthropic usa high como padrão. Para respostas curtas e limpas, prefira low a none: com none, o 5.5 pode resolver a pergunta no texto visível. none continua útil para falas rápidas em personagem.

Execute e valide a edição

Salve isto como sonnet_edit.py, defina SPICY_API_KEY a partir de API Keys e execute python3 sonnet_edit.py. Ele usa a biblioteca padrão do Python. O Sonnet 5.5 foi escolhido aqui para demonstrar a migração para ferramenta automática; trocar apenas o modelo para o Sonnet 5 também aceita esses campos. É uma chamada de texto paga, não uma tarefa de geração de mídia. As receitas de chat cobrem integrações de múltiplos turnos e com streaming.

import json
import os
import sys
import uuid
from urllib.error import HTTPError
from urllib.request import Request, urlopen

def read_reply(resp: dict, *, require_edit_tool: bool = False) -> dict:
    if resp.get("error"):
        raise RuntimeError("API error")
    choices = resp.get("choices") or []
    if not choices:
        raise RuntimeError("no choices in response")
    choice = choices[0]
    finish = choice.get("finish_reason")
    if finish not in {"stop", "tool_calls"}:
        raise RuntimeError(f"incomplete or rejected reply: {finish}")
    msg = choice.get("message") or {}
    calls = msg.get("tool_calls") or []
    if calls:
        if len(calls) != 1:
            raise RuntimeError("expected one submit_edit call")
        call = calls[0]
        if call.get("type") != "function" or not isinstance(call.get("id"), str) or not call["id"]:
            raise RuntimeError("missing function type or call ID")
        fn = call.get("function") or {}
        if fn.get("name") != "submit_edit":
            raise RuntimeError("unexpected function")
        args = json.loads(fn.get("arguments") or "")
        if not isinstance(args, dict) or any(
            not isinstance(args.get(key), str) or not args[key].strip()
            for key in ("sentence", "reason")
        ):
            raise RuntimeError("sentence and reason must be nonempty strings")
        return {"kind": "tool", "call": calls[0], "edit": args}
    if require_edit_tool:
        raise RuntimeError("model skipped submit_edit")
    text = msg.get("content")
    if finish != "stop" or not isinstance(text, str) or not text.strip():
        raise RuntimeError("empty or unfinished text")
    return {"kind": "text", "text": text}


def main() -> None:
    body = {
        "model": "anthropic/claude-sonnet-5.5/chat",
        "reasoning_effort": "low",
        "max_tokens": 8192,
        "messages": [
            {"role": "system", "content": "Edit from the supplied sources only. Reply by calling submit_edit."},
            {"role": "user", "content": 'Source A: the gallery reopened to staff in April. Source B: the public launch event was in June. Draft: "The gallery reopened to the public in April." Keep the staff/public distinction.'},
        ],
        "tools": [{"type": "function", "function": {
            "name": "submit_edit",
            "description": "Return the corrected sentence and the reason.",
            "parameters": {
                "type": "object",
                "properties": {"sentence": {"type": "string"}, "reason": {"type": "string"}},
                "required": ["sentence", "reason"],
            },
        }}],
        "tool_choice": "auto",
    }
    request = Request(
        "https://api.spicyapi.ai/v1/chat/completions",
        data=json.dumps(body).encode(),
        headers={
            "Authorization": f"Bearer {os.environ['SPICY_API_KEY']}",
            "Content-Type": "application/json",
            "Idempotency-Key": str(uuid.uuid4()),
            "User-Agent": "sonnet-edit-example/1.0",
        },
    )
    try:
        with urlopen(request, timeout=80) as response:
            task_id = response.headers.get("X-Spicy-Task-Id")
            if task_id:
                print(f"Task ID: {task_id}", file=sys.stderr)
            result = read_reply(json.load(response), require_edit_tool=True)
    except HTTPError as error:
        task_id = error.headers.get("X-Spicy-Task-Id")
        print(f"HTTP {error.code}; task ID: {task_id or 'not returned'}", file=sys.stderr)
        raise
    print(json.dumps(result["edit"], indent=2))


if __name__ == "__main__":
    main()

Uma edição válida mantém abril para o acesso da equipe e junho para o evento público. O analisador rejeita uma resposta vazia, um truncamento e uma chamada de função ignorada ou malformada; argumentos válidos ainda precisam dessa checagem de fatos. Um relato de migração do Sonnet descreve um fallback vazio chegando aos usuários como resultado bem-sucedido.

Se finish_reason for length, use mais espaço de saída ou uma tarefa menor em uma nova chamada. Preserve qualquer resultado parcial e o ID da tarefa antes de gastar de novo. Em um fluxo de ferramentas de múltiplos turnos, devolva o resultado da ferramenta com o tool_call_id correspondente antes do próximo turno. Inclua nas suas verificações de migração uma contradição, um fato inalterado, uma resposta "unknown" e um resultado de ferramenta "no match"; para extrações mais longas, verifique se as seções exigidas estão presentes, além de o JSON ser válido.

Deixe um Agent preparar a integração

Use um Agent quando quiser que ele adapte um editor existente em vez de colar uma requisição você mesmo. Mantenha as mesmas fontes da galeria e o mesmo rascunho na tarefa dele.

• CLI: depois de definir SPICY_API_KEY, deixe-o inspecionar o contrato escolhido com npx @spicyapi/cli models get anthropic/claude-sonnet-5.5/chat --json. O guia da CLI documenta esse comando somente leitura.
• MCP: com o servidor MCP da SpicyAPI conectado, peça: "Use spicyapi_model_get for anthropic/claude-sonnet-5.5/chat, then adapt my gallery edit to its accepted effort and tool-choice settings. Prepare the request without running it."
• Skill: instale o Skill oficial da SpicyAPI com npx skills add spicyapi-ai/spicy-skill, inicie uma nova sessão do Agent e peça: "Use the SpicyAPI Skill to migrate my gallery editor from Sonnet 4.5 to 5.5. Keep the source facts and validate submit_edit; show me the request before calling it."

CLI e MCP fornecem a descoberta de modelos para este fluxo de texto; a edição em si usa /v1/chat/completions por meio do programa acima ou do cliente HTTP do seu Agent. Defina um limite de gastos na chave de API antes de delegar edições repetidas.

FAQ

O Sonnet 5.5 é mais barato que o Sonnet 5?

Não. Ele custa cerca de 5,3% a mais por token ($2 e $10 contra $1,90 e $9,50). Uma tarefa só custa tanto a mais quando as contagens cobradas e as categorias de cache são idênticas. Esse extra compra o teto de resposta de 128.000 tokens, os esforços none e xhigh e o nível Sem censura.

O Sonnet 5.5 é melhor que o Opus 5.5?

Não necessariamente. O Opus 5.5 custa $3,60 de entrada e $18 de saída na SpicyAPI, cerca de 1,8 vez o Sonnet 5.5, com a mesma janela de 1M e o mesmo teto de saída de 128.000. Comece pelo Sonnet 5.5 e suba só se as suas passagens mais difíceis voltarem erradas; o guia «Claude Opus 5.5 para roleplay NSFW» cobre esse caminho.

Posso manter temperature no Sonnet 5.5?

Não. Use o esforço de raciocínio para a profundidade e coloque as regras de tom no prompt de sistema. Se você precisa de controles de amostragem, as opções são 4.5 e 4.6.