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

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.