Gemini Native API

Google Gemini 原生协议端点。让你直接用 Google 官方 SDK(google-genai / @google/genai)零代码改动接入 Picklyone,享受 Gemini 全部多模态能力。

💡 如果你已经在用 OpenAI SDK,继续走 /v1/chat/completions 也能调 Gemini —— 只需把 model 改成 gemini-2.5-flash 等 Gemini 模型名即可,不必切到本端点。
什么时候用 Gemini Native: 你原本在用 Google 官方 SDK / 需要 Gemini 独有能力(精确思考预算、safetySettings 精细控制、avgLogprobs 置信度输出)/ 想要零翻译漂移的 token 对账。
什么时候继续用 OpenAI 格式: 跨多家模型(GPT + Claude + Gemini)用统一一套代码 / 从 OpenAI 迁来不想改 SDK。

端点

{model} 替换为模型 ID,例如 gemini-2.5-flash。

鉴权(支持 3 种方式)

任选其一即可,推荐使用 header 方式:

1. Authorization header(推荐)

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx

2. x-api-key header

x-api-key: pk_live_xxxxxxxxxxxxxxxx

3. ?key= query 参数(Google SDK 默认方式)

POST /v1beta/models/{model}:generateContent?key=pk_live_xxxxxxxxxxxxxxxx

⚠️ ?key= 方式 API Key 会出现在 URL 中,可能被 CDN 日志、浏览器历史记录捕获。生产环境优先用 header 方式。

请求体

完全遵循 Google 官方 generateContent 文档。常用字段:

示例:纯文本对话

curl https://api.picklyone.com/v1beta/models/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "parts": [{ "text": "你好,请用一句话介绍下你自己" }] }
    ],
    "generationConfig": {
      "maxOutputTokens": 512
    }
  }'

响应:

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{ "text": "你好!我是 Gemini..." }]
    },
    "finishReason": "STOP",
    "avgLogprobs": -1.23
  }],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 50,
    "totalTokenCount": 60,
    "thoughtsTokenCount": 0
  },
  "modelVersion": "gemini-2.5-flash"
}

示例:流式输出

curl https://api.picklyone.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "讲一个一句话故事" }] }],
    "generationConfig": { "maxOutputTokens": 1024 }
  }'

返回 SSE 格式,每个 chunk:

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"从前..."}]}}],"modelVersion":"gemini-2.5-flash"}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"有一只猫"}]},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":5,"candidatesTokenCount":15,"totalTokenCount":20}}

最后一个 chunk 含完整 usageMetadata —— 实际客户端用 Google SDK 时不用手动解析,SDK 会自动累加。

示例:多模态(图片识别)

在 parts 数组里加 inline_data(base64 编码的图片):

IMG_B64=$(base64 -w 0 photo.jpg)

curl https://api.picklyone.com/v1beta/models/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d "{
    \"contents\": [{
      \"parts\": [
        { \"text\": \"这张图里是什么?\" },
        { \"inline_data\": { \"mime_type\": \"image/jpeg\", \"data\": \"$IMG_B64\" } }
      ]
    }]
  }"

支持的 MIME 类型:image/jpeg / image/png / image/webp / image/heic / image/heif。

注意:单次请求 body 总大小限制为 30MB,超大文件(视频/PDF 等)的 Files API 暂未支持。

示例:思考预算精确控制

gemini-2.5-flash 等模型支持显式控制推理(thinking)token 预算:

{
  "contents": [{ "parts": [{ "text": "..." }] }],
  "generationConfig": {
    "maxOutputTokens": 2048,
    "thinkingConfig": {
      "thinkingBudget": 1024
    }
  }
}

thinkingBudget 取值含义:

💡 思考型模型默认会消耗大量 token 推理。如果你只要短回复,建议显式设置 thinkingBudget: 0 或较小值,否则 max_tokens 会被推理吃光,可见输出不完整。

用 Google 官方 SDK 接入

这是 Gemini Native 端点最大的卖点 —— 改 1 行 baseUrl 就能从 Google 官方迁移。

Python(google-genai)

from google import genai

client = genai.Client(
    api_key="pk_live_xxxxxxxxxxxxxxxx",
    http_options={"base_url": "https://api.picklyone.com"},
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="你好",
)
print(response.text)

Node.js(@google/genai)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: "pk_live_xxxxxxxxxxxxxxxx",
  httpOptions: { baseUrl: "https://api.picklyone.com" },
});

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Hello",
});
console.log(response.text);

业务代码完全不动,SDK 行为、字段名、错误处理全部保留 Google 官方语义。

Token 计费说明

Gemini 的 usageMetadata 字段按以下方式计入账单:

多模态图片输入的 token 数会出现在 promptTokensDetails[modality=IMAGE],按 input_price 计费(与文本 token 同价)。

错误响应格式

错误返回 Google 原生格式:

{
  "error": {
    "code": 404,
    "message": "Model 'xxx' is not available",
    "status": "NOT_FOUND"
  }
}

常见错误码:

当前已支持/未支持端点对照

支持的 Gemini 模型

请到 模型列表 查看当前可用的全部模型。所有 gemini-* 系列模型都可以走 Gemini Native 端点。

如果某个模型同时出现在 OpenAI 兼容端点和 Gemini Native 端点中,你可以任意选择协议调用,billing 和速率限制完全一致。