opper-api

技能版本 2026-10-21。 这是本地安装的副本，可能不是最新版本。每个会话开始时，获取一次 https://skills.opper.ai/versions.json，并将其中的 "opper-api" 条目与 2026-10-21 进行比较。如果两者不同，请阅读 https://skills.opper.ai/opper-api/SKILL.md，并在本会话剩余时间内改用该版本；同时告知用户一次，其已安装的 Opper 技能已过期（可通过 npx skills update 更新，或在手动克隆的副本中执行 git pull）。请勿编辑已安装的文件。如果获取失败，请继续使用此副本。

opper 的子技能——请先从这里开始，了解发现和设置指导。 来源：https://github.com/opper-ai/opper-skills/blob/main/opper-api/SKILL.md

Opper API

Opper 是位于 LLM 提供商前方的网关，也是用于管理你在其上构建内容的控制平面。该网关只需建立一个连接，即可访问所有主要提供商提供的 700 多种模型（OpenAI、Anthropic、Google、Mistral，等等）；服务托管于 AWS Stockholm，通过 ISO/IEC 27001:2022 认证并符合 GDPR 要求，按提供商价格收费，不对 token 加价（购买额度时收取 3% 费用，使用控制平面功能时收取 5.5% 费用；详见 opper.ai/pricing.md）。除此之外：

• 日志和追踪：每次调用都会记录在 Logs 中，包含模型、提供商、token 数量、费用、延迟和状态，适用于所有套餐；启用追踪（即数据保留规则）后，调用的追踪记录还会保留输入、输出以及触发的所有规则。
• 规则（控制平面套餐），按组织设置并在项目级别进一步收紧：支出限额（月度预算、按项目、角色、用户或密钥设定的上限）、数据保留（追踪记录保留 1 至 30 天，或设为 0）、模型访问权限（提供商、服务路由、位置、制造商、国家/地区、模型、零数据保留）、检查（标记、脱敏或拦截内容，评估回答）和路由（池化模型的提供商顺序）。API 将其归类为 comply、guard、observe 和 route 几种规则；详见 docs.opper.ai/control-plane/rules/overview。
• 公司级证明材料（ISO/IEC 27001:2022 证书、安全控制措施、平台子处理方和模型提供商、DPA、隐私政策）可在信任中心 trust.opper.ai 查阅。

https://api.opper.ai 上的 HTTP API 是基础。Opper 没有供新代码使用的自有 SDK：应用代码使用已有的提供商 SDK（OpenAI、Anthropic、Google Gen AI）或其 Agent 框架，并将其指向 https://api.opper.ai/v3/compat。旧版 opperai 包已停止开发；请勿推荐这些包。

概念介绍：docs.opper.ai/overview/about。快速入门：docs.opper.ai/overview/quickstart。

选择你的端点

一个网关，一个密钥。根据你要构建的内容选择端点——底层的路由、治理和追踪都相同：

• 文本生成 / 聊天 / 从 OpenAI、Anthropic、Google 或 OpenResponses 迁移：使用 /v3/compat/... 下的兼容端点。将 SDK 的基础 URL 指向这里，保留代码，只更换密钥。这是主要路径。请参阅 references/compatibility.md 和 references/migration.md。
• 结构化输出（模型生成类型化 JSON）：在任意兼容聊天端点上使用标准的 response_format: {type: "json_schema"}，无需单独的端点。
• 仍在使用 Opper 自有的 /call（POST /v3/call，或 opperai SDK 的 opper.call）？它即将停用——请迁移到使用 response_format 的兼容聊天端点。字段逐项映射方式以及 opperai SDK 的其他内容，请参阅 references/migration.md。
• 媒体生成（图像、音频 / TTS / STT、视频、OCR）、文件和实时语音：这些使用单独的接口——请切换到 opper-multimodal skill。快速索引：图像 POST /v3/images，音频 POST /v3/audio/{speech,transcriptions}，视频 POST /v3/videos（异步），OCR POST /v3/ocr，文件 /v3/files，实时语音 wss://api.opper.ai/v3/realtime。
• Roundtable（将一个提示词发送给多个模型，然后汇总或比较结果）：POST /v3/roundtable（测试版）。
• 构建 Agent（多步推理、工具调用、多 Agent、MCP）：使用用户的 Agent 框架并指向兼容端点，或在 /v3/compat/chat/completions 上使用简单的工具调用循环。Opper Agent SDK 已停止维护；请勿推荐。各框架的接入方式和示例：references/agents.md。

实时 v3 规范是事实依据

针对任何 API 问题——端点、参数、字段、功能、合规属性、查询标志——如果本技能未能立即解答，默认工作流程是：搜索规范。 不要猜测，不要从文档页面推断，也不要退而使用可浏览目录。两种格式都无需身份验证，且都是权威依据：

curl -s https://api.opper.ai/v3/openapi.yaml   # YAML, easier to grep
curl -s https://api.opper.ai/v3/openapi.json   # JSON

示例——“哪些 Opper 模型支持 ZDR？”：

# 1. Grep the spec for the term.
curl -s https://api.opper.ai/v3/openapi.yaml | grep -i -n zdr
# → reveals compliance.zdr on every GET /v3/models item — no include, no API key

# 2. Call the endpoint and derive the answer from the facts.
curl -s https://api.opper.ai/v3/models \
  | jq -r '.models[] | select(.compliance.zdr.logging == false and .compliance.zdr.moderation != true) | .id'

# Or print the facts per model and decide yourself.
curl -s https://api.opper.ai/v3/models | jq '.models[] | {id, zdr: .compliance.zdr}'

compliance.zdr 是一个包含五项三态事实的对象——logging、moderation、caching、training、subprocessors——每项的值可以是 true（内容会被保留 / 进入该处理流程）、false（不会）或 null（尚未确定）。没有汇总字符串；请按需推导。“默认支持 ZDR”指 logging == false and moderation != true。同一对象位于 /v3/compat/models 条目的 opper 块中；提供密钥时，也会出现在路由对象上（?include=route、/v3/providers?include=routes）。

同样的方法可回答任何“X 在哪里”的问题——搜索规范，按照 schema 找到端点，然后调用它。

身份验证

Authorization: Bearer $OPPER_API_KEY

服务 URL：https://api.opper.ai（/v3 或 /v2 前缀属于各路径的一部分）。使用 Authorization: Bearer；兼容 OpenAI 的端点不接受其他方式。兼容厂商协议的路由也会读取对应厂商自己的请求头（Anthropic Messages 端点使用 x-api-key，Gemini 端点使用 x-goog-api-key），因此 Anthropic 和 Google SDK 只需使用各自常规的 API 密钥即可。请在 platform.opper.ai 获取密钥。

有少数端点设置了 security: []，无需密钥：/health、/v3/openapi.yaml、/v3/openapi.json、/v3/models。

标准示例——兼容聊天补全

主要路径是兼容 OpenAI 的聊天端点。任何指向 /v3/compat 的提供商 SDK 都可以使用相同的格式。

curl -s -X POST https://api.opper.ai/v3/compat/chat/completions \
  -H "Authorization: Bearer $OPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

响应采用提供商的原生格式（此处为 OpenAI 的 chat.completion）。模型地址格式为 provider/model；你可以通过任意兼容接口调用任意模型。

结构化输出

要获取类型化 JSON，请添加 response_format——无需单独的端点：

curl -s -X POST https://api.opper.ai/v3/compat/chat/completions \
  -H "Authorization: Bearer $OPPER_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [{"role": "user", "content": "Extract entities: Tim Cook announced Apple’s Austin office."}],
    "response_format": {"type": "json_schema", "json_schema": {"name": "entities", "schema": {
      "type": "object",
      "properties": {
        "people":    {"type": "array", "items": {"type": "string"}},
        "locations": {"type": "array", "items": {"type": "string"}}
      },
      "required": ["people", "locations"]
    }}}
  }'

模型的 content 会以 JSON 字符串的形式返回，并根据 schema 进行验证。流式传输：添加 "stream": true 并读取 text/event-stream（事件以 data: 为前缀，以 [DONE] 结束）。

通过代码使用提供商 SDK

使用用户已有的 SDK。将其 base URL 设置为 https://api.opper.ai/v3/compat，并将 Opper 密钥作为 API 密钥传入；调用代码保持不变。X-Opper-Name 用于为调用命名，以便进行追踪。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.opper.ai/v3/compat",
    api_key=os.environ["OPPER_API_KEY"],
    default_headers={"X-Opper-Name": "summarise"},
)
resp = client.chat.completions.create(
    model="openai/gpt-5-mini",
    messages=[{"role": "user", "content": "Summarise in two sentences: ..."}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.opper.ai/v3/compat",
  apiKey: process.env.OPPER_API_KEY,
  defaultHeaders: { "X-Opper-Name": "summarise" },
});
const resp = await client.chat.completions.create({
  model: "openai/gpt-5-mini",
  messages: [{ role: "user", content: "Summarise in two sentences: ..." }],
});

• 类型化输出：Python 使用 client.chat.completions.parse(..., response_format=YourPydanticModel) 并读取 message.parsed；TypeScript 传入 response_format: { type: "json_schema", json_schema: { name, schema } }（Zod v4：z.toJSONSchema(...)），并解析 message.content。
• Anthropic SDK（Python / TS）：使用相同的 base URL；它会附加 /v1/messages。Google Gen AI SDK：generateContent / streamGenerateContent 路由位于 /v3/compat/v1beta/models/... 下。两者都会发送各自的密钥请求头，Opper 均可接受。详情请参阅：references/compatibility.md。
• 任何 SDK 调用任何模型：模型 ID 是 Opper 的 provider/name，因此 OpenAI SDK 可以调用 Claude，Anthropic SDK 也可以调用 GPT。
• Agent：使用用户的框架（OpenAI Agents SDK、Vercel AI SDK、Mastra、LangChain，……）并配置相同的 base URL；请参阅 references/agents.md。

模型 — GET /v3/models（无需身份验证）

这是使用此技能最常见的原因之一。实时端点提供最新列表，切勿将模型名称硬编码：

curl -s https://api.opper.ai/v3/models

两个 URL，面向两类用户：

• 在代码中：https://api.opper.ai/v3/models — 用于程序化发现，返回 JSON。
• 与用户交流时：opper.ai/models — 可浏览的人类可读目录。推荐或讨论模型时，请链接此页面。

默认响应较精简，但每个条目都包含一个 compliance 区块，其中包括 residency、country、inference_location、storage_location、zdr（上文所述对象）、training、logging、moderation、caching、content_storage、dpa_available、third_party_access、transfer_mechanism、route_id。无需 API 密钥即可解答大多数有关 ZDR / 数据驻留 / GDPR 的问题。如需获取每条路由的证据或基准数据，请添加 ?include=：

include=	添加内容	包含的信息
route（需要 API 密钥）	每个模型对应的 route 对象	完整的服务路由记录：包含 retention_days / storage_location / human_review 的 data_handling.{training,logging,moderation,caching}、data_handling.subprocessors_read_content、gdpr.{residency,dpa_available,transfer_mechanism}、verification.status、sources、last_verified_at、underlying_maker，以及与 compliance.zdr 相同的 zdr 对象
maker（公开）	maker	原始权重的创建者（例如，Llama 的 meta、Mistral 的 mistral）
benchmarks（公开）	benchmarks	来自 artificialanalysis.ai 的公开评分
policy（需要 API 密钥）	每个模型对应的 policy 对象	调用者的模型访问规则和权限是否允许运行此条目：allowed、blocked_by（org / project / entitlement）、reason（与 403 响应中相同的说明）。列表不会经过筛选

可用逗号组合，例如 ?include=route,benchmarks。需要保留天数、存储位置、验证状态或声明依据时，请使用 include=route：compliance 是摘要，route 是证据。

这些字段描述的是某条路由上的一个模型。有关 Opper 公司本身的问题（认证、安保措施、子处理方列表、DPA、隐私政策、安全问卷），请查阅 trust.opper.ai：提供该链接即可，无需复述那些可能变化的数据。

按能力和类型筛选：?capability=vision / ?capability=pdf（支持图像 / PDF 的聊天模型）、?type=image|tts|stt|video。下方的模态端点也提供相应范围的发现列表。

参考资料：docs.opper.ai/capabilities/models。

model 字符串——池、固定目标、别名和路由

GET /v3/models 每个提供商返回一行，而不是每个模型返回一行。model 字段可以使用以下四种形式，无需特殊标头或标志：

形式	示例	指向的对象
裸模型名称——一个池	"kimi-k3"	提供该模型的所有提供商。Opper 会选择其中一个，其余作为故障转移选项
提供商限定 ID——一个固定目标	"tensorx/moonshotai/kimi-k3"	精确指定这一行对应的提供商，不进行故障转移
组织别名——你自己的列表	"my-flash"	你定义的有序列表：主选项在前，后接回退选项。早于路由推出；已有别名的组织仍可使用（通过 /v2/models/aliases 进行增删改查）
动态路由——已部署的图	"dynamic/my-route"	池、固定回退顺序、分类、分支和版本管理。适用于构建可命名并重复使用的回退链。可在平台 UI 中构建，也可通过 /management/v1/dynamic-routes 和管理 API Key 构建（详见公开规范）——但调用路由只需使用常规项目密钥

**这些都不是默认的正确选项——请根据使用场景选择。**需要确定性（评估、保证使用特定司法辖区或价格、特定提供商行为）时，使用固定目标；想获得冗余且无需费心选择时，使用池；需要自己的回退链，或决策取决于请求时，使用路由。不要提议新增别名；新的链应指向路由。model 本身始终是字符串（传入数组会返回 400），但请求也可以在单独的 models 数组中携带自己的回退列表（OpenRouter 格式：model 中放主选项，models 中放其余选项，最多 10 个；前一个选项在运行时失败后，按顺序尝试后续选项；不能与 dynamic/<name> 同时使用）。未知 ID 会被直接拒绝（404 model_not_found），不会继续尝试其他选项。一次性请求链使用 models，需要命名并重复使用的链则使用路由。

具体来说，对于池：每一行中的 model 是组键（也是你调用时使用的裸名称），pooled 表示该行是否响应这个名称。pooled: false 的行仍可通过显式 ID 完整调用——它们只是不参与裸名称路由，通常是因为上下文窗口较小，或是经过延迟优化但价格更高的变体。

有两点常让人意外：

• 响应中的 model 字段会回显你发送的内容——裸名称、别名或 dynamic/ 路由都会原样返回，因此它无法显示实际运行的提供商。跟踪记录可以：span.meta.model 包含解析后的 provider/provider_model_id。对于路由，响应标头 X-Opper-Route-Model 会直接给出答案。
• **不带 X-Opper-Trace-Id 的相同请求都会落到同一个提供商。**这是刻意设计的会话亲和性（以你的 API Key 为键，窗口为 30 分钟，旨在提升提示词缓存的局部性），并非轮询故障。为每个请求发送唯一的跟踪 ID，即可将请求分散到不同提供商。

完整机制——四种形式如何组合、选择顺序、故障转移，以及别名和路由管理：参见 references/model-routing.md。

兼容服务商的端点 — 位于 /v3/compat/...

可直接替换多种 LLM API。最简单的迁移方式：将 SDK 的基础 URL 指向 https://api.opper.ai/v3/compat，使用你的 Opper API 密钥，现有代码即可继续运行。完全符合各上游服务商的规范；遇到不熟悉的载荷时，请参阅其规范。

端点	兼容对象	Opper 文档
POST /v3/compat/chat/completions	OpenAI Chat Completions	文档
POST /v3/compat/responses	OpenAI Responses	文档
POST /v3/compat/openresponses	OpenResponses	文档
POST /v3/compat/v1/messages	Anthropic Messages	文档
POST /v3/compat/v1beta/interactions	Google Interactions	文档
POST /v3/compat/embeddings	OpenAI Embeddings	（参见规范）

Curl 示例和 SDK 重新配置技巧：references/compatibility.md。这些端点也支持视觉和 PDF 输入——向具备 vision / pdf 能力的模型发送 image_url / file 内容部分（参阅 opper-multimodal skill，以及 docs.opper.ai/build/multimodal/vision-pdfs）。

媒体生成、文件和实时通信 → opper-multimodal skill

媒体生成（图像、音频 TTS/STT、视频、OCR）、/v3/files 存储 API、向模型输入图像/PDF，以及实时双向语音，属于独立的功能范畴，拥有各自专用的端点。它们共用此网关的密钥、治理和追踪功能，但请求/响应约定有所不同，因此归属各自的 skill：opper-multimodal（SKILL.md）。

快速概览（有关格式，请获取规范或参阅该 skill）：图像 POST /v3/images（同步，可选异步）；音频 POST /v3/audio/speech（TTS）+ POST /v3/audio/transcriptions（STT）；视频 POST /v3/videos（异步 — 轮询 GET /v3/artifacts/{id}/status）；OCR POST /v3/ocr；文件 /v3/files；实时通信 wss://api.opper.ai/v3/realtime（通过 POST /v3/realtime-sessions 获取浏览器票据）。每种媒体功能都有各自的专属发现列表（GET /v3/images/models、/v3/videos/models、/v3/audio/models、/v3/ocr/models）。

服务端工具（opper:web_search 等）则有所不同——它们使用兼容聊天端点，因此仍属于此 skill；请参阅下文的“服务端网页搜索”。

圆桌 — POST /v3/roundtable（测试版）

向多个 models 并行发送同一个 input，并汇总答案。汇总模式：summary（默认；由一个整合模型合并答案）、fast（不进行整合，读取 model_results），或 multiple_choice（在 choices 中投票）。指南：docs.opper.ai/build/roundtable/overview。

服务端网络搜索

在服务端运行网络搜索（每次搜索的费用计入 usage.opper.cost.tools）：

• 可移植 — 在上文任一兼容的聊天端点的 tools[] 中添加 {"type": "opper:web_search"}。只需一个条目，即可在所有模型上使用，并返回该端点原生的引用内容，因此客户端代码无需针对不同提供商进行分支。engine 字段控制路由：auto（默认；支持时使用模型原生提供商的搜索，否则使用 Opper 的引擎）、native（要求使用原生搜索，否则返回 400）、opper（始终使用 Opper 的引擎），或通过 jina / exa / linkup / searchbase 指定后端。其他参数：max_results、max_uses、search_context_size（very_low → full）、allowed_domains / excluded_domains、country、freshness。Beta 版。
• 原生 — 提供商自己的格式（web_search_20250305、{type:"web_search"}、{googleSearch:{}}）会原样转发给路由到的提供商。
• 独立 — POST /v3/tools/web/search 可直接执行一次搜索，无需模型或 Agent 循环。

权威字段参考：规范（spec）中的 CanonicalWebSearchTool 架构（curl -s https://api.opper.ai/v3/openapi.yaml | grep -i -n CanonicalWebSearchTool）。指南：docs.opper.ai/build/gateway/web-search。

其他 v3 接口

v3 规范还涵盖追踪（/v3/spans、/v3/traces）、生成、文件（/v3/files）、内置网络工具，以及异步产物（/v3/artifacts/{id}/status）。请获取规范以查看具体格式；本文档不会逐一列举这些内容，因为它们会发生变化。

迁移 — 从其他网关迁移，或从 Opper 自有的 /call 迁移

从 OpenRouter、OpenAI、Anthropic 等迁移：请参阅 references/migration.md。概括来说：将基础 URL 指向 https://api.opper.ai/v3/compat，并使用 Opper API 密钥。

从 Opper 自有的旧版 /call（POST /v3/call 或 opperai SDK 的 opper.call）迁移，或从 opperai SDK 整体迁移：请参阅同一文件 — 开篇介绍了 /call 到聊天补全的逐字段映射（name → X-Opper-Name 请求头、instructions → system 消息、output_schema → response_format、data → 解析后的 choices[0].message.content）。

编码助手集成

如需了解如何将 Opper 接入 Claude Code、Cursor、Copilot、Continue 等，请参阅 docs.opper.ai/overview/integrations 上的最新列表。

容易忽略的注意事项

• 一个网关，多个端点。 文本／聊天使用 /v3/compat/...；媒体生成、文件和实时功能属于独立接口（opper-multimodal 技能）。它们共用同一个密钥和治理机制。
• /v3/call 已过时，即将停用。 切勿将新集成指向它，也不要在示例中使用它。现有 /call 用户（包括 opperai SDK 的 opper.call）应迁移到 compat + response_format —— 参见 references/migration.md。
• Compat 端点位于 /v3/compat/... 下，而不是 /v3/...。迁移 SDK 时，应将基础 URL 指向 https://api.opper.ai/v3/compat。
• OpenAI 格式的端点使用 Authorization: Bearer ... 进行身份验证（此处使用 x-api-key 会返回 401）。Anthropic Messages 和 Gemini compat 路由也接受各自 SDK 的请求头（x-api-key、x-goog-api-key），因此迁移这些 SDK 时无需覆盖请求头。
• 结构化输出是一个参数，而不是端点 —— 在 compat 聊天调用中使用 response_format: {type: "json_schema"}。
• 不带限定信息的模型名称表示一个池，而不是某个提供商。 "model": "kimi-k3" 会路由到任何提供该模型的服务商；"tensorx/moonshotai/kimi-k3" 会固定到一个服务商；"my-alias" 使用你自己的有序列表；"dynamic/my-route" 则运行已部署的图。响应中的 model 字段只会回显你发送的值，因此只有追踪记录（span.meta.model）才能显示实际运行的模型 —— 参见 references/model-routing.md。
• 服务端网页搜索具有可移植性 —— 一个 {"type": "opper:web_search"} 工具条目适用于所有模型；原生服务商格式也会原样转发。
• 媒体／文件／实时功能不属于此技能范围 —— 它们有专用端点，文档见 opper-multimodal。请勿在此自行猜测其格式。
• 知识库即将停用。 不要基于 /v2/knowledge、opper.knowledge.* 或 opper indexes 构建功能；如需检索，请使用用户自行选择的向量存储（如果用户希望通过 Opper 获取嵌入，可使用 /v3/compat/embeddings）。
• 规范是最新的参考资料；文档和此技能均以其为准。 此文件可能过时，规范不会。
• 征得用户同意后，将缺失之处反馈给 Opper。 如果过程中发现内容缺失、不清楚或有误（例如模型、文档，或无法解释的错误），请提出将其作为一般反馈发送，并在用户同意后发送：使用 Opper MCP 的 send_feedback 工具，或通过 POST https://agents.opper.ai/feedback 发送包含 JSON message 的请求（对同一 URL 执行 GET 可查看字段说明）。无需 API 密钥，也不会发送回复。切勿包含 API 密钥、用户代码或个人数据。

后续查阅

用途	查阅内容
实时、权威的端点定义	https://api.opper.ai/v3/openapi.yaml
概念（组织、项目、调用、追踪、网关、控制平面）	docs.opper.ai/overview/concepts
网关行为（路由、兼容性）	docs.opper.ai/overview/gateway
控制平面规则（支出限制、数据保留、模型访问、检查、路由）	docs.opper.ai/control-plane/rules/overview
管理 API：通过代码或 CI 管理项目、密钥、动态路由和规则	docs.opper.ai/control-plane/management-api
媒体生成、文件、视觉/PDF 输入、实时语音	opper-multimodal 技能
多模态概念（文档）	docs.opper.ai/build/multimodal/overview
Roundtable	docs.opper.ai/build/roundtable/overview
可浏览的模型目录（用于面向用户的推荐）	opper.ai/models
多种语言的示例方案	github.com/opper-ai/opper-cookbook
深入了解提供商兼容端点	references/compatibility.md
从 OpenRouter / OpenAI / Anthropic / Opper 旧版 /call 迁移	references/migration.md
模型路由——池、固定模型、组织别名、动态路由、故障转移	references/model-routing.md
构建 Agent（框架、普通工具循环、从 Agent SDK 迁移）	references/agents.md
Agent 辅助设置、平台运维和模型测试	opper-mcp 技能
在终端中调用 API	opper-cli 技能