Primeira requisição em Java com openai-java: base URL, chave, uso

Para chamar o CheapTokens a partir do Java, mantenha o SDK oficial openai-java e altere três coisas: a base URL (https://api.cheaptokens.dev/v1), a chave de API e o id do modelo, passado como uma String simples. O programa abaixo envia uma chat completion e imprime a resposta, o finish_reason e o uso de tokens. Ele requer Java 8 ou superior.

Se sua equipe já tem um serviço Spring que conversa com a OpenAI, esta é a migração inteira: nenhum cliente novo, nenhuma classe de requisição nova.

Adicione a dependência#

O README do SDK (github.com/openai/openai-java, verificado em 4 de novembro de 2026) mostra a versão 4.99.0, grupo com.openai, artefato openai-java. O README não informa uma data de lançamento, então consulte o repositório para a versão mais recente antes de copiar isto.

<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>4.99.0</version>
</dependency>

implementation("com.openai:openai-java:4.99.0")

Os artefatos neutros em relação a frameworks rodam em Java 8+, então um JDK corporativo mais antigo não é um bloqueio.

Defina a chave e a base URL fora do código#

O SDK lê duas variáveis de ambiente: OPENAI_API_KEY e OPENAI_BASE_URL. OpenAIOkHttpClient.fromEnv() pega as duas, então a chave nunca vai parar nos seus arquivos-fonte. (As propriedades de sistema openai.apiKey e openai.baseUrl também funcionam e têm precedência sobre as variáveis.)

export OPENAI_API_KEY="your-cheaptokens-key"
export OPENAI_BASE_URL="https://api.cheaptokens.dev/v1"

A base URL padrão do SDK é https://api.openai.com/v1. Pule a segunda linha e sua requisição vai para lá, com uma chave do CheapTokens que ele não conhece. Essa é uma forma de receber um 401 na primeira execução. Para saber onde guardar a chave e como mantê-la fora do git, veja armazene uma chave de API com segurança.

O programa#

Crie FirstRequest.java:

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

public class FirstRequest {
  public static void main(String[] args) {
    OpenAIClient client = OpenAIOkHttpClient.fromEnv();

    ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
        .model("deepseek-ai/DeepSeek-V4-Flash-0731")
        .addUserMessage("Explain in two sentences what a token is.")
        .maxCompletionTokens(300L)
        .build();

    ChatCompletion completion = client.chat().completions().create(params);
    ChatCompletion.Choice choice = completion.choices().get(0);

    System.out.println(choice.message().content().orElse("(no text)"));
    System.out.println("finish_reason: " + choice.finishReason());
    completion.usage().ifPresent(u ->
        System.out.println("input " + u.promptTokens()
            + ", output " + u.completionTokens()));
  }
}

Algumas linhas merecem uma segunda olhada.

• .model("deepseek-ai/DeepSeek-V4-Flash-0731"). Os exemplos do README do SDK usam constantes tipadas como ChatModel.GPT_5_2, mas o builder também tem uma sobrecarga model(String), então qualquer id funciona. Use o id completo da documentação do CheapTokens: o nome curto deepseek-v4-flash-0731 é como os preços são rotulados no site; a API quer o id completo com o prefixo deepseek-ai/. Não tem certeza de um id? Liste os modelos com GET /v1/models.
• .maxCompletionTokens(300L). Um teto para o tamanho da resposta, como um long. O DeepSeek-V4-Flash permite até 32.768 tokens de saída por resposta, então 300 aqui é uma escolha para manter a demonstração curta, não um limite do modelo.
• content() é um Optional. É por isso que o programa tem orElse. Uma resposta feita apenas de tool calls não tem texto.
• usage() também é um Optional. ifPresent o imprime quando o servidor o envia.

Compile e execute como seu build faz (mvn compile exec:java -Dexec.mainClass=FirstRequest, ou uma tarefa JavaExec no Gradle). Você deve receber a explicação de um token, depois uma linha finish_reason: … com stop nela, depois uma linha com as contagens de tokens de entrada e saída. Se finish_reason disser length, a resposta atingiu seu teto de 300 tokens e foi cortada: aumente o número (por que isso acontece).

usage() retorna as contagens de tokens de prompt, completion e total (promptTokens(), completionTokens(), totalTokens()).

Defina os valores explicitamente com o builder#

Testes, ou um serviço com vários clientes, às vezes precisam de valores explícitos. O mesmo cliente, construído à mão:

OpenAIClient client = OpenAIOkHttpClient.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .baseUrl("https://api.cheaptokens.dev/v1")
    .build();

Tudo depois desta linha, os params e a chamada create, permanece exatamente como acima. Continue lendo a chave do ambiente mesmo aqui; um literal de string em um arquivo .java acaba no seu repositório.

Três erros que você vai encontrar primeiro#

Uma variável de ambiente vazia é fácil de passar despercebida em uma IDE: uma configuração de execução iniciada pela barra de ferramentas pode não herdar as variáveis que você exportou no terminal. Se a chave "está definida" mas você ainda recebe 401, adicione as variáveis à configuração de execução. Mais sobre esses códigos: API 401 ou 404: chave, base URL, id do modelo.

Quanto custa uma requisição#

Como você imprime usage, pode precificar a requisição antes de escalá-la. Digamos que seu serviço envie cerca de 200 tokens de entrada e receba 300 de volta. Com os preços de hoje, essa requisição custa $0.000033 no DeepSeek-V4-Flash. Entrada e saída são cobradas juntas, e no total isso é mais barato que o OpenRouter. A tabela repete isso para 1.000 requisições em nossos modelos:

Agora insira seu próprio tráfego. Arraste os sliders para os números da sua primeira linha usage impressa:

Para mais espaço por resposta ou um formato diferente de carga de trabalho, o DeepSeek-V4-Flash oferece uma janela de contexto de 380K e um preço único em qualquer hora do dia; o GLM-5.3-Flash (zai-org/GLM-5.3-Flash) é um substituto direto no mesmo programa: mude o id, nada mais. Os preços atuais de todos os modelos estão na página de preços, e a documentação mostra a mesma requisição em outras linguagens. Fazendo isso em Go? Veja a versão openai-go.