文本生成

Gemini 原生格式适合希望直接使用 Gemini contents[].parts[]、systemInstruction、generationConfig 等字段的客户。平台会保留原生请求体并转发到可用的 Gemini 上游，响应保持 candidates、finishReason、usageMetadata 等 Gemini 风格字段。

如果客户已经按 OpenAI messages 结构接入，可以优先看「Gemini / OpenAI 兼容 / 文本生成」。如果客户需要最完整的 Gemini 原生参数、图片、视频或文档输入，建议使用本节原生格式。

接口地址

非流式：

POST https://{your-domain}/v1beta/models/{model}:generateContent

流式：

POST https://{your-domain}/v1beta/models/{model}:streamGenerateContent?alt=sse

示例模型：

gemini-3.5-flash

鉴权

推荐使用 Google 风格 API Key 请求头：

x-goog-api-key: YOUR_API_KEY
Content-Type: application/json

平台也兼容 Bearer 请求头：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

客户文档和示例建议统一使用 x-goog-api-key，这样与 Gemini 官方 REST / SDK 示例更接近；如果客户侧已有 OpenAI 网关鉴权封装，也可以使用 Authorization: Bearer。

请求结构

字段	类型	必填	说明
`contents`	array	是	对话内容数组。每个元素通常包含 `role` 和 `parts`。
`contents[].role`	string	否	常用值为 `user` 或 `model`，多轮对话时可交替传入。
`contents[].parts`	array	是	内容片段数组。文本生成通常只传 `text`。
`contents[].parts[].text`	string	是	用户输入、上下文或指令文本。
`systemInstruction.parts[].text`	string	否	系统指令，用于指定角色、语气、输出格式、约束条件。
`generationConfig.maxOutputTokens`	integer	否	最大输出 token 数。
`generationConfig.temperature`	number	否	随机性，越高越发散。
`generationConfig.topP`	number	否	nucleus sampling 参数。
`generationConfig.responseMimeType`	string	否	需要 JSON 时可传 `application/json`。

非流式文本生成

curl

curl --request POST \
  --url 'https://{your-domain}/v1beta/models/gemini-3.5-flash:generateContent' \
  --header 'x-goog-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "systemInstruction": {
      "parts": [
        {
          "text": "你是一个面向企业客户的中文技术顾问，回答要准确、简洁、可落地。"
        }
      ]
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请用三句话介绍 Gemini 原生文本生成接口，说明它适合什么场景。"
          }
        ]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 512,
      "temperature": 0.4,
      "topP": 0.9
    }
  }'

请求体

{
  "systemInstruction": {
    "parts": [
      {
        "text": "你是一个面向企业客户的中文技术顾问，回答要准确、简洁、可落地。"
      }
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请用三句话介绍 Gemini 原生文本生成接口，说明它适合什么场景。"
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "temperature": 0.4,
    "topP": 0.9
  }
}

响应示例

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Gemini 原生文本生成接口使用 contents 和 parts 组织输入，适合希望保持 Gemini 官方请求结构的客户。它可以用于普通问答、摘要、改写、分类、结构化提取等文本任务。相比 OpenAI 兼容格式，原生格式更便于继续扩展图片、视频、文档和 Gemini 专属生成参数。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 52,
    "candidatesTokenCount": 78,
    "totalTokenCount": 130
  }
}

流式文本生成

流式接口通过 SSE 返回 data: 事件。URL 必须使用 :streamGenerateContent?alt=sse，curl 建议加 -N 关闭本地缓冲。

curl

curl -N --request POST \
  --url 'https://{your-domain}/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse' \
  --header 'x-goog-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请流式输出一段中文说明，介绍企业如何接入 Gemini 原生文本生成。"
          }
        ]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 512
    }
  }'

请求体

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请流式输出一段中文说明，介绍企业如何接入 Gemini 原生文本生成。"
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512
  }
}

响应示例

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"企业接入"}]},"finishReason":null,"index":0}],"usageMetadata":{"promptTokenCount":24,"totalTokenCount":24}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":" Gemini 原生文本生成时，先确认模型名称和 API Key 权限，然后按 generateContent 的 contents/parts 结构提交请求。"}]},"finishReason":null,"index":0}],"usageMetadata":{"promptTokenCount":24,"totalTokenCount":24}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"如果需要实时展示结果，可以切换到 streamGenerateContent 并按 SSE 事件逐段读取。"}]},"finishReason":null,"index":0}],"usageMetadata":{"promptTokenCount":24,"candidatesTokenCount":45,"totalTokenCount":69}}

data: {"candidates":[{"content":{"role":"model","parts":[]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":24,"candidatesTokenCount":45,"totalTokenCount":69}}

多轮对话

多轮对话可以把历史消息继续放在 contents 中。上一轮模型输出使用 role: "model"，下一轮用户追问使用 role: "user"。

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请介绍 Gemini 原生接口。"
        }
      ]
    },
    {
      "role": "model",
      "parts": [
        {
          "text": "Gemini 原生接口使用 contents 和 parts 组织输入，支持文本和多模态内容。"
        }
      ]
    },
    {
      "role": "user",
      "parts": [
        {
          "text": "请补充它和 OpenAI 兼容接口的区别。"
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512
  }
}

JSON 输出

需要模型尽量返回 JSON 时，可以通过系统指令和 responseMimeType 同时约束。

{
  "systemInstruction": {
    "parts": [
      {
        "text": "只返回 JSON，不要返回 Markdown。"
      }
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "把这句话分类：客户希望查看本月账单明细。返回字段 category 和 reason。"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "maxOutputTokens": 256
  }
}

Python 示例

import requests

api_key = "YOUR_API_KEY"
model = "gemini-3.5-flash"
url = f"https://{{your-domain}}/v1beta/models/{model}:generateContent"

payload = {
    "contents": [
        {
            "role": "user",
            "parts": [
                {"text": "请用三句话介绍 Gemini 原生文本生成接口。"},
            ],
        }
    ],
    "generationConfig": {
        "maxOutputTokens": 512,
        "temperature": 0.4,
    },
}

resp = requests.post(
    url,
    headers={
        "x-goog-api-key": api_key,
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
resp.raise_for_status()
print(resp.json())

JavaScript 示例

const apiKey = "YOUR_API_KEY";
const model = "gemini-3.5-flash";

const response = await fetch(
  `https://{your-domain}/v1beta/models/${model}:generateContent`,
  {
    method: "POST",
    headers: {
      "x-goog-api-key": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [
        {
          role: "user",
          parts: [
            { text: "请用三句话介绍 Gemini 原生文本生成接口。" },
          ],
        },
      ],
      generationConfig: {
        maxOutputTokens: 512,
        temperature: 0.4,
      },
    }),
  }
);

if (!response.ok) {
  throw new Error(await response.text());
}

console.log(await response.json());

常见问题

场景	表现	处理方式
请求体里传了 `model`	上游可能忽略或报错	Gemini 原生模型写在 URL 路径中，请求体不需要 `model`。
流式接口没有实时输出	客户端拿到完整响应后才展示	curl 使用 `-N`，服务端和前端按 SSE `data:` 事件逐段处理。
返回 `model_not_allowed`	API Key 没有模型权限	检查 `/v1/models` 或联系平台开通模型。
返回 `model_endpoint_mismatch`	模型没有绑定 Gemini 原生 endpoint	使用支持 `/v1beta/models/{model}:generateContent` 的 Gemini 模型。
JSON 输出不稳定	模型返回 Markdown 或自然语言	增加 `responseMimeType: "application/json"`，并在系统指令中要求只返回 JSON。

开始使用

API 参考

模型与计费

指南

参考

接口地址

鉴权

请求结构

非流式文本生成

curl

请求体

响应示例

流式文本生成

curl

请求体

响应示例

多轮对话

JSON 输出

Python 示例

JavaScript 示例

常见问题

​接口地址

​鉴权

​请求结构

​非流式文本生成

​curl

​请求体

​响应示例

​流式文本生成

​curl

​请求体

​响应示例

​多轮对话

​JSON 输出

​Python 示例

​JavaScript 示例

​常见问题

接口地址

鉴权

请求结构

非流式文本生成

curl

请求体

响应示例

流式文本生成

curl

请求体

响应示例

多轮对话

JSON 输出

Python 示例

JavaScript 示例

常见问题