> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aisonar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ✨ API Protocols

> Choose Chat Completions, Responses, Messages, or Gemini native endpoints

## 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.

<CardGroup cols={2}>
  <Card title="Chat Completions" icon="plug">
    `/v1/chat/completions`
    Portable compatibility entry point
  </Card>

  <Card title="Responses" icon="bolt">
    `/v1/responses`
    Native Responses lifecycle and events
  </Card>

  <Card title="Anthropic Messages" icon="message">
    `/v1/messages`
    Native Messages request and response shapes
  </Card>

  <Card title="Gemini Native" icon="sparkles">
    `/v1beta/models/:model:generateContent`
    Native Gemini ProtoJSON and SSE
  </Card>
</CardGroup>

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.

```python theme={null}
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.

```python theme={null}
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:

```python theme={null}
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.

```bash theme={null}
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

```bash theme={null}
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

```mermaid theme={null}
graph TD
    A[Which protocol?] --> B{Need native state or tools?}
    B -->|Responses lifecycle| C[Use Responses]
    B -->|Messages behavior| D[Use Anthropic Messages]
    B -->|Gemini behavior| E[Use Gemini native]
    B -->|No| F[Use Chat Completions]
    A --> G{Existing native SDK?}
    G -->|Anthropic| D
    G -->|Gemini| E
    G -->|OpenAI Responses| C
    G -->|OpenAI Chat| F
```

## Migration Guides

### From OpenAI Official API

```python theme={null}
# 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

```python theme={null}
# 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

```python theme={null}
# 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:

```python theme={null}
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", ...)
```

<Note>
  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.
</Note>