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

> 使用单个 API 密钥接入 OpenAI、Anthropic 或 Gemini 格式

## 概览

AI Sonar 用一个 API 密钥提供四个协议入口：Chat Completions、Responses、Anthropic Messages 和 Gemini 原生协议。只有模型公开该格式且存在同协议 service 路径时，原生入口才可用；原生入口绝不回落 Chat Completions。只有 Chat 入口可以单向编译到兼容的目标协议。

<CardGroup cols={2}>
  <Card title="OpenAI 格式" icon="plug">
    `/v1/chat/completions`
    标准格式，兼容性最广
  </Card>

  <Card title="Responses" icon="bolt">
    `/v1/responses`
    原生 Responses 生命周期与事件
  </Card>

  <Card title="Anthropic 格式" icon="message">
    `/v1/messages`
    延展思维，原生 Claude 功能
  </Card>

  <Card title="Gemini 格式" icon="sparkles">
    `/v1beta/models/:model:generateContent`
    Google 生态系统集成
  </Card>
</CardGroup>

## 为什么使用多格式？

| 优点           | 说明                                          |
| ------------ | ------------------------------------------- |
| **协议原生 SDK** | 原生 SDK 只适用于公开该格式的模型；Chat 仍是覆盖最广的可移植入口       |
| **原生功能**     | 访问格式特定能力                                    |
| **原生优先迁移**   | 行为重要时保留提供商原生路由；已有 OpenAI 风格客户端使用 `/v1` 兼容路径 |
| **统一计费**     | 一个账户，一个 API 密钥，支持所有格式                       |

## 格式比较

| 功能       | OpenAI                  | Anthropic       | Gemini                                  |
| -------- | ----------------------- | --------------- | --------------------------------------- |
| **端点**   | `/v1/chat/completions`  | `/v1/messages`  | `/v1beta/models/:model:generateContent` |
| **认证头**  | `Authorization: Bearer` | `x-api-key`     | `Authorization: Bearer`                 |
| **系统提示** | 在 `messages` 数组中        | 独立的 `system` 字段 | 在 `systemInstruction` 中                 |
| **延展思维** | ❌                       | ✅               | ❌                                       |
| **流式传输** | ✅ SSE                   | ✅ SSE           | ✅ SSE                                   |
| **工具调用** | ✅                       | ✅               | ✅                                       |
| **视觉能力** | ✅                       | ✅               | ✅                                       |

## OpenAI 格式

这是面向已有 OpenAI SDK 集成、可移植聊天或 embeddings 的兼容路由。需要 Claude 或 Gemini 原生行为时，请使用下面的 Anthropic 或 Gemini 格式。

```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!"}
    ]
)
```

**适用场景：**

* 通用场景
* 已有 OpenAI SDK 集成
* 最大兼容性

## Anthropic 格式

原生 Anthropic Messages API。用于 Claude 特有功能，如延展思维。

```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!"}
    ]
)
```

### 延展思维（Claude Opus 4.6）

仅在 Anthropic 格式可用：

```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}")
```

**适用场景：**

* Claude 特有功能
* 延展思维模式
* 原生 Anthropic SDK 用户

## Gemini 格式

原生 Google Gemini API 格式，适用于 Google 生态系统集成。

```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."}]
    }
  }'
```

### 流式传输

```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"}]}]
  }'
```

**适用场景：**

* Google Cloud 集成
* 已有 Gemini SDK 代码
* 原生 Gemini 功能

**Gemini Files 和 Cache：** 原生 Gemini 路径支持 `/upload/v1beta/files`、`/v1beta/files`、`/v1beta/files:register` 和 `/v1beta/cachedContents`。请在后续 `generateContent` 调用中使用返回的公共文件或缓存标识；资源仅限创建它们的 API Key 使用。

## 工具兼容边界

只有 Chat 入口可以在目标能完整表达工具闭环时单向编译函数工具。提供商原生工具必须保留在对应的原生路径上：

* OpenAI Responses 托管和原生工具，例如 `tool_search`、`web_search`、`file_search`、`code_interpreter`、MCP、shell/apply\_patch 和 computer-use 工具，需要 `/v1/responses`。
* Anthropic server/native 工具，例如 `web_search_*`、`web_fetch_*`、`code_execution_*`、`tool_search_*`、bash、computer-use 和 text-editor 工具，需要 `/v1/messages`。
* Gemini 内置工具，例如 `googleSearch`、`codeExecution`、`urlContext`、`computerUse` 以及类似的 `tools` 字段，需要 `/v1beta`。

AI Sonar 不会把原生协议请求降级成 Chat Completions。未知字段和工具组合会 best-effort 透传，由选中的 service 决定是否支持。

## 选择合适的格式

```mermaid theme={null}
graph TD
    A[Which format?] --> B{Need Claude extended thinking?}
    B -->|Yes| C[Use Anthropic Format]
    B -->|No| D{Existing codebase?}
    D -->|OpenAI SDK| E[Use OpenAI Format]
    D -->|Anthropic SDK| C
    D -->|Gemini SDK| F[Use Gemini Format]
    D -->|新项目| G{需要供应商原生行为？}
    G -->|Yes| H[Use native Anthropic or Gemini Format]
    G -->|No| E
```

## 迁移指南

### 来自 OpenAI 官方 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
```

### 来自 Anthropic 官方 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!)
)
```

### 来自 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"}]}]}
)
```

## 可移植 Chat 兼容

当一个客户端需要访问由不同 service 协议承载的模型时，使用 `/v1/chat/completions`。可移植 Chat 请求只有在能完整表达时，才可以单向编译成 Responses、Messages 或 Gemini。Responses、Messages 和 Gemini 原生请求绝不转成 Chat；模型名或厂商名不代表原生协议一定可用。

## Responses 与 Gemini 边界

当前 Responses 入口包含创建、压缩、读取、删除和 SSE；background 只通过 HTTP 运行。收到 `background: true` 时，AI Sonar 会直接尝试所选原生 Responses 路由，由服务端响应决定是否支持，不按厂商或模型名称维护能力开关。WebSocket 只接受 `response.create`，stream 是隐含行为，且不提供 `background` 或 `response.cancel`。删除不是取消。

Gemini 的 ProtoJSON lowerCamelCase 和原始 proto snake\_case 名称都是官方拼写，混合请求也会原样保留。当前入口包括 model list/get、`generateContent`、`streamGenerateContent`、`countTokens`、`embedContent` 和 `batchEmbedContents`，不包括 Interactions 或 Live。未知字段会 best-effort 透传，由 service 决定是否支持。