Gemini 兼容 API

Puyun AI 兼容 Google Gemini API 协议，你可以直接使用 Google AI SDK 或任何兼容 Gemini 协议的客户端连接。

Base URL

text
https://ai.tracup.com

认证

Gemini 协议使用 URL 查询参数进行认证：

  • API Key 参数：?key=<your-api-key>

也可以使用 Header 认证：

  • Bearer Token：Authorization: Bearer <your-api-key>
  • x-api-key 头：x-api-key: <your-api-key>

Generate Content

Gemini 兼容的内容生成端点。

bash
curl "https://ai.tracup.com/v1beta/models/gemini-2.5-pro:generateContent?key=sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "解释一下量子计算"}
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'

请求参数：

参数类型必填说明
contentsarray是内容数组，包含对话历史
generationConfigobject否生成配置
generationConfig.temperaturenumber否采样温度（0-2）
generationConfig.maxOutputTokensinteger否最大输出 Token 数
generationConfig.topPnumber否核采样概率
generationConfig.topKinteger否Top-K 采样
generationConfig.stopSequencesarray否停止序列
systemInstructionobject否系统指令
toolsarray否Function Calling 工具定义

响应示例：

json
{
  "candidates": [
    {
      "content": {
        "parts": [
          {"text": "量子计算是一种利用量子力学原理..."}
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 25,
    "candidatesTokenCount": 128,
    "totalTokenCount": 153
  },
  "modelVersion": "gemini-2.5-pro"
}

Stream Generate Content

流式内容生成端点。

bash
curl "https://ai.tracup.com/v1beta/models/gemini-2.5-pro:streamGenerateContent?key=sk-your-api-key&alt=sse" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "解释一下量子计算"}
        ]
      }
    ]
  }'

流式响应使用 SSE 格式，每个事件包含部分生成内容。

列出模型

返回可用的 Gemini 模型列表。

bash
curl "https://ai.tracup.com/v1beta/models?key=sk-your-api-key"

协议自动转换

通过 Gemini 协议端点调用非 Google 模型时，Puyun AI 会自动完成协议转换：

  • 请求转换：将 Gemini generateContent 格式转换为目标模型的原生格式
  • 响应转换：将目标模型的响应转换为 Gemini 格式返回
  • 流式适配：流式响应自动适配为 Gemini SSE 事件格式

使用 Google AI SDK

python
import google.generativeai as genai

genai.configure(
    api_key="sk-your-api-key",
    client_options={"api_endpoint": "https://ai.tracup.com"}
)

model = genai.GenerativeModel("gemini-2.5-pro")
response = model.generate_content("你好！")
print(response.text)
javascript
const { GoogleGenerativeAI } = require("@google/generative-ai");

const genAI = new GoogleGenerativeAI("sk-your-api-key");
// 设置自定义 base URL
const model = genAI.getGenerativeModel({ model: "gemini-2.5-pro" });

多模态输入

Gemini 原生支持多模态输入：

python
model = genai.GenerativeModel("gemini-2.5-pro")
response = model.generate_content([
    "描述这张图片",
    {"inline_data": {"mime_type": "image/png", "data": "<base64-encoded-image>"}}
])

错误响应

错误响应遵循 Gemini 错误格式：

json
{
  "error": {
    "code": 400,
    "message": "API key not valid",
    "status": "INVALID_ARGUMENT"
  }
}
HTTP 状态码含义
400请求参数无效
401认证失败
403权限不足
404模型不存在
429速率限制或余额不足
500服务器内部错误