Gemini

Half Off Dev 在 /v1beta/models/{model} 下提供 Gemini 原生的 generateContent、streamGenerateContent 和 countTokens 方法。给 Google Gen AI SDK 设置 base URL https://halfoff.dev，并把 Half Off Dev 密钥作为 API key 传入，现有的 Gemini 代码就能以官方标价的一半继续运行。请求体原样转发，每个字段的含义见 Google API 文档。

配置 SDK#

SDK 通过 x-goog-api-key 发送密钥，也接受 ?key= 查询参数。

curl "https://halfoff.dev/v1beta/models/gemini-3.1-pro:generateContent" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "简单说说 CDN 对一个小博客有什么用。"}]}]
  }'

安装：pip install google-genai 或 npm install @google/genai。模型 ID 以 GET /v1/models 为准，Google 自己的写法（如 gemini-3.1-pro-preview）也会解析到同一个模型。如需 Gemini 响应格式的模型列表，请调用 GET /v1beta/models。

用 SSE 流式接收#

请求 :streamGenerateContent?alt=sse 即可收到 SSE。每个事件都是一个不完整的 GenerateContentResponse，最后一个事件包含完整的 usageMetadata。SDK 会自动加上 alt=sse。

curl -N "https://halfoff.dev/v1beta/models/gemini-3-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "写一首关于编译器的四行小诗。"}]}]}'

不带 alt=sse 时，该方法以单个 JSON 数组的形式流式返回。这样也能用，但 SSE 更容易增量解析，而且只有在 SSE 模式下，流卡住时网关才能发出规范的错误事件。见流式输出。

系统指令与思考#

systemInstruction、generationConfig、safetySettings 以及 tools 中的函数声明，都按 Google 文档的方式原样传递。Gemini 3 模型默认开启思考，可以按 Google 思考指南用 thinkingConfig 调整。

response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="给一份两个月学会 Rust 的每周学习计划。",
    config=types.GenerateContentConfig(
        system_instruction="你是一位务实的编程教练，用要点列表回答。",
        max_output_tokens=4096,
    ),
)
print(response.text)
print(response.usage_metadata)

思考 token 记在 usageMetadata.thoughtsTokenCount 中，和 candidatesTokenCount 一起按输出单价计费。与 Google API 一致，只有请求设置了 generationConfig.thinkingConfig.includeThoughts: true，思考摘要才会以带 "thought": true 的 part 返回；否则响应中没有思考内容。

计算 token 数#

:countTokens 接受与生成请求相同的 contents，返回 totalTokens。不收费，余额为零也能用。结果是近似值：适合对照上下文窗口检查长度，不适合精确预测扣费。

curl "https://halfoff.dev/v1beta/models/gemini-3.1-pro:countTokens" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "量一量这句话。"}]}]}'

Gemini CLI#

Gemini CLI 从环境变量读取端点和密钥：

export GOOGLE_GEMINI_BASE_URL=https://halfoff.dev
export GEMINI_API_KEY="$HALFOFF_API_KEY"
gemini -m gemini-3.1-pro

完整步骤见 Gemini CLI。

缓存#

Gemini 会自动缓存重复的提示前缀（隐式缓存）。命中缓存的 token 记在 usageMetadata.cachedContentTokenCount 中，按缓存读取单价计费。网关会把每个对话送回同一个渠道，让缓存保持有效，见提示缓存。

不支持的功能#

以下 Gemini API 功能返回 404：cachedContents（显式上下文缓存）、文件上传、embedContent 与 batchEmbedContents、批处理模式，以及 Live API。

请求头#

错误沿用 Gemini 的格式 {"error": {"code": 429, "message": "...", "status": "RESOURCE_EXHAUSTED"}}，见错误。