创建对话请求（Gemini）

Cloubie 的 Gemini 原生 Chat Completions 接口面向已经接入 Google Gemini 生态的团队，提供一条与官方接口格式高度一致的迁移路径。平台在协议层兼容 Gemini 官方 models/{model}:streamGenerateContent / generateContent 规范：请求体沿用 model、contents（多模态内容块）、tools、toolConfig 等字段设计，并支持流式响应与函数调用。

1️⃣ Gemini 官方 SDK 不支持 base_url 切换，只能使用 REST API 的方式调用 Token Hubs 的 Gemini 接口。

请求

Endpoint

POST https://api.token-hubs.com/v1beta/{model=models}

Headers

Authorizationstring必填

Bearer Token，格式：Bearer YOUR_API_KEY

Content-Typestring必填

请求体格式，固定为 application/json

modelstring必填

用于生成补全的 Model 的名称，格式：models/{model}。

示例请求

https://api.token-hubs.com/v1beta/{model=models} \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "contents": [{
    "parts": [{"text": "Write a story about a magic backpack"}]
  }]
}'

Request Body

contentsobject array必填

与模型当前对话的内容，对于单轮查询，这是单个实例。对于多轮查询（例如聊天），这是包含对话历史记录和最新请求的重复字段。

rolestring（可选）：
内容的制作方，必须是 "user" 或 "model"
partsobject array（必填）：
part 由具有关联数据类型的数组组成
- thoughtbool（可选）：
  表示相应部分是否由模型生成
- thoughtSignaturestring（可选）：
  一种不透明的思路签名，以便在后续请求中重复使用；使用 base64 编码的字符串
- partMetadataobject（可选）：
  与部件关联的自定义元数据
- dataUnion type（必填）：
  - textstring：
    内嵌文本
  - inlineDataobject：
    - mimeTypestring：
      来源数据的 IANA 标准 MIME 类型。示例：image/png、image/jpeg
    - datastring (bytes format)：
      媒体格式的原始字节，使用 base64 编码的字符串
  - functionCallobject：
    - namestring（必填）：
      要调用的函数名称，必须是 a-z、A-Z、0-9 或包含下划线和短划线，长度上限为 64
    - argsobject (Struct format)（可选）：
      以 JSON 对象格式表示的函数参数和值
  - functionResponseobject：
    FunctionCall 的结果输出
    - namestring（必填）：
      要调用的函数名称
    - responseobject (Struct format)（必填）：
      以 JSON 对象格式表示的函数响应
  - fileDataobject：
    基于 URI 的数据
    - mimeTypestring（可选）：
      来源数据的 IANA 标准 MIME 类型
    - fileUristring（必填）：
      URI
  - executableCodeobject：
    模型生成的旨在执行的代码
    - languageenum（必填）：
      code 的编程语言
    - codestring（必填）：
      code 代码
  - codeExecutionResultobject：
    执行 ExecutableCode 的结果
    - outcomeenum（必填）：
      代码执行结果
    - outputstring（可选）：
      如果代码执行成功，则包含 stdout；否则包含 stderr 或其他说明

toolsobject array

仅限输入。不可变。模型可能用于生成下一个回答的 Tools 列表。

toolConfigobject

请求中指定的任何 Tool 的工具配置。

functionCallingConfigobject（可选）：
函数调用配置
- modestring（可选）：
  指定函数调用应以何种模式执行。如果未指定，则默认值将设置为 AUTO。
- allowedFunctionNamesstring array（可选）：
  一组函数名称，提供后可限制模型将调用的函数。仅当模式为 "ANY" 或 "VALIDATED" 时，才应设置此字段。
retrievalConfigobject（可选）：
检索配置

safetySettingsobject array

用于屏蔽不安全内容的唯一 SafetySetting 实例的列表。

systemInstructionobject

开发者设置了系统指令。目前仅限文本。

generationConfigobject

模型生成和输出的配置选项。

stopSequencesstring array（可选）：
将停止输出生成的字符序列集（最多 5 个）
responseMimeTypestring（可选）：
生成的候选文本的 MIME 类型。支持的 MIME 类型包括：text/plain（默认）文本输出
responseSchemaobject（可选）：
生成的候选文本的输出结构，可以是对象、基元或数组
responseModalitiesenum array（可选）：
请求的响应模态。支持以下模态：
- MODALITY_UNSPECIFIED：
  默认值
- TEXT：
  表示模型应返回文本
- IMAGE：
  表示模型应返回图片
- AUDIO：
  表示模型应返回音频
candidateCountinteger（可选）：
要返回的生成响应的数量。如果未设置，则默认为 1
maxOutputTokensinteger（可选）：
候选回答中包含的 token 数量上限
temperaturenumber（可选）：
控制输出的随机性，值介于 [0.0, 2.0] 之间
topPnumber（可选）：
抽样时要考虑的 token 的最大累积概率
topKinteger（可选）：
抽样时要考虑的令牌数量上限，一般 topP 和 topK 只设置一个
seedinteger（可选）：
解码中使用的种子。如果未设置，请求会使用随机生成的种子
presencePenaltynumber（可选）：
如果下一个令牌已在响应中出现，则对该令牌的 logprobs 应用存在惩罚
frequencyPenaltynumber（可选）：
应用于下一个令牌的 logprobs 的频次惩罚
responseLogprobsbool（可选）：
如果为 true，则在响应中导出 logprobs 结果
logprobsinteger（可选）：
仅在 responseLogprobs=True 时有效。该数字必须介于 [0, 20] 之间
speechConfigobject（可选）：
语音生成配置
- voiceConfigobject：
  单语言输出时的配置
- multiSpeakerVoiceConfigobject：
  多语言设置的配置，它与 voiceConfig 字段互斥
- languageCodestring：
  用于语音合成的语言代码（采用 BCP 47 格式，例如 "en-US"）
thinkingConfigobject（可选）：
思考功能的配置
- includeThoughtsbool：
  指示是否在回答中包含想法
- thinkingBudgetinteger：
  模型应生成的想法 token 的数量
- thinkingLevelenum：
  控制模型在生成回答之前的内部推理过程的最大深度
imageConfigobject（可选）：
图片生成配置
- aspectRatiostring：
  要生成的图片的宽高比。支持的宽高比：1:1、2:3、3:2、4:3、9:16、16:9、21:9
- imageSizestring：
  指定生成的图片的大小。支持的值为 1K、2K、4K
mediaResolutionenum（可选）：
输入媒体的媒体分辨率
- MEDIA_RESOLUTION_UNSPECIFIED：
  媒体分辨率尚未设置
- MEDIA_RESOLUTION_LOW：
  媒体分辨率设置为低（64 个 token）
- MEDIA_RESOLUTION_MEDIUM：
  媒体分辨率设置为中等（256 个 token）
- MEDIA_RESOLUTION_HIGH：
  媒体分辨率设置为高（缩放重构，256 个 token）

cachedContentstring

用作提供预测的上下文的缓存内容的名称。格式：cachedContents/{cachedContent}

Response Body

candidatesobject array

模型生成的候选回答列表。每个候选包含生成的内容、完成原因等信息。

contentContent：
模型返回的生成内容
- rolestring（可选）：
  内容的制作方，必须是 "user" 或 "model"
- partsobject array（必填）：
  part 由具有关联数据类型的数据组成
finishReasonFinishReason：
模型停止生成 token 的原因。如果为空，表示模型尚未停止生成
safetyRatingsarray<SafetyRating>：
响应候选项的安全性评分列表，每个类别最多一个评分
citationMetadataCitationMetadata：
模型生成的候选回答的引用信息
tokenCountinteger：
该候选对象对应的 token 数量
avgLogprobsnumber：
候选者的平均对数概率得分
logprobsResultLogprobsResult：
回答 token 和热门 token 的对数似然得分
urlContextMetadataUrlContextMetadata：
与网址上下文检索工具相关的元数据
indexinteger：
该候选在响应候选列表中的索引
finishMessagestring（可选）：
详细说明模型停止生成 token 的原因

promptFeedbackobject

与内容过滤器相关的提示反馈，例如是否因安全策略被过滤等。

usageMetadataobject

本次生成请求的 token 使用情况元数据。

promptTokenCountinteger：
提示中的 token 数量
cachedContentTokenCountinteger：
提示的缓存部分中的 token 数量
candidatesTokenCountinteger：
所有生成的回答候选的 token 总数
toolUsePromptTokenCountinteger：
工具使用提示中的 token 数量
thoughtsTokenCountinteger：
思考模型的想法的 token 数量
totalTokenCountinteger：
生成请求（提示 + 回答候选）的总 token 数
promptTokensDetailsarray<ModalityTokenCount>：
请求输入中处理的模态列表及其 token 计数
cacheTokensDetailsarray<ModalityTokenCount>：
请求输入缓存内容的模态列表及其 token 计数
candidatesTokensDetailsarray<ModalityTokenCount>：
响应中返回的模态列表及其 token 计数
toolUsePromptTokensDetailsarray<ModalityTokenCount>：
为工具使用请求输入处理的模态列表及其 token 计数

modelVersionstring

实际用于生成回答的模型版本标识。

responseIdstring

用于唯一标识每个响应的 ID，便于追踪与调试。

响应示例

示例响应（JSON 格式）

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "这是一个关于魔法背包的故事。从前，有一个名叫艾米的小女孩，她在一个古老的古董店里发现了一个看起来普通的背包。然而，当她第一次使用它时，她发现这个背包有着神奇的能力——无论她放进去什么，背包都会自动整理并扩大内部空间。"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ],
      "tokenCount": 156,
      "index": 0
    }
  ],
  "promptFeedback": {
    "blockReason": "BLOCK_REASON_UNSPECIFIED"
  },
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 156,
    "totalTokenCount": 168,
    "cachedContentTokenCount": 0
  },
  "modelVersion": {
    "version": "gemini-2.0-flash-exp",
    "launchDate": {
      "year": 2024,
      "month": 12,
      "day": 11
    }
  },
  "responseId": "chatcmpl-abc123xyz456"
}

代码示例

Python 示例

使用 Google SDK（推荐）

from google import genai

client = genai.Client(
    api_key="YOUR_API_KEY",
    http_options={"base_url": "https://api.token-hubs.com"},
)

# 非流式调用
response = client.models.generate_content(
    model="gemini-3.1-pro-preview", contents="你好，请介绍一下你自己"
)
print(response.text)

# 流式调用
response = client.models.generate_content_stream(
    model="gemini-3.1-pro-preview",
    contents=["你好, 介绍一下你自己"]
)
for chunk in response:
    print(chunk.text, end="")

Go 示例

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

type GeminiRequest struct {
    Contents []Content `json:"contents"`
}

type Content struct {
    Parts []Part `json:"parts"`
}

type Part struct {
    Text string `json:"text"`
}

type GeminiResponse struct {
    Candidates []struct {
        Content struct {
            Parts []Part `json:"parts"`
        } `json:"content"`
    } `json:"candidates"`
}

func main() {
    reqBody := GeminiRequest{
        Contents: []Content{
            {Parts: []Part{{Text: "你好"}}},
        },
    }

    jsonData, _ := json.Marshal(reqBody)
    url := "https://api.token-hubs.com/v1beta/models/gemini-2.0-flash-exp:generateContent"
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-goog-api-key", "YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    var result GeminiResponse
    json.Unmarshal(body, &result)
    
    fmt.Println(result.Candidates[0].Content.Parts[0].Text)
}

Node.js 示例

使用 Google SDK（推荐）

const { GoogleGenerativeAI } = require('@google/generative-ai');

const genAI = new GoogleGenerativeAI('YOUR_API_KEY');

// 非流式调用
async function main() {
    const model = genAI.getGenerativeModel({ 
        model: 'gemini-2.0-flash-exp',
        baseUrl: 'https://api.token-hubs.com'
    });

    const result = await model.generateContent('你好，请介绍一下你自己');
    console.log(result.response.text());
}

main();

// 流式调用
const { GoogleGenerativeAI } = require('@google/generative-ai');

const genAI = new GoogleGenerativeAI('YOUR_API_KEY');

async function main() {
    const model = genAI.getGenerativeModel({ 
        model: 'gemini-2.0-flash-exp',
        baseUrl: 'https://api.token-hubs.com'
    });

    const result = await model.generateContentStream('讲个笑话');
    
    for await (const chunk of result.stream) {
        process.stdout.write(chunk.text());
    }
}

main();

#创建对话请求（Gemini）

#请求

#Endpoint

#Headers

#示例请求

#Request Body

#Response Body

#响应示例

#示例响应（JSON 格式）

#代码示例

#Python 示例

#使用 Google SDK（推荐）

#Go 示例

#Node.js 示例

#使用 Google SDK（推荐）

创建对话请求（Gemini）

请求

Endpoint

Headers

示例请求

Request Body

Response Body

响应示例

示例响应（JSON 格式）

代码示例

Python 示例

使用 Google SDK（推荐）

Go 示例

Node.js 示例

使用 Google SDK（推荐）