文档API 参考Gemini API

Gemini API

Google Gemini 兼容入口：generateContent、streamGenerateContent 与 countTokens。

POST/v1beta/models/{model}:generateContent

与 Google Gemini API 请求体兼容的对话入口。模型名与动作写在路径里（{model}:generateContent），鉴权用 x-goog-api-key 头。

不支持 Google 官方的 ?key= 查询参数传 Key，必须用 x-goog-api-key 头（Google GenAI SDK 默认就走该头）。

请求体

字段	类型	必填	说明
`contents`	array	是	对话内容：每项含 `role`（`user`/`model`）与 `parts`（文本或内联媒体）。
`systemInstruction`	object	否	系统提示词（`{ "parts": [{ "text": … }] }`）。
`generationConfig`	object	否	生成参数：`temperature`、`maxOutputTokens` 等。

request.sh

curl "https://soleapi.com/v1beta/models/gemini-3.7-flash:generateContent" \
  -H "x-goog-api-key: $SOLEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Write a haiku about the sea"}]}]
  }'

响应

response.json

{
  "candidates": [
    {
      "content": {
        "parts": [{ "text": "Waves fold into foam..." }],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 14,
    "candidatesTokenCount": 23,
    "totalTokenCount": 37
  }
}

流式生成

POST/v1beta/models/{model}:streamGenerateContent

追加 ?alt=sse 以 SSE 增量返回，每条 data: 行是一个响应片段；不带 alt=sse 时返回完整 JSON 数组。详见流式响应。

计数 token

POST/v1beta/models/{model}:countTokens

count_tokens.sh

curl "https://soleapi.com/v1beta/models/gemini-3.7-flash:countTokens" \
  -H "x-goog-api-key: $SOLEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Write a haiku about the sea"}]}]
  }'

# => { "totalTokens": 14 }

图像生成（Nano Banana）

Gemini 的图像模型（gemini-2.5-flash-image、gemini-3-pro-image、gemini-3.1-flash-image、gemini-3.1-flash-lite-image）没有单独的图像接口，仍走上面的 generateContent / streamGenerateContent：请求体与文本对话相同，只需在 generationConfig.responseModalities 里声明要图片；生成的图片以 inlineData（base64）随 parts 返回。

字段	类型	说明
`generationConfig.responseModalities`	array	`["TEXT", "IMAGE"]`；只要图片可写 `["IMAGE"]`。
`generationConfig.imageConfig.aspectRatio`	string	`1:1`、`3:2`、`2:3`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`。
`generationConfig.imageConfig.imageSize`	string	`1K`（默认）、`2K`、`4K`；`gemini-3.1-flash-image` 另支持 `0.5K`，`gemini-3.1-flash-lite-image` 仅 `1K`，`gemini-2.5-flash-image` 不支持该字段。

generate_image.sh

curl "https://soleapi.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "x-goog-api-key: $SOLEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "A watercolor lighthouse at dawn"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

response.json

{
  "candidates": [
    {
      "content": {
        "parts": [
          { "text": "Here is the lighthouse." },
          { "inlineData": { "mimeType": "image/png", "data": "iVBORw0KGgo..." } }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 1694,
    "candidatesTokensDetails": [
      { "modality": "TEXT", "tokenCount": 14 },
      { "modality": "IMAGE", "tokenCount": 1680 }
    ],
    "totalTokenCount": 1703
  }
}

编辑图片：把参考图作为 inlineData 放进 contents[].parts（最多 14 张），与文字指令一起发送即可；请求体其余部分不变。

edit_request.json

{
  "contents": [{
    "parts": [
      { "text": "Turn the sky into a starry night" },
      { "inlineData": { "mimeType": "image/jpeg", "data": "<base64>" } }
    ]
  }],
  "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
}

图片按 输出 token 计费（usageMetadata.candidatesTokensDetails 中 modality = IMAGE 的数量），单价见模型页；1K 图约 1,120～1,290 token，2K 约 1,680，4K 约 2,000～2,520。流式用法与文本相同（streamGenerateContent?alt=sse），图片会在最后一帧整体到达。