跳转到主要内容
curl "https://api.poixe.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $POIXE_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Hello!"
          }
        ]
      }
    ]
  }'

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Hello there! How can I help you today?"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 2,
    "candidatesTokenCount": 10,
    "totalTokenCount": 35,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 2
      }
    ],
    "thoughtsTokenCount": 23
  },
  "modelVersion": "gemini-2.5-flash",
  "responseId": "9h9hae6BBJy8vr0PoczKOA"
}
POST 非流 https://api.poixe.com/v1beta/models/gemini-2.5-flash:generateContentPOST 流式 https://api.poixe.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse
这是 Google 面向开发者提供的统一生成式能力接口体系：它用一致的输入/输出结构覆盖文本、多模态与工具增强等场景。

​
流式调用（SSE）

Gemini 的非流式与流式是 两个不同的接口，并且 请求 URL 中包含模型名称（例如 .../models/gemini-2.5-flash:xxx），不是像部分协议那样仅在 body 里填 model。
  • 非流式：POST ...:generateContent
  • 流式：POST ...:streamGenerateContent?alt=sse

​
鉴权与请求头

所有请求都必须在 HTTP Header 中携带 API Key。
​
x-goog-api-key
string
必填
Google API Key。格式示例：$POIXE_API_KEY。
​
Content-Type
string
必填
必须设置为 application/json。

​
请求参数

以下是最常用、最核心的请求字段（覆盖单轮文本、多轮对话、常见采样控制）。
​
contents
object[]
必填
对话内容（或单轮输入）。Gemini 使用 contents[] 表示“对话历史 + 本轮输入”。
​
systemInstruction
object
系统指令（可选）。用于放置“开发者/系统级约束”，本质上也是一个 Content（通常只包含 text）。
​
generationConfig
object
生成参数（可选），用于控制采样、长度与输出格式。
​
tools
object[]
工具列表（可选）。用于函数调用/代码执行等能力（不同模型与能力支持情况可能不同）。
​
toolConfig
object
工具配置（可选）。用于指定工具选择策略、约束等（通常与 tools 搭配使用）。
​
safetySettings
object[]
安全设置（可选）。用于覆盖默认的内容安全阈值策略（按类别配置）。

​
响应结构

非流式请求返回一个 GenerateContentResponse 对象；流式请求会以 SSE 返回多段 GenerateContentResponse（你会持续收到多条 data: {...} JSON）。
​
candidates
object[]
候选结果列表（通常取 candidates[0] 即可）。
​
promptFeedback
object
提示词安全反馈（如有返回）。当 prompt 触发过滤/阻断时通常可从这里定位原因。
​
usageMetadata
object
Token 用量统计（输出字段）。Gemini 的计费口径建议按以下方式理解与落库： input_tokens = promptTokenCount + toolUsePromptTokenCount， output_tokens = candidatesTokenCount + thoughtsTokenCount， total_tokens = input_tokens + output_tokens（通常与 totalTokenCount 对齐）。
​
modelVersion
string
实际使用的模型版本（输出字段）。
​
responseId
string
响应唯一标识（输出字段）。

官方文档：Text generation（Gemini API）

查看 Gemini 文本生成说明、示例与最佳实践。