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

# Gemini Native

> Gemini 原生格式 API 调用 generateContent 和 streamGenerateContent。请求使用 contents 和 parts，可包含文本和内联图像数据。

* 使用 Google 原生 API 格式调用 Gemini 模型
* 支持同步和流式两种生成方法
* 参数精简，便于快速上手

## 使用示例

### 生成内容

接口：

```text theme={null} theme={"dark"}
POST /v1beta/models/gemini-3-flash-preview:generateContent
```

请求体：

```json theme={null} theme={"dark"}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Summarize the goals of the new night mode in one sentence."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 256,
    "temperature": 0.7
  }
}
```

### 流式生成内容

接口：

```text theme={null} theme={"dark"}
POST /v1beta/models/gemini-3-flash-preview:streamGenerateContent
```

请求体：

```json theme={null} theme={"dark"}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Generate 5 short feature names for an AI writing assistant."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 256
  }
}
```

### 多模态输入

```json theme={null} theme={"dark"}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Describe the image and write concise alt text."
        },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "BASE64_IMAGE_DATA"
          }
        }
      ]
    }
  ]
}
```

## 注意事项

* 使用 `generateContent` 获取完整 JSON 响应。
* 使用 `streamGenerateContent` 进行流式生成。
* 尽可能把文本指令放在多模态 part 之前。

## 响应

`generateContent` 直接返回 Gemini `GenerateContentResponse` 对象，不带 `code` / `data` 包装。文本位于 `candidates[].content.parts[].text`，token 计数位于 `usageMetadata`。思考模型可能会添加带 `thought: true` 或 `thoughtSignature` 的 part；跳过没有 `text` 的 part 即可。

## 流式输出

`streamGenerateContent` 返回 `text/event-stream`。每个事件是一行包含部分 `GenerateContentResponse` 的 `data:`，流以 `data: [DONE]` 结束。接受 `alt=sse` 查询参数，但不是必需的。

```text theme={"dark"}
data: {"candidates":[{"content":{"parts":[{"thought":true}],"role":"model"}}],"usageMetadata":{"promptTokenCount":260,...}}
data: {"candidates":[{"content":{"parts":[{"text":"OK."}],"role":"model"}}],"usageMetadata":{"candidatesTokenCount":2,...}}
data: {"candidates":[{"content":{"parts":[{"thoughtSignature":"..."}],"role":"model"},"finishReason":"STOP"}],"usageMetadata":{...}}
data: [DONE]
```

* 按顺序拼接各个 `text` part。最后一个事件携带 `finishReason`。

## 错误

* `401`：缺少 API Key 或 API Key 无效。
* `400`：请求无效，或模型不是 Gemini 模型。响应体使用 Google 错误结构：`{"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}`。
* `404`：未知的 model id。

响应体示例见[错误码](https://docs.poyo.ai/zh/api-manual/error-codes.md#llm-接口错误)，哪些模型支持此格式见 [LLM 模型](https://docs.poyo.ai/zh/api-manual/chat-series/overview.md)。


## OpenAPI

````yaml zh/api-manual/chat-series/gemini-native-format.json POST /v1beta/models/{model}:{method}
openapi: 3.0.0
info:
  title: Gemini 原生格式
  description: 面向 Google Gemini 模型的原生 Gemini generateContent 格式。
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
    description: 生产环境
security:
  - BearerAuth: []
paths:
  /v1beta/models/{model}:{method}:
    post:
      tags:
        - Text Series
      summary: Gemini 原生格式
      description: 使用原生 Gemini 请求/响应格式。
      operationId: generateGeminiContent
      parameters:
        - name: model
          in: path
          required: true
          schema:
            type: string
            example: gemini-3-flash-preview
          description: Gemini 模型名称。示例：`gemini-3-flash-preview`。
        - name: method
          in: path
          required: true
          schema:
            type: string
            enum:
              - generateContent
              - streamGenerateContent
            example: generateContent
          description: 请求方法。`generateContent` 返回完整 JSON 响应，`streamGenerateContent` 用于流式生成。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeminiGenerateContentRequest'
            examples:
              basic:
                summary: 基础请求
                value:
                  contents:
                    - role: user
                      parts:
                        - text: >-
                            Summarize the 'new night mode' requirements in 3
                            points and provide next steps.
      responses:
        '200':
          description: 内容已生成
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeminiGenerateContentResult'
              examples:
                success:
                  summary: 成功响应
                  value:
                    candidates:
                      - content:
                          role: model
                          parts:
                            - text: Hello! I'm pleased to introduce myself.
                        finishReason: STOP
                        index: 0
                    promptFeedback:
                      safetyRatings:
                        - category: HARM_CATEGORY_HATE_SPEECH
                          probability: NEGLIGIBLE
                        - category: HARM_CATEGORY_DANGEROUS_CONTENT
                          probability: NEGLIGIBLE
                        - category: HARM_CATEGORY_HARASSMENT
                          probability: NEGLIGIBLE
                        - category: HARM_CATEGORY_SEXUALLY_EXPLICIT
                          probability: NEGLIGIBLE
                    usageMetadata:
                      promptTokenCount: 15
                      candidatesTokenCount: 29
                      totalTokenCount: 44
                      thoughtsTokenCount: 0
                      promptTokensDetails:
                        - modality: TEXT
                          tokenCount: 15
        '400':
          description: 请求无效，或模型不支持 Gemini Native
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeminiError'
        '401':
          description: API Key 缺失或无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoyoAuthError'
        '404':
          description: 未知的 model id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpstreamFormatError'
              example:
                error:
                  message: 'Model not found: no-such-model'
                  type: invalid_request_error
                  code: model_not_found
components:
  schemas:
    GeminiGenerateContentRequest:
      type: object
      required:
        - contents
      properties:
        contents:
          type: array
          description: >-
            包含角色和 parts 的对话内容。每个 content 对象可包含 `role`（`user` 或
            `model`）以及由文本或内联数据组成的 `parts` 数组。
          items:
            $ref: '#/components/schemas/GeminiContent'
        generationConfig:
          $ref: '#/components/schemas/GeminiGenerationConfig'
          description: 生成配置，包括 temperature、topP、topK、maxOutputTokens 和 stopSequences。
        safetySettings:
          type: array
          description: 安全设置。
          items:
            $ref: '#/components/schemas/GeminiSafetySetting'
    GeminiGenerateContentResult:
      type: object
      properties:
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/GeminiCandidate'
        promptFeedback:
          $ref: '#/components/schemas/GeminiPromptFeedback'
    GeminiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              example: 400
            message:
              type: string
              example: >-
                URI '/v1beta/models/deepseek-v4-flash:generateContent' is not
                supported by this model. Supported URIs:
                ['/v1/chat/completions']
            status:
              type: string
              example: INVALID_ARGUMENT
    PoyoAuthError:
      type: object
      properties:
        code:
          type: integer
          example: 401
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
        error:
          type: object
          properties:
            message:
              type: string
              example: Invalid API key
            type:
              type: string
              example: authentication_error
    UpstreamFormatError:
      type: object
      description: 模型或请求在此 API 格式下被拒绝时返回的错误。
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 'Model not found: no-such-model'
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              example: model_not_found
    GeminiContent:
      type: object
      required:
        - role
        - parts
      properties:
        role:
          type: string
          enum:
            - user
            - model
          description: 角色类型。`user` 用于用户输入，`model` 用于模型输出。
          example: user
        parts:
          type: array
          description: parts 列表。每个 part 可包含文本或内联数据。
          items:
            $ref: '#/components/schemas/GeminiPart'
    GeminiGenerationConfig:
      type: object
      description: 生成配置。
      properties:
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: 控制输出的随机性。
          example: 0.7
        topP:
          type: number
          minimum: 0
          maximum: 1
          description: 核采样参数。
          example: 0.9
        topK:
          type: integer
          minimum: 1
          description: Top-k 采样参数。
          example: 40
        maxOutputTokens:
          type: integer
          minimum: 1
          description: 最大输出 token 数。
          example: 512
        stopSequences:
          type: array
          description: 停止序列。
          items:
            type: string
    GeminiSafetySetting:
      type: object
      description: 安全设置项。
      properties:
        category:
          type: string
          description: 安全类别。
          example: HARM_CATEGORY_DANGEROUS_CONTENT
        threshold:
          type: string
          description: 拦截阈值。
          example: BLOCK_MEDIUM_AND_ABOVE
    GeminiCandidate:
      type: object
      properties:
        content:
          $ref: '#/components/schemas/GeminiContent'
        finishReason:
          type: string
          example: STOP
        index:
          type: integer
          example: 0
        safetyRatings:
          type: array
          items:
            $ref: '#/components/schemas/GeminiSafetyRating'
    GeminiPromptFeedback:
      type: object
      properties:
        safetyRatings:
          type: array
          items:
            $ref: '#/components/schemas/GeminiSafetyRating'
    GeminiPart:
      type: object
      description: part 可包含文本或内联数据。
      oneOf:
        - type: object
          required:
            - text
          properties:
            text:
              type: string
              example: Hello!
        - type: object
          required:
            - inlineData
          properties:
            inlineData:
              $ref: '#/components/schemas/GeminiInlineData'
    GeminiSafetyRating:
      type: object
      properties:
        category:
          type: string
          example: HARM_CATEGORY_DANGEROUS_CONTENT
        probability:
          type: string
          example: NEGLIGIBLE
    GeminiInlineData:
      type: object
      required:
        - mimeType
        - data
      properties:
        mimeType:
          type: string
          example: image/png
        data:
          type: string
          description: Base64 编码的数据。
          example: BASE64_ENCODED_IMAGE
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证。


        创建 API Key：登录 PoYo，进入 **仪表盘 → API
        密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建
        Key。


        在请求头中添加：


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.