Integrando IAs Gratuitas em Aplicações Spring Boot com Spring AI e OpenRouter

Imagem de capa: Integrando IAs Gratuitas em Aplicações Spring Boot com Spring AI e OpenRouter

Você sabia que é possível adicionar inteligência artificial à sua aplicação Spring Boot sem gastar um centavo e com pouquíssimas linhas de configuração? Neste post, vamos explorar como fazer isso usando Spring AI com o OpenRouter — e como base, vamos analisar um projeto real: um gerenciador de tarefas que gera relatórios semanais com IA.

O Problema: Quero IA, Mas Não Quero Pagar (ainda)

A integração com APIs de IA normalmente implica criar uma conta, fornecer cartão de crédito e torcer para não extrapolar os limites gratuitos. O OpenRouter resolve isso de forma elegante: ele é um proxy que agrega dezenas de modelos de IA — incluindo vários completamente gratuitos — e expõe tudo através de uma API compatível com a da OpenAI.

Isso significa que você pode usar a dependência oficial do Spring AI para OpenAI, apontar a base-url para o OpenRouter, e simplesmente escolher um modelo gratuito. Nenhuma mudança de código necessária.

A Chave: Compatibilidade de API

O OpenRouter é propositalmente compatível com a API da OpenAI. Isso quer dizer que qualquer cliente construído para a OpenAI funciona com o OpenRouter sem modificações — inclusive o Spring AI.

Por isso, no projeto de exemplo, a dependência no pom.xml é a do Spring AI para OpenAI:

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

Não existe um spring-ai-starter-model-openrouter. A sacada é justamente usar o starter da OpenAI e redirecionar para o OpenRouter via configuração.

Configuração: Apenas Três Propriedades

Toda a mágica da integração está no application.yaml. São somente três propriedades relacionadas à IA que você precisa definir:

spring:
  ai:
    openai:
      api-key: ${OPENROUTER_API_KEY}
      base-url: https://openrouter.ai/api
      chat:
        options:
          model: google/gemma-3-4b-it:free
  • api-key: sua chave do OpenRouter (obtida em openrouter.ai), injetada via variável de ambiente.
  • base-url: aponta para o OpenRouter em vez da OpenAI.
  • model: O identificador do modelo. Note o :free — isso seleciona a versão gratuita do Gemma 3 da Google, rodando sem custo algum.

Para obter sua chave gratuita: acesse openrouter.ai, crie uma conta e gere uma API key.

O Código: Simplicidade em Dois Arquivos

AiService: O coração da integração

@Service
public class AiService {
    private final ChatClient chatClient;

    public AiService(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    public AiResponse processPrompt(String prompt) {
        try {
            String content = chatClient.prompt()
                .user(prompt)
                .call()
                .content();
            return new AiResponse(content);
        } catch (Exception e) {
            throw new AiServiceException("Failed to process AI prompt");
        }
    }
}

Isso é tudo. O ChatClient é injetado automaticamente pelo Spring AI com base nas suas configurações — ele já sabe que precisa se conectar ao OpenRouter usando o modelo Gemma 3. Nenhum código específico de provedor, nenhuma configuração manual de HTTP.

AiResponse: Um record simples

public record AiResponse(String report) {}

Caso de Uso Real: Relatórios Semanais de Produtividade

O projeto de exemplo usa essa integração para algo prático: analisar as tarefas de um usuário e gerar um relatório semanal personalizado. Veja como o ReportService constrói o prompt:

private String buildPrompt(List<Task> tasks) {
    // Cálculo de métricas
    long completed = tasks.stream().filter(Task::isCompleted).count();
    long pending = tasks.size() - completed;
    long overdue = tasks.stream()
        .filter(t -> !t.isCompleted() && t.getDueDate() != null 
                     && t.getDueDate().isBefore(now))
        .count();

    // Montagem do prompt estruturado
    return String.format("""
        You are a productivity assistant. Analyze this user's current tasks.

        SUMMARY:
        - Total tasks: %d
        - Completed: %d
        - Pending: %d
        - Overdue: %d

        PENDING TASKS:
        %s

        Provide:
        1. A brief overall assessment (1-2 sentences)
        2. Top 3 priorities the user should focus on right now
        3. Any deadline risks or warnings
        4. One motivational tip

        Be concise, friendly, and actionable.
        """, tasks.size(), completed, pending, overdue, pendingTasksList);
}

E o uso é direto:

AiResponse aiResponse = aiService.processPrompt(buildPrompt(tasks));
report.setContent(aiResponse.report());
reportRepository.save(report);

O relatório é gerado pela IA e salvo no banco de dados. Simples assim.

Modelos Gratuitos Disponíveis no OpenRouter

O OpenRouter oferece vários modelos marcados com :free. Alguns dos mais interessantes para aplicações em produção:

  • Google Gemma 3 4B
    • Identificador: google/gemma-3-4b-it:free
    • Pontos fortes: Leve, rápido, bom para tarefas simples
  • Google Gemma 3 12B
    • Identificador: google/gemma-3-12b-it:free
    • Pontos fortes: Mais capaz, ainda gratuito
  • Meta Llama 3.1 8B
    • Identificador: meta-llama/llama-3.1-8b-instruct:free
    • Pontos fortes: Raciocínio avançado
  • Mistral 7B
    • Identificador: mistralai/mistral-7b-instruct:free
    • Pontos fortes: Boa relação tamanho/qualidade

Para consultar a lista atualizada, acesse openrouter.ai/models e filtre por "Free".

Trocando de Modelo ou Provedor

Uma das grandes vantagens dessa abordagem é a portabilidade. Para mudar de modelo, basta alterar uma linha no application.yaml:

  • Gemma para uso geral
    model: google/gemma-3-4b-it:free
  • Llama para melhor suporte ao português
    model: meta-llama/llama-3.1-8b-instruct:free
  • Modelo premium quando necessário
    model: openai/gpt-4o-mini

E se quiser migrar para a API da OpenAI diretamente (pagando), é igualmente simples:

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      # Remova o base-url — Spring AI usa https://api.openai.com por padrão
      chat:
        options:
          model: gpt-4o-mini

Zero mudança no código Java.

Estrutura Completa do Projeto

Para referência, a arquitetura do backend é a seguinte:

backend/
├── pom.xml
└── src/main/
    ├── java/.../AiTaskApp/
    │   ├── ai/
    │   │   ├── dto/AiResponse.java         # Record de resposta
    │   │   └── service/AiService.java      # Integração com Spring AI
    │   ├── reports/
    │   │   ├── controller/ReportController.java
    │   │   ├── model/Report.java
    │   │   └── service/ReportService.java  # Orquestra geração de relatórios
    │   └── infra/job/WeeklyReportJob.java  # Job agendado
    └── resources/
        ├── application.yaml               # Config de dev (com OpenRouter)
        └── application-docker.yaml        # Config de produção (Docker)

O WeeklyReportJob usa @Scheduled para acionar a geração automática de relatórios semanalmente, tornando a experiência completamente automática para o usuário.

Configuração com Docker Compose

O projeto inclui Docker Compose para facilitar o desenvolvimento:

docker-compose.yml (simplificado)

services:
  backend:
    build: ./backend
    env_file:
      - ./backend/.env  # OPENROUTER_API_KEY fica aqui
    environment:
      - SPRING_PROFILES_ACTIVE=docker

Crie um arquivo .env na pasta backend/:

OPENROUTER_API_KEY=sk-or-v1-sua-chave-aqui

Resumo: Por que essa abordagem funciona tão bem

  1. Zero custo inicial — modelos gratuitos do OpenRouter para desenvolvimento e MVPs.
  2. Sem lock-in — troque de modelo ou provedor alterando apenas o application.yaml.
  3. Código limpo — o ChatClient do Spring AI abstrai toda a complexidade de HTTP e serialização.
  4. Escalabilidade — quando seu produto crescer, migrar para modelos pagos é questão de uma linha de configuração.
  5. Compatibilidade — a API da OpenRouter é idêntica à da OpenAI, então toda a documentação e ecossistema do Spring AI se aplicam diretamente.

Próximos Passos

  • Explore o repositório do projeto para ver a implementação completa com frontend React.
  • Consulte a documentação do Spring AI para recursos avançados como streaming, function calling e embeddings.
  • Experimente diferentes modelos gratuitos no OpenRouter para encontrar o melhor para seu caso de uso.

Gostou deste artigo? Compartilhe!