Avyneo API 接入文档

Avyneo API 支持 OpenAI、Google Gemini、Anthropic 多种兼容格式接口。把官方 SDK 的 base URL 指向 Avyneo，无需改动业务代码，即可调用 Claude / Gemini / GPT 等多家模型。

Base URL: https://YOUR_AVYNEO_API_HOST/v1 · https://YOUR_AVYNEO_API_HOST/anthropic · https://YOUR_AVYNEO_API_HOST/gemini
鉴权: API Key（sk-avyneo-xxxxxx）
协议: Anthropic 原生（/anthropic/v1/messages）· OpenAI 兼容（/v1/chat/completions）· Responses API（/v1/responses，仅 GPT）· Gemini 原生（/gemini/v1beta）· 图像（/v1/images）

文中的 sk-avyneo-xxxxxx 请替换为你自己的 Key，妥善保管、不要提交到代码仓库。

一、Base URL 与请求头

三种协议共用同一枚 API Key，Base URL 按协议区分：

base-urltext

OpenAI      https://YOUR_AVYNEO_API_HOST/v1
Anthropic   https://YOUR_AVYNEO_API_HOST/anthropic
Gemini      https://YOUR_AVYNEO_API_HOST/gemini

不同格式的鉴权 Header 不同，按使用的协议选择：

协议	Header
`Anthropic`	x-api-key: sk-avyneo-xxxxxx + anthropic-version: 2023-06-01
`OpenAI`	Authorization: Bearer sk-avyneo-xxxxxx
`Gemini`	x-goog-api-key: sk-avyneo-xxxxxx

二、可用模型

通过 GET /v1/models 实时拉取完整列表：

models.shbash

curl https://YOUR_AVYNEO_API_HOST/v1/models \
  -H "Authorization: Bearer sk-avyneo-xxxxxx"

当前主要模型（节选）：

厂商	模型 ID
`Anthropic`	claude-fable-5、claude-opus-5、claude-sonnet-5、claude-opus-4-8、claude-sonnet-4-6、claude-haiku-4-5
`OpenAI`	gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-5.5、gpt-5.4、gpt-5.4-mini、gpt-image-2
`Google`	gemini-3.7-flash、gemini-3.6-flash、gemini-3.5-flash、gemini-3.5-flash-lite、gemini-3.1-pro-preview
`Kimi`	kimi-k3
`DeepSeek`	deepseek-v4-pro、deepseek-v4-flash、deepseek-v4-flash-vision-exp
`GLM`	glm-5.3-flash、glm-5.3、glm-5.2
`Grok`	grok-4.6

上表仅为节选，实际可用范围与模型 ID 以 /v1/models 的实时返回为准。

三、Anthropic 原生格式

端点：POST /anthropic/v1/messages。调用 Claude 系列模型请使用该协议。

3.1 基础请求

messages.shbash

curl https://YOUR_AVYNEO_API_HOST/anthropic/v1/messages \
  -H "x-api-key: sk-avyneo-xxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'

返回（节选）：

response.jsonjson

{
  "id": "msg_01KxDE...",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5",
  "content": [{"type": "text", "text": "我是 Claude……"}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 159, "output_tokens": 34}
}

3.2 流式（SSE）

加 "stream": true，响应为 text/event-stream：

messages-stream.shbash

curl https://YOUR_AVYNEO_API_HOST/anthropic/v1/messages \
  -H "x-api-key: sk-avyneo-xxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "写一首五言绝句"}]
  }'

事件序列：message_start → content_block_start → 多个 content_block_delta → content_block_stop → message_delta → message_stop。

3.3 Python SDK（anthropic）

claude.pypython

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-avyneo-xxxxxx",
    base_url="https://YOUR_AVYNEO_API_HOST/anthropic",
)

resp = client.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.content[0].text)

Anthropic SDK 的 base_url 填到 /anthropic 为止，/v1/messages 由 SDK 自动补全。

四、OpenAI 兼容格式

端点：POST /v1/chat/completions（Chat Completions）与 POST /v1/responses（Responses API，仅 GPT 系列）。

4.1 Chat Completions 基础请求

chat.shbash

curl https://YOUR_AVYNEO_API_HOST/v1/chat/completions \
  -H "Authorization: Bearer sk-avyneo-xxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

返回为标准 OpenAI chat.completion 结构：

response.jsonjson

{
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 214, "completion_tokens": 3, "total_tokens": 217}
}

4.2 Python SDK（openai）

gpt.pypython

from openai import OpenAI

client = OpenAI(
    api_key="sk-avyneo-xxxxxx",
    base_url="https://YOUR_AVYNEO_API_HOST/v1",
)

resp = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

OpenAI SDK 的 base_url 必须带 /v1 后缀。

4.3 流式

加 "stream": true，返回标准 OpenAI SSE（data: {...} 分片，以 data: [DONE] 结束）。

4.4 Responses API 基础请求

如果你的应用已经迁移到 OpenAI Responses API，可以直接调用 /v1/responses：

responses.shbash

curl https://YOUR_AVYNEO_API_HOST/v1/responses \
  -H "Authorization: Bearer sk-avyneo-xxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "用一句话介绍 Avyneo"
  }'

/v1/responses 仅支持 GPT 系列模型，请求 Claude / Gemini 会直接返回 400。Claude 请走 /v1/messages，Gemini 请走 Gemini 原生格式。

4.5 Python SDK（openai responses）

responses.pypython

from openai import OpenAI

client = OpenAI(
    api_key="sk-avyneo-xxxxxx",
    base_url="https://YOUR_AVYNEO_API_HOST/v1",
)

resp = client.responses.create(
    model="gpt-5.6-sol",
    input="用一句话介绍 Avyneo",
)
print(resp.output_text)

4.6 Responses API 流式

加 "stream": true，返回 OpenAI Responses API 的标准流式事件。

4.7 快速模式（Fast mode）

OpenAI 兼容接口支持快速模式（Fast mode，原名 Priority processing）。在 Chat Completions 或 Responses API 请求中加入：

fast-mode.jsonjson

"service_tier": "fast"

fast.pypython

from openai import OpenAI

client = OpenAI(
    api_key="sk-avyneo-xxxxxx",
    base_url="https://YOUR_AVYNEO_API_HOST/v1",
)

resp = client.responses.create(
    model="gpt-5.6-sol",
    input="帮我分析这个需求",
    service_tier="fast",
)
print(resp.output_text)

fast.mjsjavascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-avyneo-xxxxxx",
  baseURL: "https://YOUR_AVYNEO_API_HOST/v1",
});

const resp = await client.responses.create({
  model: "gpt-5.6-sol",
  input: "帮我分析这个需求",
  service_tier: "fast",
});
console.log(resp.output_text);

旧写法 "service_tier": "priority" 仍然兼容，两者效果相同；fast 为当前推荐写法，适用于所有支持快速模式的 GPT 系列模型。

快速模式输出速度更快、计费倍率更高，具体倍率以定价页为准。对于 GPT-5.6 及更早模型，响应中的 service_tier 可能仍返回 "priority"，这是正常现象。

五、Gemini 原生格式

端点：POST /gemini/v1beta/models/{model}:generateContent。

5.1 基础请求

gemini.shbash

curl https://YOUR_AVYNEO_API_HOST/gemini/v1beta/models/gemini-3.5-flash:generateContent \
  -H "x-goog-api-key: sk-avyneo-xxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "用一句话介绍你自己"}]}
    ]
  }'

返回（节选）：

response.jsonjson

{
  "candidates": [
    {
      "content": {"role": "model", "parts": [{"text": "我是 Gemini……"}]},
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {"promptTokenCount": 12, "candidatesTokenCount": 22, "totalTokenCount": 34}
}

5.2 流式（SSE）

使用 streamGenerateContent，并加上 alt=sse：

gemini-stream.shbash

curl "https://YOUR_AVYNEO_API_HOST/gemini/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: sk-avyneo-xxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "写一首五言绝句"}]}
    ]
  }'

5.3 环境变量

如果你的工具或 SDK 支持自定义 Gemini Base URL，可以按下面方式配置：

env.shbash

export GOOGLE_GEMINI_BASE_URL="https://YOUR_AVYNEO_API_HOST/gemini"
export GEMINI_API_KEY="sk-avyneo-xxxxxx"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

不同 Gemini SDK 对自定义 endpoint 的字段名可能不同，常见名称包括 base_url、baseURL、apiEndpoint 或环境变量。核心原则：Base URL 指向部署地址，Key 使用你的 Avyneo API Key。

六、图像生成（GPT Image 2）

图像模型 gpt-image-2 使用独立的 /v1/images 端点，鉴权为 Authorization: Bearer。

6.1 生成图像

端点：POST /v1/images/generations

images.shbash

curl https://YOUR_AVYNEO_API_HOST/v1/images/generations \
  -H "Authorization: Bearer sk-avyneo-xxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只在键盘上打字的橘猫，插画风格"
  }'

返回（节选），data[0].b64_json 为 Base64 编码的图片：

response.jsonjson

{
  "created": 1752345600,
  "data": [
    {"b64_json": "iVBORw0KGgo..."}
  ]
}

建议把客户端超时设置为 300 秒。生图模型响应时间较长，超时太短可能调用失败。

6.2 编辑图像

端点：POST /v1/images/edits。以 multipart/form-data 上传原图并给出修改指令：

images-edit.shbash

curl https://YOUR_AVYNEO_API_HOST/v1/images/edits \
  -H "Authorization: Bearer sk-avyneo-xxxxxx" \
  -F model="gpt-image-2" \
  -F image="@photo.png" \
  -F prompt="把背景换成星空"

接口与 OpenAI Images API 兼容。

七、在 Agent 工具中接入

Claude Code 走 Anthropic 协议、Codex 走 OpenAI 协议、Gemini CLI 走 Gemini 协议。只需用环境变量把 Base URL 和 API Key 指向 Avyneo 即可，无需改动工具本身。

Claude Code（Anthropic 协议）：

claude-code.shbash

export ANTHROPIC_BASE_URL="https://YOUR_AVYNEO_API_HOST/anthropic"
export ANTHROPIC_API_KEY="sk-avyneo-xxxxxx"

OpenAI 协议的工具（Chat Completions / Responses API 均可）：

openai-tools.shbash

export OPENAI_BASE_URL="https://YOUR_AVYNEO_API_HOST/v1"
export OPENAI_API_KEY="sk-avyneo-xxxxxx"

Gemini CLI：

gemini-cli.shbash

export GOOGLE_GEMINI_BASE_URL="https://YOUR_AVYNEO_API_HOST/gemini"
export GEMINI_API_KEY="sk-avyneo-xxxxxx"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

八、常见问题

出现 401 报错 / 鉴权失败？: 先核对协议与 Header 的对应关系：Anthropic 用 x-api-key，OpenAI 用 Authorization: Bearer，Gemini 用 x-goog-api-key。再确认 Key 复制完整（sk-avyneo- 开头、无多余空格）且未在控制台删除；另外注意 base_url 写法：OpenAI 填 /v1，Anthropic 填 /anthropic，Gemini 填 /gemini。
调用 Claude 该用哪种协议？: Claude Code 等 Agent 工具按 Anthropic 协议配置：Base URL 填 /anthropic，端点为 /v1/messages。其他应用继续用 OpenAI 兼容格式调用 Claude 也可以，网关会在入口完成协议转换。
模型不可用？: 请先用 GET /v1/models 拉取实时列表，核对模型 ID 拼写（全小写，留意 - 与 . 的区别）。同时确认端点与模型的对应关系。
超时 / 首字慢？: Opus / Fable 这类大模型在思考阶段首字延迟数秒到数十秒属正常，不代表请求失败。生产环境建议加 "stream": true 用流式提升体感，并把客户端读超时调大。
Key 安全: 放入环境变量或密钥管理服务，切勿硬编码、提交到 Git，或打包进前端 / 客户端对外分发。若怀疑 Key 已泄露，立即在控制台删除该 Key 并新建替换。