Consumo de tokens no Cherry Studio: custos, estimativas e cobranças

Nas estatísticas de consumo de tokens do Cherry Studio, uma imagem pode ter sido gerada enquanto a coluna Cost de Requests continua em branco ou mostra um traço. Isso não significa que a requisição foi gratuita, e um valor exibido também não equivale automaticamente à cobrança do provedor. Encontre o registro em Settings → Usage → Requests —configurações, uso e requisições— e confira a origem do valor, a unidade de cobrança e o débito real para saber se falta configurar um preço, se o cliente não consegue estimar o custo ou se os dois sistemas estão contando chamadas diferentes.

Guarde os registros de requisições e cobranças que você já tem; não é preciso gerar imagens repetidamente apenas para fazer Cost mostrar um número. As explicações de interface e cálculo abaixo se baseiam no código da versão oficial e em alterações já incorporadas. Elas descrevem como o cliente registra os custos, sem comprovar, por meio de chamadas reais, o funcionamento de uma combinação específica de provedor, modelo e conta.

Confira a versão: o preço por imagem entrou na main, mas ainda não na última versão publicada

Em 2026-10-17, a última versão oficial ainda é a v2.1.6; o PR #21892, que adiciona um editor de preços por imagem, foi incorporado à main nessa mesma data. main é a branch de desenvolvimento. Uma alteração incorporada não comprova que a versão oficial instalada no seu computador já inclui o recurso. Consulte o registro da versão oficial e o PR de preços por imagem.

Em 2026-10-16, codeBennyLaw relatou na issue #21870 que, no Windows com a v2.1.6, a configuração de preços só oferecia campos por milhão de tokens e algumas requisições de imagem mostravam um traço em Cost. O relato descreve o ambiente daquele usuário; não permite concluir que todos os modelos de imagem sejam gratuitos. A issue foi encerrada com a incorporação do PR, mas você ainda precisa conferir a versão instalada para identificar a sua interface.

A interface que você tem	O que ela permite	Como proceder
Editor de preços de modelos da v2.1.6	Editar preços de tokens de entrada, saída e cache, inclusive faixas de preço; não há campo de preço por imagem	Conferir as tarifas dos modelos cobrados por tokens; comparar as requisições cobradas por imagem diretamente com os registros do provedor
Build que inclui o PR #21892 e realmente mostra Price unit e Image price	Editar o preço de cada imagem gerada	Confirmar que o provedor cobra por imagem, inserir a tarifa correspondente e verificar uma nova requisição
Build mais recente ou personalizada com outra interface	Os recursos dependem dessa build	Conferir a documentação e os campos disponíveis, sem deduzir a configuração a partir de uma captura de outra versão

A comparação segue o editor de preços da v2.1.6 e o editor com a alteração incorporada. As instruções usam os nomes dos campos em inglês para ajudar na localização; os rótulos mudam conforme o idioma do cliente.

Encontre a mesma requisição em Requests

Identifique a requisição antes de comparar valores. Tenha em mãos a versão do cliente, a configuração do provedor usada naquele momento, o ID exato do modelo e os registros de uso ou cobrança da mesma conta do provedor. Nomes de exibição iguais não bastam para comprovar que se trata do mesmo modelo ou da mesma rota de cobrança.

Abra Settings → Usage → Requests, selecione um período que cubra a requisição e localize-a por Date —data—.
Confira o nome do modelo em cada linha e o nome do provedor logo abaixo. Source indica qual assistente, sessão ou recurso originou a chamada; não indica a origem do custo.
Anote data e hora, Tokens, Cost e moeda. Se o registro não aparecer, volte a ordenar por Date, confira o período e use a opção de carregar mais no fim da lista. A ordenação por Cost também filtra pela moeda selecionada, o que pode excluir os registros sem valor de custo.
Guarde também os registros do provedor para o mesmo período. A data registrada pelo cliente vem do momento em que a chamada terminou. O provedor pode usar outro horário de contabilização ou outro fuso; escolha um intervalo que cubra todo o processamento da requisição.

Os campos e a forma de exibição podem ser conferidos no código oficial da tabela Requests e na lógica de gravação dos registros.

Se a lista inteira estiver vazia, confira primeiro o período, o carregamento dos dados e se a chamada já terminou. Se apenas Cost estiver sem valor, continue verificando os preços e a origem do custo. Cada situação pede uma ação diferente; reinstalar o aplicativo ou apagar o histórico não comprova se houve cobrança pelo provedor.

Cost tem três estados; a coluna Source não identifica a origem do valor

A origem do valor importa mais do que sua aparente precisão. A lógica oficial tenta primeiro aceitar um custo informado pelo provedor que atenda às condições exigidas. Caso isso não seja possível, estima o valor usando a cópia dos preços capturada para aquela requisição. Se nenhuma das opções estiver disponível, o custo fica em branco. Veja a lógica de registro de custos.

Situação no registro	O que significa	Como usar na conferência da cobrança
`costSource` é `provider`	O cliente aceitou um custo retornado pelo provedor; as condições de capacidade declarada do provedor, valor e moeda precisam ser atendidas	Trate-o como uma informação de custo incluída naquela resposta e compare-o também com os débitos da conta do provedor
`costSource` é `computed`	O cliente calculou o valor com base no uso e nos preços capturados naquele momento	Use-o para estimativas e tendências e confira se as tarifas locais correspondem às da sua conta
Cost está sem valor e a origem do custo está vazia	Não há um valor utilizável do provedor e não foi possível concluir o cálculo local	O valor é desconhecido; consulte o débito real nos registros do provedor e não substitua a ausência por zero

Na v2.1.6, um Cost sem valor aparece como -; a versão de main consultada usa Unable to estimate —não é possível estimar— em inglês. A tabela Requests atual não tem uma coluna costSource separada nem uma dica que informe a origem do custo. Não confunda Source com esse campo nem deduza a origem apenas pelo valor exibido. Se a interface não a identificar explicitamente, trate a origem como não especificada. Consulte a tabela na main e os textos da interface em inglês.

Um campo de custo na resposta do provedor não garante que o cliente vá aceitá-lo. A aceitação também depende de condições como a declaração do provedor de que informa custos reais e a possibilidade de determinar a moeda. Você não precisa alterar registros internos para investigar isso; a conferência do débito real continua dependendo da conta do provedor. Veja a explicação oficial sobre o significado dos custos.

Estimativas por tokens: confira a unidade e depois as categorias

Tokens em Requests é um total de uso; não basta multiplicá-lo por uma tarifa única. computed indica apenas que o valor foi calculado localmente, não que a quantidade de tokens também seja uma estimativa local. A função oficial prioriza totalTokens; quando esse total não existe, soma as contagens de entrada e saída disponíveis. Se ambas forem desconhecidas, mantém o valor ausente. Consulte a definição do total de tokens.

Vá a Settings → Model Provider → selecione o provedor → engrenagem do modelo correspondente → More settings e localize a seção de preços. Confira os campos com base nas tarifas atuais daquela conta, modelo e faixa de cobrança:

Input Price / Output Price: são as tarifas por milhão de tokens de entrada e de saída, respectivamente. Se o provedor informar preços por mil tokens, converta-os para a base de um milhão antes de preencher; não copie o número sem ajustar a unidade.
Cache Read Price / Cache Write Price: confira separadamente a leitura e a gravação de cache. Ao deixar um campo em branco no editor atual, o cálculo usa a tarifa de entrada daquela faixa. Preencher com 0 faz o cálculo local usar uma tarifa gratuita; branco não significa grátis.
Faixas de preço: quando as faixas dependem do tamanho da entrada, o cliente escolhe uma usando a quantidade total de entrada da requisição e aplica essa faixa à chamada inteira. Não é um cálculo progressivo em que cada parcela recebe a tarifa de uma faixa diferente. Se faltarem dados de uso ou tarifas necessários, a estimativa pode continuar em branco.

Os campos e o comportamento de gravação estão no editor de preços; o critério de cálculo está na documentação de custos.

Guarde as quantidades por categoria e suas tarifas no mesmo registro de conferência: entrada sem cache × tarifa de entrada + leitura de cache × tarifa de leitura + gravação de cache × tarifa de gravação + saída × tarifa de saída, convertendo cada parcela para a mesma base de um milhão de tokens. Se o total de entrada já incluir os tokens de cache, separe as categorias antes para não contá-los novamente como entrada comum. Da mesma forma, não some os tokens de raciocínio outra vez se eles já estiverem incluídos na saída. Se você não conseguir obter as quantidades por categoria, marque-as como desconhecidas; não use o total Tokens para supor uma cobrança exata.

Confira também a moeda: no editor de preços consultado, $ corresponde a USD e ¥ a CNY, não a JPY. Trocar o símbolo não faz uma conversão cambial. Se o comprovante de recarga ou o extrato bancário estiver na sua moeda local, mas o preço do modelo estiver em dólares americanos, confira primeiro o custo das chamadas em dólares e depois, separadamente, o câmbio e as taxas da recarga. Não some valores em moedas diferentes. Veja o código de correspondência de moedas e gravação de preços.

Depois de alterar um preço, saia do campo e abra novamente o mesmo modelo para confirmar que o valor foi salvo. Confira se a configuração do provedor também tem um multiplicador de preço ou regras por horário, para não multiplicar outra vez uma tarifa real que já inclua esse fator. As requisições antigas mantêm os preços capturados no momento da chamada; alterar o preço atual não recalcula automaticamente o histórico. Consulte o código de multiplicadores e regras por horário e a captura dos preços no momento da requisição.

Cost em branco para imagens: diferencie cobrança por requisição e por imagem

Cobrar por requisição, por imagem ou por tokens de imagem são regras distintas. Uma requisição pode retornar várias imagens. Um valor fixo por requisição não pode ser inserido diretamente como preço por imagem nem nos campos Input Price ou Output Price.

A v2.1.6 já tem a lógica interna de cálculo por imagem, mas o editor de preços do aplicativo para desktop não oferece o campo correspondente. Uma estimativa local exige que os preços capturados durante a execução incluam perImage, com unit igual a image, e que a chamada forneça imageCount. Ter apenas preços por tokens, ou uma unidade pixel, não é suficiente. Consulte as condições do cálculo de custos de imagens.

Se a sua build realmente mostrar os novos campos e o provedor informar claramente que cobra por imagem gerada, configure assim:

Na seção de preços do mesmo provedor e modelo, altere Price unit —unidade de preço— para Image —imagem—.
Em Image price —preço por imagem—, preencha o valor por imagem na moeda correspondente. Saia do campo e abra o modelo novamente para confirmar a gravação.
Deixe o preço em branco se ele for desconhecido. Use 0 somente quando a tarifa realmente for zero; preencher com zero muda a exibição local, mas não impede a cobrança pelo provedor.
O seletor apenas muda qual tarifa você está editando. Os preços de tokens e de imagens são preservados. Ele não cria uma cobrança fixa por requisição nem resolve a estimativa por pixels ou por tokens de imagem.
Confira uma nova geração feita depois da alteração. Quando receber o resultado, anote a quantidade real de imagens, o horário da requisição e o novo Cost e compare com os registros do provedor. O cálculo local deve usar “quantidade de imagens geradas × preço por imagem em vigor no momento da requisição”, considerando os multiplicadores ou as regras por horário aplicáveis. Uma nova requisição de verificação ainda pode ser cobrada; prefira uma geração que você já precise fazer.

Esses passos seguem o novo editor de preços e a função de gravação dos preços. Se os campos não estiverem disponíveis, confira primeiro os registros reais do provedor. Configure a tarifa quando a versão oficial que você instalar incluir expressamente esse recurso.

Mesmo depois de preencher o preço por imagem, uma nova requisição pode continuar sem valor em Cost. Verifique se ela usou outra configuração de modelo, se falta a contagem de imagens, se a informação de moeda está incompleta ou se o contrato real é diferente da cobrança por imagem. O fluxo oficial de tarefas de imagem para provedores personalizados registra imageCount a partir da quantidade de URLs de imagens retornadas; o número de arquivos baixados com sucesso no seu computador não pode substituí-la diretamente. Esse comportamento também não garante que todos os provedores usem a mesma regra de cobrança. Consulte o código de registro das tarefas de imagem.

Confira o débito no provedor e guarde um registro que explique as diferenças

Comece por uma requisição concluída: é mais fácil explicar uma diferença específica do que comparar dois totais mensais. Use a mesma conta do provedor e anote o rótulo ou grupo da chave se isso ajudar a distinguir o uso. Não coloque chaves API completas em capturas de tela ou pedidos de ajuda.

O que guardar	No Cherry Studio	No provedor
Identidade	Versão do cliente, configuração do provedor, nome exibido do modelo e ID exato correspondente	Conta real, ID do modelo e faixa de preços aplicável
Horário	Momento de conclusão da requisição e fuso local	Horário de contabilização, fuso e intervalo que cubra a mesma chamada
Quantidade	Tokens visíveis; quantidade de imagens realmente retornadas pela tarefa	Uso separado por entrada, saída, cache e outras categorias; requisições ou imagens cobradas
Valor	Cost exatamente como aparece, moeda e valores ausentes	Débito real, moeda e estornos ou ajustes visíveis
Correspondência	Sessão ou recurso que originou a requisição	Identificador de requisição ou cobrança fornecido pelo provedor

Se os dois lados mostrarem explicitamente o mesmo ID de requisição do provedor, use-o primeiro para relacionar os registros. Caso contrário, combine conta, modelo, intervalo e quantidades. Os identificadores internos do Cherry Studio seguem uma convenção própria; não presuma que sejam iguais aos IDs do provedor. Veja a estrutura oficial dos registros.

Se você já usa BetterToken, siga as orientações oficiais de uso para consultar o consumo atual e o histórico de cobranças no painel e depois confira modelo, horário, status e tokens com os campos que a página realmente disponibilizar.

Se os valores não coincidirem, siga esta ordem:

As quantidades já são diferentes: confira se outras ferramentas usam a mesma conta ou se uma operação gerou várias chamadas. Retentativas do SDK que o cliente não consegue observar podem não aparecer em Requests; não espere que cada linha corresponda automaticamente a um registro do provedor.
As quantidades coincidem, mas os valores não: confira modelo, unidade por imagem/requisição/token, regras de cache, faixas, moeda, multiplicadores e preços reais da conta. Depois verifique os preços capturados quando a requisição foi feita.
O provedor cobrou, mas Cost está em branco no cliente: preserve o campo em branco e registre “o cliente não consegue estimar; o provedor cobrou”, junto com o valor real. Não substitua o dado ausente por zero.
O cliente não tem registro ou mostra falha, mas o provedor tem um registro: esclareça primeiro as regras do provedor para conclusão, cobrança e estorno. Forneça horário, modelo e identificador de requisição do provedor sem dados sensíveis; não repita imediatamente um lote de requisições para reproduzir o problema.

A documentação oficial define esses registros como dados de análise capturados na medida do possível. Retentativas não observadas, falhas e registros históricos migrados podem afetar a comparação de quantidades. Confira o débito real nos registros do provedor e peça a ele que explique entradas pouco claras; uma célula Cost em branco não permite deduzir essa informação. Consulte a cobertura e os limites dos registros.

Quando a conferência está concluída

Você deve conseguir guardar os registros dos dois lados para a mesma requisição e explicar três pontos: qual modelo e unidade de cobrança foram usados, se o valor do cliente tem origem identificada ou é estimado/desconhecido e quanto o provedor cobrou ao final e por que há diferença. Se alterou um preço local, use uma nova requisição para confirmar que o valor foi salvo e o cálculo funciona. Preserve os valores originais das requisições antigas; não espere que o histórico seja recalculado.

Comece agora com uma requisição de imagem que já exista: anote versão, modelo, horário, quantidade real de imagens, Cost e débito do provedor. Quando conseguir explicar essa requisição, amplie o período para calcular os totais. Se não conseguir, encaminhe os campos ausentes e a requisição correspondente ao provedor ou ao projeto do cliente para investigação.