✨ 多格式 API

概览

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

OpenAI 格式

/v1/chat/completions 标准格式，兼容性最广

Responses

/v1/responses 原生 Responses 生命周期与事件

Anthropic 格式

/v1/messages 延展思维，原生 Claude 功能

Gemini 格式

/v1beta/models/:model:generateContent Google 生态系统集成

为什么使用多格式？

优点	说明
协议原生 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 格式。

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 特有功能，如延展思维。

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 格式可用：

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 生态系统集成。

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

流式传输

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 决定是否支持。

选择合适的格式

迁移指南

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

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

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

可移植 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 决定是否支持。

快速入门

核心指南

媒体指南

✨ 多格式 API

概览

OpenAI 格式

Responses

Anthropic 格式

Gemini 格式

为什么使用多格式？

格式比较

OpenAI 格式

Anthropic 格式

延展思维（Claude Opus 4.6）

Gemini 格式

流式传输

工具兼容边界

选择合适的格式

迁移指南

来自 OpenAI 官方 API

来自 Anthropic 官方 API

来自 Google AI Studio

可移植 Chat 兼容

Responses 与 Gemini 边界

​概览

OpenAI 格式

Responses

Anthropic 格式

Gemini 格式

​为什么使用多格式？

​格式比较

​OpenAI 格式

​Anthropic 格式

​延展思维（Claude Opus 4.6）

​Gemini 格式

​流式传输

​工具兼容边界

​选择合适的格式

​迁移指南

​来自 OpenAI 官方 API

​来自 Anthropic 官方 API

​来自 Google AI Studio

​可移植 Chat 兼容

​Responses 与 Gemini 边界

概览

为什么使用多格式？

格式比较

OpenAI 格式

Anthropic 格式

延展思维（Claude Opus 4.6）

Gemini 格式

流式传输

工具兼容边界

选择合适的格式

迁移指南

来自 OpenAI 官方 API

来自 Anthropic 官方 API

来自 Google AI Studio

可移植 Chat 兼容

Responses 与 Gemini 边界