sttp-ai: Scala client for OpenAI, Claude, Gemini, and compatible APIs

sttp is a family of Scala HTTP-related projects, and currently includes:

• sttp client: the Scala HTTP client you always wanted!

• sttp tapir: typed API descriptions

• sttp ai: this project. Non-official Scala client wrapper for OpenAI, Claude (Anthropic), Gemini (Google), and OpenAI-compatible APIs (e.g. Azure OpenAI, Ollama, Grok, Groq, OpenRouter). Use the power of ChatGPT, Claude, and Gemini inside your code!

sttp-ai uses sttp client to describe requests and responses as plain, type-safe Scala values — request bodies, response models, JSON schemas, and tool definitions are all derived from case classes via Tapir and circe, with minimal ceremony and no hand-written JSON.

What can you do with sttp-ai?

• Call model APIs directly — OpenAI (chat completions, embeddings, audio, images, and more), Claude (Messages API), and Gemini (Interactions API); each provider has a blocking sync client and a raw-request async client that works with any effect system

• Use OpenAI-compatible providers — Azure OpenAI, Ollama, Grok, Groq, OpenRouter, vLLM and others via the OpenAI client with a custom base URL

• Stream responses — server-sent events streaming for fs2, ZIO, Akka Streams, Pekko Streams, and Ox

• Get structured outputs — JSON-schema-constrained responses parsed straight into your case classes (OpenAI, Claude, Gemini)

• Call tools — let the model invoke functions in your code (OpenAI, Claude, Gemini)

• Run an agent loop — autonomous tool-calling agents with typed tools and typed results, working across all three providers, with tools loadable from MCP servers, testable offline with the agent testkit

Why sttp-ai?

sttp-ai implements the native APIs of all three major providers — OpenAI, Claude, and Gemini — in one library, rather than funnelling everything through an OpenAI-compatibility shim. You bring your own effect system: cats-effect, ZIO, Akka/Pekko Streams, direct-style Ox, or plain blocking calls. Structured-output schemas and tool definitions are derived from case classes instead of written by hand, and the built-in agent loop gives you typed tools and typed results, with tools loadable from MCP servers. Cross-built for Scala 2.12, 2.13 and Scala 3, with Scala Native support (Scala 3) for the core and provider modules.

Getting started

• Quickstart
  • For OpenAI/OpenAI-compatible APIs
  • For Claude (Anthropic) API
  • For Gemini (Google) API

OpenAI

• OpenAI API basics
  • Available features
  • Sync and async clients
  • Basic usage
  • Token limits on reasoning models (GPT-5, o-series)
• Streaming
  • Using fs2 (cats-effect)
  • Using ZIO
  • Using Pekko Streams
  • Using Akka Streams (Scala 2.13)
  • Using Ox (Scala 3)
  • Streaming the Responses API
• Structured outputs / JSON Schema
  • Typed responses with createChatCompletionAs[T]
  • Strict mode and schema normalization
  • Lower-level: building ResponseFormat.JsonSchema yourself
• Tool calling
  • Calling a tool with Tool.Function.withSchema[T]
  • Using the agent loop
• OpenAI-compatible APIs: Azure OpenAI, Ollama, Grok, Groq, OpenRouter
  • Azure OpenAI
  • Ollama
  • Grok
  • Groq
  • OpenRouter
  • Reasoning models
  • Extra body parameters (vLLM and other extensions)
  • Client implementations

Claude

• Claude API basics
  • Claude features
  • Sync and async clients
  • Basic usage
  • Async usage
  • Claude configuration
• Messages API
  • Basic text conversation
  • System messages
  • Image support
  • Advanced parameters
  • Usage and cache accounting
• Structured outputs
  • Typed responses with createMessageAs[T]
  • Lower-level: setting OutputFormat.JsonSchema yourself
  • Manual Schema Definition
• Tool calling
  • Custom tools
  • Answering tool calls
  • Predefined tools
  • Using the agent loop
• Streaming
  • Using fs2 (cats-effect)
  • Using ZIO
  • Using Ox (Scala 3)
• Models and error handling
  • Claude Models API
  • Claude error handling

Gemini

• Gemini API
  • Gemini Features
  • Basic Usage (Gemini)
  • Async Usage
  • Gemini Configuration
• Interactions
  • The Interaction Lifecycle
  • store: server-side persistence
  • Multi-turn conversations
  • Step and Content: the conversation model
• Tool calling
  • Custom Tools
  • Answering function calls
  • Built-in tools
  • Using the agent loop
• Structured outputs
  • Typed responses with createInteractionAs[T]
  • Manual ResponseFormat.JsonSchema
• Streaming
  • Using fs2 (cats-effect)
  • Using Ox (Scala 3)
• Models and error handling
  • Gemini Models
  • Gemini Error Handling

Agent loop

• Agent loop
  • Quick Start
  • Multi-turn conversations
• Agent configuration
  • Agent Configuration
  • Model capabilities
  • Per-iteration model selection
  • Exception Handling
• Interceptors
  • Writing an interceptor
  • Composition and ordering
  • Usage accounting
  • Budgets
  • Bridging the logging sink
  • Migrating from the tool-call hooks
• Agent tools and results
  • Defining tools
  • Deriving tool sets from a service trait
  • Agent Result
  • Typed input and output
  • Composing agents
• MCP tools
  • Lifecycle
  • Tool names
  • Results and errors
  • Backend caveats
• Custom backends and effect systems
  • Custom agent backend
  • Effect systems
• Testing agents
  • Scripting a conversation
  • Asserting without scalatest matchers
  • Effect systems

Other

• JSON Schemas: structured outputs & tools
  • What’s needed
  • The easiest way: derive from a case class
  • Customising the derived schema
  • Building a schema manually
  • Response schemas
  • Union types: structured intent classification
• Timeouts and retries
  • Timeout
  • Retries
• Running examples