Gemini 原生

用一个 BeatAPI 密钥，通过 Gemini generateContent 请求调用 Gemini 4 Argon、Gemini 3.8 Flash 和 Gemini 3.1 Pro。

• POST /v1beta/models/{model}:generateContent 覆盖当前所有 Gemini 模型，流式输出用 :streamGenerateContent?alt=sse。
• 支持文本与图片输入、文本输出、流式输出、函数调用和思考。
• 密钥放在 x-goog-api-key 请求头，或作为 Bearer 令牌发送。
• 模型 ID 写在 URL 里，不在请求体里。

在调试窗口里打开本接口，填入你的 BeatAPI API 密钥即可发送。调用是真实的，费用从你自己的余额中扣除。

模型

把下列 ID 之一写进 URL，替换 {model}。

• 价格为基础档，已计入折扣。长上下文档、缓存命中输入价和缓存写入价不在本表内，见价格表。
• — 表示目录未公布该数字。

本系列仍可调用的旧 ID 见旧型号。

快速开始

把密钥放在 BEATAPI_API_KEY，不要把它写进浏览器代码。模型 ID 在 URL 里，所以请求体没有 model 字段。以下是请求示例，不是真实的模型输出记录。

从 candidates[0].content.parts[0].text 读取答案，再检查 candidates[0].finishReason 和 usageMetadata。HTTP 200 不能证明答案满足你的任务，请在应用里校验内容。文本请求直接返回，不要为它们轮询 /v1/tasks。

curl --request POST \
  --url https://direct.beatapi.io/v1beta/models/gemini-3.8-flash:generateContent \
  --header "x-goog-api-key: $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Design a resilient webhook retry strategy for a payments API."
        }
      ]
    }
  ]
}'

端点与鉴权

POST https://direct.beatapi.io/v1beta/models/{model}:generateContent

流式输出调用 POST /v1beta/models/{model}:streamGenerateContent?alt=sse。密钥放在 x-goog-api-key 请求头，或放在 Authorization: Bearer <key>，两种都行。

:countTokens 不可用，会返回 404。

请求参数

以上是会生效的字段。其他 Gemini 字段请求里可以带，但不起作用：generationConfig.thinkingConfig、generationConfig.responseMimeType、generationConfig.responseSchema、generationConfig.seed、safetySettings、toolConfig 和 cachedContent。请不要依赖它们。

[
  {
    "role": "user",
    "parts": [
      { "text": "What is in this image?" },
      { "inlineData": { "mimeType": "image/png", "data": "<base64>" } }
    ]
  }
]

{
  "parts": [{ "text": "Answer in one short paragraph." }]
}

{
  "temperature": 0.7,
  "topP": 0.95,
  "maxOutputTokens": 2048,
  "stopSequences": ["END"]
}

[
  {
    "functionDeclarations": [
      {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    ]
  }
]

响应

非流式调用返回一个 JSON 对象。以下是精简后的示例。

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Retry with exponential backoff and jitter, and make every handler idempotent."
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 19,
    "candidatesTokenCount": 16,
    "totalTokenCount": 120,
    "thoughtsTokenCount": 85
  }
}

响应字段

流式输出

调用 :streamGenerateContent?alt=sse。每个事件是一行 data: {...}，内容是 candidates 对象，形状与非流式答案相同。

• 最后一个事件带有 finishReason，例如 "STOP"。
• 流式响应是 text/event-stream。调用模型之前发生的失败，以带 HTTP 状态码的普通 JSON 错误返回，不会作为流事件出现。
• 请设置明确的超时，并安全地重连流式响应。

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"Retry"}]},"index":0}]}
data: {"candidates":[{"content":{"role":"model","parts":[{"text":" with backoff"}]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":19,"candidatesTokenCount":16,"totalTokenCount":120,"thoughtsTokenCount":85}}

错误

HTTP 错误速查

Gemini 原生端点的错误只有一种格式 {"error": {"message", "type": "beatapi_error", "code"}}：错误码在 error.code，request id 附在 message 末尾，没有 retryable 字段。详见错误码。

完整的错误码表和重试策略见错误码。

注意事项

• Gemini 模型也可以用 Chat Completions、Responses 和 Anthropic Messages 调用，见 Gemini 的其他页面。
• 思考 token 按输出 token 计费。请为思考和答案一起预留输出额度，不要只按答案估算。
• 密钥只放在可信的服务端，记录响应里的请求 ID，只对 429、500 和 503 重试。