# Gemini 原生接口 (https://hypit.ai/zh/api-reference/gemini/)

> 原样透传 Google 自己的协议格式——给已经按 GenAI SDK 写好的代码用。

有些项目是按 Google 原生 API 写的，而不是 OpenAI 形状：用 `contents` 而不是 `messages`，用 `parts`
而不是 `content`，用 `usageMetadata` 而不是 `usage`。把这些改写成 OpenAI 客户端是不该由你承担的
工作量，所以 hypit.ai 直接提供原生格式。

```text
POST https://hypit.ai/v1beta/models/{model}:{action}
```

注意这里是 `/v1beta`，**不是** `/v1`。请求体逐字节转发给 Google，响应原样返回。

## 支持的 action [#支持的-action]

只有三个：

| Action                  | 行为                                      |
| ----------------------- | --------------------------------------- |
| `generateContent`       | 缓冲式 JSON 响应                             |
| `streamGenerateContent` | 默认 SSE；`?alt=json` 返回 Google 的 JSON 帧数组 |
| `countTokens`           | 缓冲式，且**不计费**                            |

其余一律返回 `404 unsupported_action`，包括 `embedContent`、`batchEmbedContents`、`predict` 和文件
上传。这条路径只注册了 `POST`；对它发 `GET` 会得到普通的 `404`。

```bash
curl "https://hypit.ai/v1beta/models/gemini-3.1-pro:generateContent" \
  -H "x-goog-api-key: $HYPIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Hypit 是什么？一句话。"}]}]
  }'
```

流式：

```bash
curl -N "https://hypit.ai/v1beta/models/gemini-3.1-pro:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $HYPIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"parts": [{"text": "写一首关于纸船的俳句。"}]}]}'
```

`streamGenerateContent` 不带 `alt` 参数时默认按 `alt=sse` 处理，与 Google 一致。这条接口上
**没有 `[DONE]` 哨兵**——Google 不发它，而我们如果补上，官方 SDK 会试图把它当成
`GenerateContentResponse` 去解码。

## 认证 [#认证]

用的是和别处一样的 hypit.ai `sk-hh-` Key，位置可以按 Google 客户端的习惯放：

```bash
-H "x-goog-api-key: $HYPIT_API_KEY"      # GenAI SDK 发的头
-H "Authorization: Bearer $HYPIT_API_KEY"
"…:generateContent?key=$HYPIT_API_KEY"   # REST 写法
```

无论用哪种，凭据在转发前都会从查询串里剥掉——`key`、`api_key`、`apikey`、`access_token` 都会被
移除。其余查询参数原样转发。

## 把 Google SDK 指过来 [#把-google-sdk-指过来]

```python
import os
from google import genai

client = genai.Client(
    api_key=os.environ["HYPIT_API_KEY"],
    http_options={"base_url": "https://hypit.ai"},
)

response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="Hypit 是什么？一句话。",
)
print(response.text)
```

```js
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.HYPIT_API_KEY,
  httpOptions: { baseUrl: "https://hypit.ai" },
});

const response = await ai.models.generateContent({
  model: "gemini-3.1-pro",
  contents: "Hypit 是什么？一句话。",
});
console.log(response.text);
```

这里的 base URL 是**站点 origin**，不带 `/v1beta`——版本段由 SDK 自己补。

## 模型名里带冒号 [#模型名里带冒号]

Google 的 URL 把 action 放在最后一段里、跟在一个字面冒号之后。我们按**最后一个**冒号切分，所以
模型名本身带冒号也能正确解析：

```text
/v1beta/models/tunedModels/my-tune:generateContent   →  模型 "tunedModels/my-tune"
```

如果路径里没有字面冒号，百分号编码的 `%3A` 也会被解码。

## 哪些模型可用 [#哪些模型可用]

模型卡片的 `endpoints` 里含 `gemini` 就能走这条路由：

```bash
curl -s https://hypit.ai/v1/models \
  -H "Authorization: Bearer $HYPIT_API_KEY" |
  jq -r '.data[] | select(.endpoints[] == "gemini") | .id'
```

这些模型通常同时也能走 `/v1/chat/completions`——同一张模型卡片往往 `chat` 和 `gemini` 都列。用你
现有代码已经会说的那种协议即可，计费完全一样。

## 错误 [#错误]

<Callout type="warn" title="错误用的是 OpenAI 信封，不是 Google 的">
  Google 返回 `{"error": {"code": 400, "message": "…", "status": "INVALID_ARGUMENT"}}`。hypit.ai 在
  所有接口上都返回自己的形状，这一条也不例外：

  ```json
  {
    "error": {
      "message": "action \"embedContent\" is not supported; use generateContent, streamGenerateContent or countTokens",
      "type": "not_found_error",
      "code": "unsupported_action",
      "param": null
    }
  }
  ```

  Google SDK 会看到一个它不认识的错误体。请自行处理非 2xx 响应，不要依赖 SDK 的错误解析。
</Callout>

| 状态    | `code`               | 含义                                     |
| ----- | -------------------- | -------------------------------------- |
| `404` | `unknown_route`      | 路径不是 `/v1beta/models/{model}:{action}` |
| `404` | `unsupported_action` | 不在上述三个 action 之内                       |
| `400` | `bad_request_body`   | 传了请求体但它不是 JSON 对象                      |
| `413` | `request_too_large`  | 超过 32 MiB                              |
| `502` | `empty_stream`       | 上游没有产生任何帧                              |

[错误与限流](/zh/api-reference/errors)里的内容在这条路由上同样适用——它和 `/v1` 走的是同一套认证、
限流与额度闸门。