Primeira requisição em Ruby com a gem openai: base_url, chave, usage

Sim, a gem oficial openai funciona com a CheapTokens: passe base_url: "https://api.cheaptokens.dev/v1" e sua chave para OpenAI::Client.new, chame client.chat.completions.create e leia o texto em choices.first.message.content. O restante desta página é o script completo, como ler o que volta e o que verificar quando ele não roda.

Digamos que você tenha uma rake task que rotula tickets de suporte, ou um background job que resume uma nota antes de salvá-la. Você quer o SDK oficial, não HTTP feito à mão, e quer ver quantos tokens cada chamada usou. É exatamente este script.

O que você precisa antes de começar#

A página da gem no RubyGems (verificada em 8 de novembro de 2026) lista openai 0.120.0, lançada em 5 de novembro de 2026, Apache-2.0. Ela exige Ruby 3.3.0 ou mais novo; se você está preso no Ruby 3.2, as próprias notas da gem apontam para a linha 0.75.x. O pacote ainda é 0.x e muda rápido, então fixe a versão.

No seu Gemfile:

gem "openai", "~> 0.120.0"

Depois bundle install. Sem Bundler, gem install openai -v 0.120.0 faz o mesmo.

Você também precisa de uma API key da sua conta CheapTokens. Mantenha-a fora do código: coloque-a em uma variável de ambiente e, se a palavra .gitignore é nova para você, este guia sobre como manter chaves seguras é uma leitura de cinco minutos.

export CHEAPTOKENS_API_KEY="sk-your-key"

O script#

Crie ask.rb:

require "openai"

client = OpenAI::Client.new(
  api_key: ENV.fetch("CHEAPTOKENS_API_KEY"),
  base_url: "https://api.cheaptokens.dev/v1"
)

completion = client.chat.completions.create(
  model: "deepseek-ai/DeepSeek-V4-Flash-0731",
  messages: [
    { role: "user", content: "Explain in one sentence what a token is." }
  ]
)

choice = completion.choices.first
puts choice.message.content
puts "finish_reason: #{choice.finish_reason}"
puts completion.usage

Rode com ruby ask.rb. Três coisas merecem uma segunda olhada.

ENV.fetch em vez de ENV[...]. Se a variável estiver faltando, fetch para na hora com um KeyError que a nomeia. ENV[...] passa nil silenciosamente e você recebe um erro de autenticação confuso algumas linhas depois.

base_url: é a única linha que difere dos exemplos da OpenAI no README da gem. Todo o resto é o mesmo código, que é justamente o ponto de uma API compatível com OpenAI. Se a ideia é nova, o que é base_url e como trocar explica com uma analogia de restaurante.

O id do modelo é o completo, deepseek-ai/DeepSeek-V4-Flash-0731. O nome curto de uma tabela de preços não é aceito pela API; pegue ids na documentação da CheapTokens ou em GET /v1/models.

Lendo o que volta#

A resposta é um objeto, não um hash, então você chama métodos nele. O texto fica em completion.choices.first.message.content; esse é o caminho que o README da gem também usa.

Mais duas linhas valem a pena imprimir desde o primeiro dia:

• finish_reason diz por que o modelo parou. stop é um fim normal. length significa que um limite de comprimento cortou a resposta. Se você algum dia vir isso, por que respostas são cortadas e como corrigir.
• usage guarda os tokens pelos quais a chamada foi cobrada: o que você enviou e o que o modelo escreveu. O script imprime o objeto inteiro com puts completion.usage, então você vê os dois números como a API os retornou.

Por que registrá-los? Porque tokens são a conta. Uma pergunta de uma frase com uma resposta de uma frase é minúscula, mas um job que roda mil vezes por dia não é. Tokens de entrada vs saída explica por que o segundo número geralmente custa mais por token.

Quanto custa uma chamada como esta#

DeepSeek-V4-Flash na CheapTokens custa $0.015 por 1M tokens de entrada e $0.10 por 1M tokens de saída, com o mesmo preço em qualquer hora do dia. Pegue um job de rotulagem de tickets: cerca de 300 tokens de entrada, 150 tokens de saída por ticket. Um ticket custa $0.00002. Mil tickets ficam assim, com o preço de referência do OpenRouter na coluna seguinte:

O modelo aceita até 380K tokens de contexto e até 32.768 tokens em uma resposta, então um job de resumo raramente bate em um limite. Se você preferir testar um segundo modelo com o mesmo script, mude apenas a string model: para zai-org/GLM-5.3-Flash (390K de contexto, até 8.192 tokens de saída).

Se não rodar#

A maioria das falhas na primeira execução é uma de cinco coisas. Escolha a que corresponde à sua tela.

Os casos 401 e 404 aparecem com todo SDK, não só Ruby; API 401 ou 404: chave, base URL ou id de modelo errado percorre eles em ordem.

Para onde ir agora#

Você agora tem o menor loop útil: enviar, ler o texto, registrar os tokens. A partir daqui, envolva a chamada em um método e adicione os números de usage ao seu logger. O mesmo padrão existe em outras linguagens se sua stack é mista: Go, Java e C#. A lista completa de modelos e preços está na página de modelos, e a referência da API está na documentação.