---
title: "OpenAI Responses API, GPT-5.6, tools, and embeddings"
chapter: "05"
---

# OpenAI Responses API, GPT-5.6, tools, and embeddings

The Responses API is the current unified OpenAI surface for stateful,
multimodal, tool-using applications. Current model guidance identifies the
GPT-5.6 family: Sol for flagship quality, Terra for balanced work, and Luna for
high-volume/latency-sensitive roles.

## Request shape

```java
String result = openAiClient.prompt()
    .system("Answer from approved evidence. Cite source ids.")
    .user(question)
    .tools(new AccountTools(accountService))
    .call()
    .content();
```

Use Spring AI for portable application flow and the provider SDK/API when a
Responses capability is not yet abstracted.

## Hosted and custom tools

OpenAI supports web search, file search, function tools, remote MCP, tool
search, code execution, and other hosted capabilities. Expose only relevant
tools. Schemas must declare required fields and reject extra properties.
Application code authorizes every requested call.

## Model migration

Do not replace every old model with Sol. Preserve each route's quality, latency,
cost, reasoning, endpoint, cache, and tool semantics. Keep model registries,
allowlists, pricing metadata, tests, and UI labels aligned.

## Embeddings

`text-embedding-3-small` defaults to 1536 dimensions and
`text-embedding-3-large` to 3072. The `dimensions` parameter can shorten them.
Changing model or dimensions creates a new vector space and requires
re-embedding plus index migration.

## State and privacy

Decide explicitly whether the API or your application stores conversation
state. Do not place secrets in prompts. Treat provider request IDs, token use,
tool calls, citations, and refusal/abstention as observable events.

## Feynman check

OpenAI provides models and tools. Your application decides which employee may
ask which model to use which tool on which customer account.