文本通用接口（Gemini 原生格式）

Gemini 原生对话 / 多模态识别

Google Gemini 原生 :generateContent 协议，同步返回。SDK 用 @google/genai 时，把 base_url 指向心流即可使用。

支持三种用法：

1. 纯文本对话（gemini-2.5-flash、gemini-2.5-pro 等）
2. 多模态识别（图片 / PDF / 音频 / 视频 + 文字提示）
3. 图片生成（gemini-*-image-preview 系列，详见「图像模型 → Gemini Nano Banana」）

接入地址

线路	Base URL	说明
国内加速（推荐）	https://cdn.wusag.com	走国内 CDN 节点
海外直连	https://api.xinliu.one	海外服务器或加速节点异常时使用

两个地址共用同一账户和 Key。

请求

• 方法：POST {Base URL}/v1beta/models/{model}:generateContent
• Header：
  • Authorization: Bearer 你的令牌
  • Content-Type: application/json

模型分组

心流不同分组的 Gemini 模型权限不同。如果遇到「分组 xxx 下模型 yyy 无可用渠道」，请联系客服切换到对应分组的令牌。

分组	包含模型	用途
普通分组	gemini-*-image-preview 系列	图片生成
企业分组	gemini-2.5-flash gemini-2.5-pro gemini-3-*-preview 等	文本对话 / 多模态识别

文本对话模型

model	用途
gemini-2.5-flash	快速、便宜，常用首选
gemini-2.5-pro	高质量推理
gemini-3-pro-preview	Gemini 3 Pro 预览
gemini-3-pro-preview-thinking	Gemini 3 Pro 推理增强
gemini-3-flash-preview	Gemini 3 Flash
gemini-3-flash-preview-thinking	Gemini 3 Flash 推理增强
gemini-3.1-pro-preview	Gemini 3.1 Pro
gemini-3.1-pro-preview-thinking	Gemini 3.1 Pro 推理增强

参数

字段	类型	必填	说明
contents	array	是	对话内容列表
contents[].role	string	是	user 或 model（不是 assistant）
contents[].parts	array	是	内容部件，可多个并存
contents[].parts[].text	string	—	文本部分
contents[].parts[].inline_data	object	—	多模态输入
contents[].parts[].inline_data.mime_type	string	—	见下方 mime 表
contents[].parts[].inline_data.data	string	—	Base64（不含 data: 前缀）
generationConfig.temperature	number	否	0~2
generationConfig.topP / topK	—	否
generationConfig.maxOutputTokens	int	否	最大输出 token 数
generationConfig.stopSequences	array	否	停止序列
generationConfig.thinkingConfig.thinkingBudget	int	否	推理 token 预算，传 0 关闭推理
safetySettings	array	否	安全阈值 [{category, threshold}]
tools	array	否	工具调用
systemInstruction	object	否	系统指令 {parts:[{text:"..."}]}

多模态 mime_type

• 图片：image/png image/jpeg image/webp
• PDF：application/pdf
• 音频：audio/mpeg audio/mp3 audio/wav
• 视频：video/mp4 video/mov

心流仅支持 inline_data Base64，不支持 Google 原版的 fileData.fileUri。

多模态请求示例

{
  "contents": [{
    "role": "user",
    "parts": [
      {
        "inline_data": {
          "mime_type": "image/png",
          "data": "iVBORw0KGgo..."
        }
      },
      { "text": "这张图里有什么？" }
    ]
  }],
  "generationConfig": { "maxOutputTokens": 200 }
}

返回字段

字段	说明
candidates[].content.parts[].text	模型回复文本
candidates[].finishReason	STOP 正常 / MAX_TOKENS 截断 / SAFETY 安全过滤 / RECITATION 版权命中
usageMetadata.thoughtsTokenCount	推理 token 用量（单独计费）
usageMetadata.promptTokensDetails	拆分 TEXT 和 IMAGE token

请求示例（纯文本）

curl https://cdn.wusag.com/v1beta/models/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer 你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "你好，请介绍一下你自己"}]
    }],
    "generationConfig": {"maxOutputTokens": 200}
  }'

请求示例（多模态识图）

# 先把图片转 base64
B64=$(base64 -w0 < your_image.png)

curl https://cdn.wusag.com/v1beta/models/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer 你的令牌" \
  -H "Content-Type: application/json" \
  -d "{
    \"contents\": [{
      \"role\": \"user\",
      \"parts\": [
        {\"inline_data\": {\"mime_type\": \"image/png\", \"data\": \"$B64\"}},
        {\"text\": \"这张图里有什么？\"}
      ]
    }],
    \"generationConfig\": {\"maxOutputTokens\": 200}
  }"

返回示例（纯文本）

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "你好！"}]
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 6,
    "candidatesTokenCount": 1,
    "totalTokenCount": 22,
    "thoughtsTokenCount": 15,
    "promptTokensDetails": [{"modality": "TEXT", "tokenCount": 6}]
  },
  "modelVersion": "gemini-2.5-flash"
}

返回示例（多模态）

多模态请求的 usageMetadata.promptTokensDetails 会拆出 TEXT 和 IMAGE 两类 token：

{
  "candidates": [{
    "content": {"role": "model", "parts": [{"text": "Red"}]},
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 273,
    "candidatesTokenCount": 1,
    "totalTokenCount": 319,
    "thoughtsTokenCount": 45,
    "promptTokensDetails": [
      {"modality": "TEXT", "tokenCount": 15},
      {"modality": "IMAGE", "tokenCount": 258}
    ]
  }
}

错误码

• 400 参数错误
• 401 令牌无效或未提供
• 402 余额不足
• 404 模型不存在或未开通
• 429 速率限制
• 500 服务端错误