千云开发者中心

Appearance

Gemini 多模态非流式生成 ​

POST/v1/gemini/models/{model}:generateContent

Gemini 多模态非流式生成

用于 Gemini 协议非流式生成。请求体 contents.parts 支持 text、inlineData 和 fileData，适合图文问答、OCR、图片理解等图片输入场景；这不是单独的图片生成接口。网关支持 Authorization: Bearer sk-...、x-goog-api-key: sk-... 或 query key=sk-...；进入代理后复用平台模型权限、余额预检、用量采集、日志与计费链路。

基础信息

鉴权Authorization: Bearer sk-... / x-goog-api-key: sk-... / ?key=sk-...
请求类型application/json
响应类型application/json

请求参数

Path

字段
类型
必填
位置
说明
model
string
是
path
平台模型 ID，写在 Gemini 路径中。
示例："gemini-2.5-flash"

Body

字段
类型
必填
位置
说明
contents
array<object>
是
body
Gemini 内容数组。parts 支持 text、inlineData 和 fileData，可用于图文问答、OCR、图片理解等图片输入场景。
role
string
否
body
内容角色。
示例："user"
parts
array<object>
是
body
内容片段。
systemInstruction
object
否
body
系统指令；官方文档当前说明为 text only。
role
string
否
body
内容角色。
示例："user"
parts
array<object>
是
body
内容片段。
tools
array<object>
否
body
工具列表。
functionDeclarations
array<object>
否
body
函数声明列表。
googleSearchRetrieval
object
否
body
Google Search 检索工具。
codeExecution
object
否
body
代码执行工具。
googleSearch
object
否
body
Google Search 工具。
computerUse
object
否
body
Computer Use 工具。
urlContext
object
否
body
URL 上下文工具。
toolConfig
object
否
body
工具配置。
functionCallingConfig
object
否
body
函数调用策略。
retrievalConfig
object
否
body
检索策略。
safetySettings
array<object>
否
body
安全设置。
category
string
是
body
安全分类。
示例："HARM_CATEGORY_HATE_SPEECH"
threshold
string
是
body
安全阈值。
示例："BLOCK_ONLY_HIGH"
generationConfig
object
否
body
生成配置。
candidateCount
integer
否
body
候选数。
示例：1
stopSequences
array<string>
否
body
停止序列。
示例：["</end>"]
maxOutputTokens
integer
否
body
最大输出 token 数。
示例：512
temperature
number
否
body
温度。
示例：0.7
topP
number
否
body
Top-p。
示例：0.95
topK
integer
否
body
Top-k。
示例：40
seed
integer
否
body
随机种子。
示例：42
responseMimeType
string
否
body
候选输出 MIME 类型。
示例："application/json"
responseSchema
object
否
body
候选输出 Schema。
responseJsonSchema
object
否
body
候选输出 JSON Schema。
responseModalities
array<string>
否
body
响应模态。
示例：["TEXT"]
presencePenalty
number
否
body
出现惩罚。
示例：0
frequencyPenalty
number
否
body
频率惩罚。
示例：0
responseLogprobs
boolean
否
body
是否返回 logprobs。
示例：false
logprobs
integer
否
body
每步返回的 top logprobs 数量。
示例：5
enableEnhancedCivicAnswers
boolean
否
body
是否启用增强 civic 回答。
示例：false
speechConfig
object
否
body
语音生成配置。
thinkingConfig
object
否
body
思考配置。
imageConfig
object
否
body
图像生成配置。
mediaResolution
string
否
body
媒体分辨率。
示例："HIGH"
cachedContent
string
否
body
缓存内容名称。
示例："cachedContents/abc123"
serviceTier
string
否
body
服务层级。
示例："standard"
store
boolean
否
body
是否记录请求日志。
示例：false

请求示例

json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请识别图片中的文字，并总结画面内容。"
        },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAIAAABMXPacAAABXUlEQVR42u3dwQnCQBBA0VRhAbZhLzaRDuzNdjyJ4MkcBJG4kihmZiQv/Armkcu6E7vT+abEOiMAAEAAAAgAAAEAIAAABACAAAAQAAACAEAAAAgAAJUB8DQfAAAAAAAAAAAAAAAAAAAA4G+e7XEPIHTccwKQM/evJQD8fvQfMVQB2B0ukcVMf44BgGWnP2kAYNnRTzIACJr+OwMAAGoABEy/aQAgdPqvBgCipz8yAAAgFSBl+s8GAAAAWC1A4vQfBgAAAAAAAAAAAMEA6dO/5w3wBgAAAAAAAAAAnIY6DQUAAIDfhAEAcC/IzTg349wNBQDAfoANGRsydsRsSa5gS9KeMACb8r4VAcDXUgAAAAAAAAAAAACMn2u/qRwAAAAAAAAAAAAAAAAAAAAAwFmQsyAAAAAAqAAgf2cLQAAACAAAAQAgAAAEAIAAABAAAAIAQAAACAAAAQAgAADUagAbMOXIAHaxNAAAAABJRU5ErkJggg=="
          }
        },
        {
          "fileData": {
            "mimeType": "image/jpeg",
            "fileUri": "https://example.com/sample.jpg"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 512
  }
}

响应示例

json
{
  "responseId": "resp-123",
  "modelVersion": "gemini-2.5-flash",
  "promptFeedback": {
    "blockReason": null,
    "safetyRatings": []
  },
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "千云模型网关提供统一模型 API 接入、权限控制与计费能力。"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [],
      "citationMetadata": {},
      "tokenCount": 28,
      "groundingMetadata": {},
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "cachedContentTokenCount": 0,
    "candidatesTokenCount": 28,
    "toolUsePromptTokenCount": 0,
    "thoughtsTokenCount": 0,
    "totalTokenCount": 40,
    "promptTokensDetails": [],
    "cacheTokensDetails": [],
    "candidatesTokensDetails": [],
    "toolUsePromptTokensDetails": []
  }
}

响应字段

字段
类型
必填
位置
说明
responseId
string
否
body
响应 ID。
示例："resp-123"
modelVersion
string
否
body
用于生成响应的模型版本。
示例："gemini-2.5-flash"
promptFeedback
object
否
body
提示过滤反馈。
blockReason
string
否
body
提示被屏蔽原因。
示例："SAFETY"
safetyRatings
array<object>
否
body
提示安全评分。
candidates
array<object>
否
body
候选响应。
content
object
否
body
模型生成内容。
finishReason
string
否
body
停止原因。
示例："STOP"
safetyRatings
array<object>
否
body
候选安全评分。
citationMetadata
object
否
body
引用元数据。
tokenCount
integer
否
body
候选 token 数。
示例：28
groundingAttributions
array<object>
否
body
检索归因信息。
groundingMetadata
object
否
body
检索 grounding 元数据。
avgLogprobs
number
否
body
平均 log 概率。
示例：-0.4
logprobsResult
object
否
body
logprobs 结果。
urlContextMetadata
object
否
body
URL 上下文元数据。
index
integer
否
body
候选索引。
示例：0
finishMessage
string
否
body
停止原因详情。
usageMetadata
object
否
body
token 使用统计。
promptTokenCount
integer
否
body
提示 token 数。
示例：12
cachedContentTokenCount
integer
否
body
缓存内容 token 数。
示例：0
candidatesTokenCount
integer
否
body
候选 token 总数。
示例：28
toolUsePromptTokenCount
integer
否
body
工具使用 prompt token 数。
示例：0
thoughtsTokenCount
integer
否
body
思考 token 数。
示例：0
totalTokenCount
integer
否
body
总 token 数。
示例：40
promptTokensDetails
array<object>
否
body
提示输入的模态统计。
cacheTokensDetails
array<object>
否
body
缓存输入的模态统计。
candidatesTokensDetails
array<object>
否
body
响应输出的模态统计。
toolUsePromptTokensDetails
array<object>
否
body
工具使用 prompt 的模态统计。

错误码

HTTPcode说明
400invalid_request_error请求体结构不合法、缺少必填参数，或 JSON 无法解析。
401invalid_auth_header缺少或传错鉴权头，网关无法识别当前调用身份。
403model_not_allowed当前 API Key 没有访问该模型的权限。
402insufficient_balance余额不足，平台在调用前预检时已拒绝请求。
503model_not_available当前模型没有可用路由或上游渠道不可用。

在线调试

Playground · 浏览器直连网关

Gemini 多模态非流式生成

兼容 Gemini generateContent 协议，支持文本和图片输入，返回 candidates、promptFeedback 与 usageMetadata。

提示：正式路径为 /v1/gemini

提示：也可使用 x-goog-api-key 或 query key 传递同一个平台 sk API Key。

提示：图片输入放在 contents.parts 中；inlineData 用于 Base64 图片，fileData 用于已上传或可访问的图片 URI。

提示：本页用于图片理解、OCR 和图文问答；Gemini 文生图和图生图请使用本分组下的对应入口。

json
尚未发起请求。
bash
curl --location --request POST 'https://api.harnmodel.com/v1/gemini/models/gemini-2.5-flash:generateContent' \
  --header 'Authorization: Bearer sk-xxx' \
  --header 'Content-Type: application/json' \
  --data '{}'

多语言示例

bash
curl --location --request POST 'https://api.harnmodel.com/v1/gemini/models/gemini-2.5-flash:generateContent' \
  --header 'Authorization: Bearer sk-xxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请识别图片中的文字，并总结画面内容。"
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAIAAABMXPacAAABXUlEQVR42u3dwQnCQBBA0VRhAbZhLzaRDuzNdjyJ4MkcBJG4kihmZiQv/Armkcu6E7vT+abEOiMAAEAAAAgAAAEAIAAABACAAAAQAAACAEAAAAgAAJUB8DQfAAAAAAAAAAAAAAAAAAAA4G+e7XEPIHTccwKQM/evJQD8fvQfMVQB2B0ukcVMf44BgGWnP2kAYNnRTzIACJr+OwMAAGoABEy/aQAgdPqvBgCipz8yAAAgFSBl+s8GAAAAWC1A4vQfBgAAAAAAAAAAAMEA6dO/5w3wBgAAAAAAAAAAnIY6DQUAAIDfhAEAcC/IzTg349wNBQDAfoANGRsydsRsSa5gS9KeMACb8r4VAcDXUgAAAAAAAAAAAACMn2u/qRwAAAAAAAAAAAAAAAAAAAAAwFmQsyAAAAAAqAAgf2cLQAAACAAAAQAgAAAEAIAAABAAAAIAQAAACAAAAQAgAADUagAbMOXIAHaxNAAAAABJRU5ErkJggg=="
            }
          }
        ]
      }
    ]
  }'

千云开发者中心仅维护中文第一版文档；接口口径以当前后端实现为准。

Copyright © 2026 千云（上海）信息科技有限公司