> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini generateContent — Google 原生格式

> 使用 Google Gemini 原生格式发送请求。Anyone 支持 Gemini SDK 直接调用。

Anyone 在 `/v1beta/models/{model}` 路径下提供 Google Gemini 兼容端点，与 Google AI SDK 和 Gemini REST API 的格式一致。使用 `x-goog-api-key` 头或 `key` 查询参数传入你的 Anyone API key 进行认证——无需 Google 凭据。Anyone 将请求路由到你在 URL 路径中指定的模型对应的上游渠道。

## 端点

| 方法     | 路径                                             | 说明        |
| ------ | ---------------------------------------------- | --------- |
| `POST` | `/v1beta/models/{model}:generateContent`       | 生成响应（非流式） |
| `POST` | `/v1beta/models/{model}:streamGenerateContent` | 流式生成响应    |

模型名在 URL 路径中指定，不在请求体中。例如，要使用 `gemini-3.1-pro-preview`，发送 `POST` 到 `/v1beta/models/gemini-3.1-pro-preview:generateContent`。

## 认证

通过以下任一方式传入 Anyone API key：

**请求头（推荐）：**

```
x-goog-api-key: YOUR_TOKEN
```

**查询参数：**

```
POST /v1beta/models/gemini-3.1-pro-preview:generateContent?key=YOUR_TOKEN
```

## 请求参数

<ParamField body="contents" type="object[]" required>
  对话历史，由内容对象数组组成。每个对象包含 `role` 和 `parts` 数组。

  <Expandable title="内容属性">
    <ParamField body="contents[].role" type="string">
      内容作者的角色。用户轮次用 `"user"`，模型轮次用 `"model"`。单轮请求可省略。
    </ParamField>

    <ParamField body="contents[].parts" type="object[]" required>
      组成该轮次的内容部分数组。

      <Expandable title="part 属性">
        <ParamField body="contents[].parts[].text" type="string">
          文本部分。用于纯文本输入或与其他模态一起提供文本。
        </ParamField>

        <ParamField body="contents[].parts[].inlineData" type="object">
          内联二进制数据（如 base64 编码的图片或音频）。

          <Expandable title="inlineData 属性">
            <ParamField body="contents[].parts[].inlineData.mimeType" type="string" required>
              数据的 MIME 类型，例如 `"image/jpeg"`、`"audio/mp3"` 或 `"video/mp4"`。
            </ParamField>

            <ParamField body="contents[].parts[].inlineData.data" type="string" required>
              Base64 编码的字节数据。
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="contents[].parts[].fileData" type="object">
          通过 URI 引用的文件，例如 Google Cloud Storage URI 或 Files API URI。

          <Expandable title="fileData 属性">
            <ParamField body="contents[].parts[].fileData.mimeType" type="string">
              文件的 MIME 类型。
            </ParamField>

            <ParamField body="contents[].parts[].fileData.fileUri" type="string" required>
              文件的 URI。
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="contents[].parts[].functionCall" type="object">
          模型请求的 function calling。包含 `name` 和 `args`。
        </ParamField>

        <ParamField body="contents[].parts[].functionResponse" type="object">
          function calling 的结果。包含 `name` 和 `response`。
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="systemInstruction" type="object">
  系统提示词。结构与 `contents` 项相同：包含 `parts` 数组的对象。系统指令仅支持 `text` 部分。

  ```json theme={null}
  {
    "systemInstruction": {
      "parts": [{"text": "You are a helpful assistant."}]
    }
  }
  ```

  也接受 `system_instruction`（snake\_case 形式）。
</ParamField>

<ParamField body="generationConfig" type="object">
  控制模型生成输出的参数。也接受 `generation_config`。

  <Expandable title="generationConfig 属性">
    <ParamField body="generationConfig.temperature" type="number">
      采样温度。值越高越有创造性，值越低越确定。
    </ParamField>

    <ParamField body="generationConfig.topP" type="number">
      核采样概率质量。也接受 `top_p`。
    </ParamField>

    <ParamField body="generationConfig.topK" type="number">
      Top-k 采样。也接受 `top_k`。
    </ParamField>

    <ParamField body="generationConfig.maxOutputTokens" type="integer">
      最大生成 token 数。也接受 `max_output_tokens`。
    </ParamField>

    <ParamField body="generationConfig.candidateCount" type="integer">
      生成的候选响应数量。默认为 `1`。
    </ParamField>

    <ParamField body="generationConfig.stopSequences" type="string[]">
      模型遇到这些序列时停止生成。也接受 `stop_sequences`。
    </ParamField>

    <ParamField body="generationConfig.responseMimeType" type="string">
      响应的 MIME 类型。设为 `"application/json"` 可请求 JSON 输出。也接受 `response_mime_type`。
    </ParamField>

    <ParamField body="generationConfig.responseSchema" type="object">
      响应必须遵循的 JSON Schema。需要 `responseMimeType` 为 `"application/json"`。也接受 `response_schema`。
    </ParamField>

    <ParamField body="generationConfig.responseModalities" type="string[]">
      请求的输出模态，例如 `["TEXT"]` 或 `["TEXT", "IMAGE"]`。也接受 `response_modalities`。
    </ParamField>

    <ParamField body="generationConfig.thinkingConfig" type="object">
      扩展思考配置。也接受 `thinking_config`。

      <Expandable title="thinkingConfig 属性">
        <ParamField body="generationConfig.thinkingConfig.includeThoughts" type="boolean">
          是否在响应中包含模型的思考内容。也接受 `include_thoughts`。
        </ParamField>

        <ParamField body="generationConfig.thinkingConfig.thinkingBudget" type="integer">
          用于思考的最大 token 数。也接受 `thinking_budget`。
        </ParamField>

        <ParamField body="generationConfig.thinkingConfig.thinkingLevel" type="string">
          推理强度：`"low"`、`"medium"` 或 `"high"`。也接受 `thinking_level`。
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tools" type="object[]">
  模型可使用的工具。支持 `functionDeclarations`、`googleSearch`、`googleSearchRetrieval`、`codeExecution` 和 `urlContext`。
</ParamField>

<ParamField body="toolConfig" type="object">
  控制模型如何选择工具。

  <Expandable title="toolConfig 属性">
    <ParamField body="toolConfig.functionCallingConfig" type="object">
      function calling 配置。

      <Expandable title="functionCallingConfig 属性">
        <ParamField body="toolConfig.functionCallingConfig.mode" type="string">
          function calling 模式：`"AUTO"`、`"ANY"` 或 `"NONE"`。
        </ParamField>

        <ParamField body="toolConfig.functionCallingConfig.allowedFunctionNames" type="string[]">
          当 `mode` 为 `"ANY"` 时，限制只能调用此列表中的函数。
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="safetySettings" type="object[]">
  覆盖默认安全过滤器。每项指定一个 `category` 和 `threshold`。
</ParamField>

## 响应字段

<ResponseField name="candidates" type="object[]">
  生成的响应候选数组。

  <Expandable title="candidate 属性">
    <ResponseField name="candidates[].content" type="object">
      生成的内容。

      <Expandable title="content 属性">
        <ResponseField name="candidates[].content.role" type="string">
          生成内容的角色，始终为 `"model"`。
        </ResponseField>

        <ResponseField name="candidates[].content.parts" type="object[]">
          内容部分数组。每个部分包含 `text` 字段（文本输出）或 `functionCall`（tool calling）。带 `thought: true` 的部分包含模型的内部推理（启用思考时）。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="candidates[].finishReason" type="string">
      模型停止的原因。常见值：`"STOP"`（自然结束）、`"MAX_TOKENS"`（达到 token 限制）、`"SAFETY"`（安全过滤）、`"RECITATION"`。
    </ResponseField>

    <ResponseField name="candidates[].index" type="integer">
      此候选的索引。
    </ResponseField>

    <ResponseField name="candidates[].safetyRatings" type="object[]">
      各危害类别的安全评级。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usageMetadata" type="object">
  请求的 token 用量。

  <Expandable title="usageMetadata 属性">
    <ResponseField name="usageMetadata.promptTokenCount" type="integer">
      输入 `contents` 中的 token 数量。
    </ResponseField>

    <ResponseField name="usageMetadata.candidatesTokenCount" type="integer">
      生成候选中的 token 数量。
    </ResponseField>

    <ResponseField name="usageMetadata.totalTokenCount" type="integer">
      总 token 用量。
    </ResponseField>

    <ResponseField name="usageMetadata.thoughtsTokenCount" type="integer">
      用于思考的 token 数量（启用扩展思考时）。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="promptFeedback" type="object">
  关于提示词的反馈，包括安全评级和拦截原因（如果提示词被拦截）。
</ResponseField>

## 示例

<Tabs>
  <Tab title="非流式">
    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.anyone.ai/v1beta/models/gemini-3.1-pro-preview:generateContent" \
        -H "x-goog-api-key: YOUR_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "contents": [
            {
              "role": "user",
              "parts": [{"text": "Explain the difference between RAM and ROM."}]
            }
          ],
          "generationConfig": {
            "temperature": 0.7,
            "maxOutputTokens": 512
          }
        }'
      ```

      ```python Python (google-genai SDK) theme={null}
      import google.generativeai as genai

      genai.configure(
          api_key="YOUR_TOKEN",
          client_options={"api_endpoint": "https://api.anyone.ai"},
      )

      model = genai.GenerativeModel("gemini-3.1-pro-preview")
      response = model.generate_content("Explain the difference between RAM and ROM.")

      print(response.text)
      ```
    </CodeGroup>

    **响应示例：**

    ```json theme={null}
    {
      "candidates": [
        {
          "content": {
            "role": "model",
            "parts": [
              {
                "text": "RAM (Random Access Memory) is volatile memory used for temporary storage while your computer is running..."
              }
            ]
          },
          "finishReason": "STOP",
          "index": 0,
          "safetyRatings": []
        }
      ],
      "usageMetadata": {
        "promptTokenCount": 11,
        "candidatesTokenCount": 142,
        "totalTokenCount": 153
      }
    }
    ```
  </Tab>

  <Tab title="流式">
    ```bash cURL theme={null}
    curl "https://api.anyone.ai/v1beta/models/gemini-3.1-pro-preview:streamGenerateContent" \
      -H "x-goog-api-key: YOUR_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "contents": [
          {"role": "user", "parts": [{"text": "Count from 1 to 5."}]}
        ]
      }'
    ```

    服务端返回以换行符分隔的 JSON 对象流，每个代表一个部分响应块。每个块的结构与非流式响应相同，包含部分 `candidates[].content.parts[].text`。
  </Tab>

  <Tab title="多轮对话">
    ```bash cURL theme={null}
    curl "https://api.anyone.ai/v1beta/models/gemini-3.1-pro-preview:generateContent" \
      -H "x-goog-api-key: YOUR_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "systemInstruction": {
          "parts": [{"text": "You are a geography expert."}]
        },
        "contents": [
          {"role": "user", "parts": [{"text": "What is the longest river in Africa?"}]},
          {"role": "model", "parts": [{"text": "The Nile is the longest river in Africa."}]},
          {"role": "user", "parts": [{"text": "How long is it in kilometers?"}]}
        ]
      }'
    ```
  </Tab>
</Tabs>

## 思考模型

Anyone 支持 Gemini 思考模型，模型在生成响应前进行额外推理。有三种方式启用思考：

**1. 思考模型后缀** — 在支持的模型名后追加 `-thinking`：

```bash theme={null}
POST /v1beta/models/gemini-3.1-pro-preview-thinking:generateContent
POST /v1beta/models/gemini-3.1-pro-preview-thinking:generateContent
```

**2. 强度后缀** — 追加 `-low`、`-medium` 或 `-high` 精细控制：

```bash theme={null}
POST /v1beta/models/gemini-3.1-pro-preview-high:generateContent
```

**3. `generationConfig` 中的 `thinkingConfig`** — 显式传入配置：

```json theme={null}
{
  "contents": [...],
  "generationConfig": {
    "thinkingConfig": {
      "includeThoughts": true,
      "thinkingBudget": 8192
    }
  }
}
```

启用思考后，响应中带 `"thought": true` 的部分包含模型的推理内容。这些部分默认不展示给终端用户——由你的应用决定是否显示。

<Tip>
  如果只需要文本输出，不想处理思考部分，设置 `includeThoughts: false`，让模型在内部推理但不在响应体中包含这些 token。
</Tip>