# Google Gemini 兼容接口 (/docs/api/compatible/google)



## 基础地址 [#基础地址]

<ApiBaseDomain prefix="/google" />

## 接入 [#接入]

<QuickstartTabs snippets="{&#x22;curl&#x22;:&#x22;curl https://api-origin.invalid/google/v1beta/models/gemini-2.5-flash:generateContent \\\n  -H \&#x22;x-goog-api-key: $PRAXIS_API_KEY\&#x22; \\\n  -H \&#x22;Content-Type: application/json\&#x22; \\\n  -d '{\&#x22;contents\&#x22;:[{\&#x22;role\&#x22;:\&#x22;user\&#x22;,\&#x22;parts\&#x22;:[{\&#x22;text\&#x22;:\&#x22;你好\&#x22;}]}]}'&#x22;,&#x22;python&#x22;:&#x22;import os\n\nfrom google import genai\nfrom google.genai import types\n\nclient = genai.Client(\n    api_key=os.environ[\&#x22;PRAXIS_API_KEY\&#x22;],\n    http_options=types.HttpOptions(base_url=\&#x22;https://api-origin.invalid/google\&#x22;),\n)\n\nresp = client.models.generate_content(\n    model=\&#x22;gemini-2.5-flash\&#x22;,\n    contents=\&#x22;你好\&#x22;,\n)\nprint(resp.text)&#x22;,&#x22;typescript&#x22;:&#x22;import { GoogleGenAI } from \&#x22;@google/genai\&#x22;;\n\nconst ai = new GoogleGenAI({\n  apiKey: process.env.PRAXIS_API_KEY,\n  httpOptions: { baseUrl: \&#x22;https://api-origin.invalid/google\&#x22; },\n});\n\nconst resp = await ai.models.generateContent({\n  model: \&#x22;gemini-2.5-flash\&#x22;,\n  contents: \&#x22;你好\&#x22;,\n});\nconsole.log(resp.text);&#x22;}" />

## 可用模型 [#可用模型]

* 路径里的模型名就是平台模型名（如 `gemini-2.5-flash`），可用模型见[列出模型](/docs/api/compatible/google/listModels)。只有声明了 Google 协议的模型可以在这里调用，其他模型返回 404。
* 需要图片输出时，在 `generationConfig.responseModalities` 里带上 `IMAGE`，请求会交给平台的图像模型处理。
* 在思考模型上强制调用工具（`toolConfig` 的 `ANY` 模式）与 Gemini 原生 API 一致，会原样转发给模型：模型接受即执行，不接受时返回 Google 格式的 400 错误。

## 端点 [#端点]

| 方法   | 路径                                                                                                     | 说明       | 支持     |
| ---- | ------------------------------------------------------------------------------------------------------ | -------- | ------ |
| POST | [`/v1beta/models/{modelsId}:generateContent`](/docs/api/compatible/google/generateContent)             | 生成内容     | ● 支持   |
| POST | [`/v1beta/models/{modelsId}:streamGenerateContent`](/docs/api/compatible/google/streamGenerateContent) | 流式生成内容   | ● 支持   |
| POST | [`/v1beta/models/{modelsId}:countTokens`](/docs/api/compatible/google/countTokens)                     | 统计 token | ◐ 部分支持 |
| POST | [`/v1beta/models/{modelsId}:embedContent`](/docs/api/compatible/google/embedContent)                   | 生成向量嵌入   | ● 支持   |
| POST | [`/v1beta/models/{modelsId}:batchEmbedContents`](/docs/api/compatible/google/batchEmbedContents)       | 批量生成向量嵌入 | ● 支持   |
| GET  | [`/v1beta/models`](/docs/api/compatible/google/listModels)                                             | 列出模型     | ● 支持   |
| GET  | [`/v1beta/models/{modelsId}`](/docs/api/compatible/google/getModel)                                    | 读取模型     | ● 支持   |

## 与官方的差异 [#与官方的差异]

* <a href="/docs/api/compatible/google/generateContent">生成内容</a>：toolConfig 的强制工具（functionCallingConfig mode ANY，含 allowedFunctionNames） 在思考模型上同样忠实转发给上游——与 Gemini 原生 API 一致，是否接受由上游模型 决定：如果上游返回 400，错误保持 Google 格式并携带上游的代码与状态。
* <a href="/docs/api/compatible/google/countTokens">统计 token</a>：按模型族校准的估算值（包括中文和工具定义），响应头为 x-praxis-token-count: estimated；不能用作精确用量或计费依据。
* <a href="/docs/api/compatible/google/embedContent">生成向量嵌入</a>：只接受文本部件；图像等多模态部件会被拒绝。taskType、title 以及 autoTruncate / documentOcr / audioTrackExtraction 等检索配置在平台上没有等价语义， 请求携带时会收到 400（INVALID\_ARGUMENT），不会静默忽略——因为不同 taskType 生成的向量行为不同，静默丢弃会悄悄改变检索质量。outputDimensionality 映射为 返回向量的维度。
* <a href="/docs/api/compatible/google/batchEmbedContents">批量生成向量嵌入</a>：requests 中每一项的约束与 embedContent 相同（文本部件、同上拒绝规则）；批量内 所有条目的 outputDimensionality 必须一致。当前官方 JS 与 Python SDK 的 embedContent 调用实际走的就是这个批量端点。
* <a href="/docs/api/compatible/google/listModels">列出模型</a>：向量嵌入模型会以 embedContent 作为其唯一受支持的方法列出。当模型目录 暂时不可用时，generateContent 的行为保持不变：显式要求图像输出 （responseModalities 含 IMAGE）的请求仍走图像通道；未显式声明的旧式图像请求 在该窗口内会按文本对话处理——降级期间每个响应都带 X-Praxis-Route-Degraded: model-catalog-unavailable 头以示区别。

参数与字段的权威定义以 [Gemini API 官方文档](https://ai.google.dev/api)为准。

错误按 Gemini API 格式返回，参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。