# Gemini 兼容接口

https://modelportal.ai/docs/api-gemini?lang=zh

REST 前缀 `https://modelportal.ai/v1beta`，鉴权用 `x-goog-api-key: YOUR_API_KEY`、查询参数 `key=YOUR_API_KEY` 或 `Authorization: Bearer YOUR_API_KEY`，带了几处时必须相同。请求与响应格式与 Gemini API 一致。路径里的 `{模型}` 是模型 ID，斜杠可以直接写，也可以写成 `%2F`。

## POST /v1beta/models/{模型}:generateContent

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `contents` | array | 是 | 对话内容，`parts` 支持 `text`、`inlineData`、`fileData`、`functionCall`、`functionResponse` |
| `systemInstruction` | object | 否 | 系统提示 |
| `generationConfig` | object | 否 | `temperature`、`topP`、`topK`、`maxOutputTokens`、`candidateCount`、`responseMimeType`、`responseSchema`、`thinkingConfig` 等；不填 `maxOutputTokens` 时平台按模型上限和可用余额补一个值 |
| `tools`、`toolConfig` | — | 否 | 函数调用 |

```json
{
  "candidates": [{"content": {"role": "model", "parts": [{"text": "你好！"}]}, "finishReason": "STOP"}],
  "usageMetadata": {"promptTokenCount": 9, "candidatesTokenCount": 4, "totalTokenCount": 13, "cost": 0.000013},
  "provider": "PROVIDER_ID",
  "attempts": [{"provider": "PROVIDER_ID", "endpoint": "ENDPOINT_ID", "status": 200, "cost": 0.000013}],
  "modelVersion": "MODEL_ID"
}
```

`usageMetadata` 是计费用量：`promptTokenCount` 含缓存读写，`candidatesTokenCount` 不含推理，`thoughtsTokenCount`、`cachedContentTokenCount` 单列。`usageMetadata.cost` 是这次的扣费（USD），`provider`、`attempts` 是承接的供应商和每次尝试；流式时这三项写在带 `usageMetadata` 的最后一段里。响应头见[接口概览](/docs/api-overview)。

## POST /v1beta/models/{模型}:streamGenerateContent

请求体同 `generateContent`。带 `?alt=sse` 时以 SSE 返回；不带时返回 JSON 数组。

## POST /v1beta/models/{模型}:countTokens

计算输入 token 数，不计费。请求体可以是 `contents`，也可以是 `generateContentRequest`。

## POST /v1beta/models/{模型}:embedContent 与 :batchEmbedContents

生成向量，模型要具备向量能力。`batchEmbedContents` 里每条的 `model` 必须为空或与路径里的模型相同。

## GET /v1beta/models

列出这把密钥能调用的模型，以及每个模型支持的方法和 token 上限。

## 错误

错误体为 `{"error": {"code", "message", "status"}}`，`code` 是 HTTP 状态码，`status` 只由它决定：

| HTTP | `status` |
| --- | --- |
| 400、422 | `INVALID_ARGUMENT` |
| 401 | `UNAUTHENTICATED` |
| 402、429 | `RESOURCE_EXHAUSTED` |
| 403 | `PERMISSION_DENIED` |
| 404、410 | `NOT_FOUND` |
| 502、503 | `UNAVAILABLE` |

422 时 `error.excluded` 列出排除原因。各状态对应的平台错误码见[常见错误](/docs/errors)。