Gemini 文本接口

Gemini 内容生成接口文档。

接口地址

POST https://www.moyu.info/v1beta/models/{model}:generateContent

流式输出请使用 streamGenerateContent 端点并加 ?alt=sse（详见下方「流式输出」）：

POST https://www.moyu.info/v1beta/models/{model}:streamGenerateContent?alt=sse

鉴权方式

以下三种鉴权方式任选其一，均等效：

方式	写法	说明
Authorization	`-H "Authorization: Bearer YOUR_API_KEY"`	本文档示例采用
Gemini 原生头	`-H "x-goog-api-key: YOUR_API_KEY"`	官方 Gemini SDK 默认发送此头
Query 参数	`?key=YOUR_API_KEY`	拼接在 URL 上

用官方 Gemini SDK 的客户默认走 x-goog-api-key，本平台同样支持，无需改造。

流式输出

Gemini 流式由 URL 决定，不是请求体字段——按 OpenAI 习惯在 body 里传 "stream": true 对 Gemini 无效。

开启流式需同时满足两点：

端点用 streamGenerateContent（而非 generateContent）；

URL 加 query 参数 ?alt=sse，响应即以 SSE（text/event-stream）逐块返回。

请求示例

cURL

其他语言

响应格式

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Hi there! How can I help you today? 😊\n"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "avgLogprobs": -0.10243042310078938
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 6,
    "candidatesTokenCount": 12,
    "totalTokenCount": 18,
    "cachedContentTokenCount": 0
  }
}

请求参数

路径参数

参数	类型	必填	说明
model	string	是	模型名称，如 gemini-2.0-flash, gemini-2.5-flash, gemini-3-pro-preview 等

基础参数

参数	类型	必填	说明
contents	array	是	对话内容列表，包含用户和模型的消息

contents 格式

[
  {
    "role": "user",
    "parts": [
      {
        "text": "Hello"
      }
    ]
  }
]

支持的 role 值：

user: 用户消息

model: 模型的回复

系统指令参数

参数	类型	必填	说明
systemInstruction	object	否	系统指令，用于设定模型的行为和角色

systemInstruction 格式

{
  "parts": [
    {
      "text": "You are a helpful assistant"
    }
  ]
}

生成配置参数

参数	类型	必填	默认值	说明
generationConfig	object	否	-	生成配置对象
generationConfig.temperature	number	否	1.0	采样温度，范围 0-2。较高的值使输出更随机，较低的值使输出更确定
generationConfig.topP	number	否	0.95	核采样参数，范围 0-1
generationConfig.topK	integer	否	40	Top-K 采样参数
generationConfig.maxOutputTokens	integer	否	8192	生成的最大 token 数量
generationConfig.candidateCount	integer	否	1	生成的候选响应数量
generationConfig.stopSequences	array	否	-	停止序列列表，遇到时停止生成

安全设置参数

参数	类型	必填	说明
safetySettings	array	否	安全过滤设置数组

safetySettings 格式

[
  {
    "category": "HARM_CATEGORY_HARASSMENT",
    "threshold": "BLOCK_MEDIUM_AND_ABOVE"
  }
]

支持的 category 值：

HARM_CATEGORY_HARASSMENT: 骚扰内容

HARM_CATEGORY_HATE_SPEECH: 仇恨言论

HARM_CATEGORY_SEXUALLY_EXPLICIT: 色情内容

HARM_CATEGORY_DANGEROUS_CONTENT: 危险内容

支持的 threshold 值：

BLOCK_NONE: 不阻止

BLOCK_ONLY_HIGH: 仅阻止高风险

BLOCK_MEDIUM_AND_ABOVE: 阻止中等及以上风险

BLOCK_LOW_AND_ABOVE: 阻止低等及以上风险

工具参数

参数	类型	必填	说明
tools	array	否	工具列表，用于函数调用等高级功能

文件上传参数（inline_data）

通过 inline_data 可以将文件以 base64 编码的方式内联传递，让模型分析图片、视频等多模态内容。

参数	类型	必填	说明
inline_data.mime_type	string	是	文件 MIME 类型，如 `video/mp4`、`image/jpeg`、`image/png` 等
inline_data.data	string	是	文件的 base64 编码字符串（不换行）

支持的视频格式

格式	MIME 类型
MP4	`video/mp4`
AVI	`video/avi`
MOV	`video/quicktime`
WebM	`video/webm`
MKV	`video/x-matroska`
FLV	`video/x-flv`

文件上传请求示例

第一步：将文件转为 base64 并构造请求体

第二步：发送请求

响应示例

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "这段视频展现了一个充满田园诗意和治愈感的动画场景..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 911,
    "candidatesTokenCount": 634,
    "totalTokenCount": 2682,
    "promptTokensDetails": [
      { "modality": "VIDEO", "tokenCount": 640 },
      { "modality": "AUDIO", "tokenCount": 252 },
      { "modality": "TEXT", "tokenCount": 19 }
    ]
  }
}

注意事项

文件大小：base64 编码后体积约为原文件的 1.33 倍，例如 12.6MB 的视频编码后 JSON 约 17MB

超时设置：视频文件较大时，请求耗时较长，建议 curl 加上 --max-time 300 参数

Token 消耗：视频会被拆分为视频帧和音频两部分计算 token，一段短视频通常消耗数百到数千 token

模型选择：需要使用支持多模态的 Gemini 模型（如 gemini-3-pro-preview）

响应字段说明

字段	类型	说明
candidates	array	生成的候选响应列表
candidates[].content.parts	array	响应内容部分
candidates[].content.parts[].text	string	生成的文本内容
candidates[].content.role	string	角色，固定为 model
candidates[].finishReason	string	结束原因：STOP(自然结束)、MAX_TOKENS(达到长度限制)、SAFETY(安全过滤)
candidates[].avgLogprobs	number	平均对数概率
candidates[].safetyRatings	array	安全评级列表
usageMetadata	object	token 使用情况统计
usageMetadata.promptTokenCount	integer	输入 token 数
usageMetadata.candidatesTokenCount	integer	生成 token 数
usageMetadata.totalTokenCount	integer	总 token 数
usageMetadata.cachedContentTokenCount	integer	缓存命中的 token 数（使用 context caching 时返回，未命中时为 0）
createTime	string	创建时间
modelVersion	string	模型版本

接口地址#

鉴权方式#

流式输出#

请求示例#

cURL#

其他语言#

响应格式#

请求参数#

路径参数#

基础参数#

contents 格式#

系统指令参数#

systemInstruction 格式#

生成配置参数#

安全设置参数#

safetySettings 格式#

工具参数#

文件上传参数（inline_data）#

支持的视频格式#

文件上传请求示例#

注意事项#

响应字段说明#