✨ API Protocols

Overview

AI Sonar exposes four protocol surfaces with one API key: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Gemini native REST. Protocol availability is model-specific: a native endpoint is listed only when the model details advertise that request format and a same-protocol route is currently available. A provider or model name alone does not imply native protocol support.

Chat Completions

/v1/chat/completions Portable compatibility entry point

Responses

/v1/responses Native Responses lifecycle and events

Anthropic Messages

/v1/messages Native Messages request and response shapes

Gemini Native

/v1beta/models/:model:generateContent Native Gemini ProtoJSON and SSE

AI Sonar preserves unknown request fields on same-protocol routes and forwards them on a best-effort basis. Their presence in a request does not guarantee that the selected service or model supports them.

Why Multi-Format?

Benefit	Description
Protocol-native SDKs	Keep the request and response shape expected by your SDK
Native features	Access format-specific capabilities
Native-first migration	Keep native provider routes when behavior matters; use `/v1` OpenAI compatibility for existing OpenAI-style clients
Single billing	One account, one API key, all formats

Format Comparison

Feature	Chat Completions	Responses	Messages	Gemini native
Endpoint	`/v1/chat/completions`	`/v1/responses`	`/v1/messages`	`/v1beta/models/:model:generateContent`
Auth Header	`Authorization: Bearer`	`Authorization: Bearer`	`x-api-key`	`Authorization: Bearer`
Native state	No	`previous_response_id`, stored/background responses	Messages request history	Cached content and Gemini resources
Streaming	Chat SSE	Responses SSE / WebSocket	Messages SSE	Gemini SSE
Availability	Widest portable surface	Responses request format + same-protocol route	Messages request format + same-protocol route	Gemini request format + same-protocol route

OpenAI Format

Use this compatibility route for existing OpenAI SDK integrations and portable chat flows. Chat requests can be compiled one-way to a compatible Responses, Messages, or Gemini route. Native Responses, Messages, and Gemini requests are never converted back through Chat Completions.

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.aisonar.dev/v1"
)

# Portable chat works across many models
response = client.chat.completions.create(
    model="claude-sonnet-4-6",  # Claude via OpenAI format
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)

Best for:

General use
Existing OpenAI SDK integrations
Maximum compatibility

Anthropic Format

Native Anthropic Messages API. Required for Claude-specific features like extended thinking. The native Messages endpoint is available only when the model details publish the Messages request format and a same-protocol route is currently available. It does not fall back to Chat Completions.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.aisonar.dev"  # No /v1 suffix!
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a helpful assistant.",  # Separate system field
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

Extended Thinking (Claude Opus 4.6)

Only available in Anthropic format:

message = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "Solve this complex problem..."}]
)

# Access thinking process
for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Answer: {block.text}")

Best for:

Claude-specific features
Extended thinking mode
Native Anthropic SDK users

Gemini Format

Native Google Gemini API format for Google ecosystem integration. Gemini lowerCamelCase field names and original proto snake_case field names are both official ProtoJSON spellings. AI Sonar preserves either spelling, including mixed requests; when both spellings of a field are present, AI Sonar does not merge them or assign a local precedence.

curl "https://api.aisonar.dev/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "Hello!"}]
    }],
    "systemInstruction": {
      "parts": [{"text": "You are a helpful assistant."}]
    }
  }'

Streaming

curl "https://api.aisonar.dev/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Write a story"}]}]
  }'

Best for:

Google Cloud integrations
Existing Gemini SDK code
Native Gemini features

Gemini Files and Cache: /upload/v1beta/files, /v1beta/files, /v1beta/files:register, and /v1beta/cachedContents are available on the native Gemini route. Use the returned public file or cache identifier in later generateContent calls; resources remain scoped to the API key that created them. The supported legacy Gemini surface includes model list/get, generateContent, streamGenerateContent, countTokens, embedContent, and batchEmbedContents. Gemini Interactions and Live are not exposed by this surface.

Responses Format

Use /v1/responses only for models that advertise a Responses contract. The native surface includes create, compact, retrieve, delete, SSE, WebSocket create/continuation, and durable background completion. For background: true, AI Sonar attempts the selected native route directly and lets the service response determine support; there is no provider/model-name capability switch. Delete remains deletion; it is not a cancellation endpoint. Public cancel, input-items, and input-tokens endpoints are not currently exposed. Responses WebSocket accepts response.create events. generate: false creates a local warmup response that can be continued; stream and background are not valid WebSocket request fields. Connections are serial, do not multiplex active responses, and are limited to 60 minutes.

Tool Compatibility Boundary

Chat function tools can be compiled to another protocol when the selected route can represent the complete tool-call loop. Provider-native tools must stay on their native route:

OpenAI Responses hosted and native tools such as tool_search, web_search, file_search, code_interpreter, MCP, shell/apply_patch, and computer-use tools require /v1/responses.
Anthropic server/native tools such as web_search_*, web_fetch_*, code_execution_*, tool_search_*, bash, computer-use, and text-editor tools require /v1/messages.
Gemini built-in tools such as googleSearch, codeExecution, urlContext, computerUse, and similar tools fields require /v1beta.

Native protocol requests are not downgraded to Chat Completions. Field enumerations, tool combinations, parameter ranges, and future extensions are otherwise left to the selected service instead of being rejected by an AI Sonar compatibility validator.

Choosing the Right Format

Migration Guides

From OpenAI Official API

# Before (OpenAI)
client = OpenAI(api_key="sk-openai-key")

# After (AI Sonar)
client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.aisonar.dev/v1"  # Add this line
)
# That's it! Same code works

From Anthropic Official API

# Before (Anthropic)
client = Anthropic(api_key="sk-ant-key")

# After (AI Sonar)
client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.aisonar.dev"  # Add this line (no /v1!)
)

From Google AI Studio

# Before (Google)
import google.generativeai as genai
genai.configure(api_key="google-api-key")

# After (AI Sonar) - Use REST API
import requests

response = requests.post(
    "https://api.aisonar.dev/v1beta/models/gemini-3.5-flash:generateContent",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={"contents": [{"parts": [{"text": "Hello"}]}]}
)

Portable Chat Compatibility

Use Chat Completions when one client must reach models backed by different physical protocols:

from openai import OpenAI

client = OpenAI(base_url="https://api.aisonar.dev/v1", api_key="sk-...")

# These portable chat calls use the same /v1 compatibility SDK:
response = client.chat.completions.create(model="gpt-4o", ...)
response = client.chat.completions.create(model="claude-sonnet-4-6", ...)
response = client.chat.completions.create(model="gemini-3.5-flash", ...)

Native protocol availability is never inferred from a gpt-*, Claude, Gemini, or provider name. Consult the model’s published request formats before choosing a native endpoint.

Getting Started

Core Guides

Media Guides

✨ API Protocols

Overview

Chat Completions

Responses

Anthropic Messages

Gemini Native

Why Multi-Format?

Format Comparison

OpenAI Format

Anthropic Format

Extended Thinking (Claude Opus 4.6)

Gemini Format

Streaming

Responses Format

Tool Compatibility Boundary

Choosing the Right Format

Migration Guides

From OpenAI Official API

From Anthropic Official API

From Google AI Studio

Portable Chat Compatibility

​Overview

Chat Completions

Responses

Anthropic Messages

Gemini Native

​Why Multi-Format?

​Format Comparison

​OpenAI Format

​Anthropic Format

​Extended Thinking (Claude Opus 4.6)

​Gemini Format

​Streaming

​Responses Format

​Tool Compatibility Boundary

​Choosing the Right Format

​Migration Guides

​From OpenAI Official API

​From Anthropic Official API

​From Google AI Studio

​Portable Chat Compatibility

Overview

Why Multi-Format?

Format Comparison

OpenAI Format

Anthropic Format

Extended Thinking (Claude Opus 4.6)

Gemini Format

Streaming

Responses Format

Tool Compatibility Boundary

Choosing the Right Format

Migration Guides

From OpenAI Official API

From Anthropic Official API

From Google AI Studio

Portable Chat Compatibility