> ## Documentation Index > Fetch the complete documentation index at: https://docs.playapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Gemini generateContent > 通过模型路径创建 Gemini 原生内容。 `POST /v1beta/models/{model}:generateContent` 使用 `x-goog-api-key` 请求头传入网关令牌。模型位于路径；请求体使用 `contents` 和可选 `systemInstruction`。角色为 `user` / `model`，文本在 `parts[]` 中。 检查 `promptFeedback`、候选数量与 `finishReason`，再读取 `candidates[].content.parts`。空候选、安全阻断、工具块和截断响应不能作为完整文本。 [原生 Gemini 指南与完整 TypeScript 示例](/zh/guides/native-gemini)包含路径与认证、可运行代码及失败处理。SSE 使用另一动作 `:streamGenerateContent?alt=sse`，此操作的参数表仅描述非流式 `generateContent`；尚未展开全部工具、多模态与生成配置字段。项目未实现 `/v1beta/...:countTokens`，当前返回 404。 核对版本：`d851a5faa49a00abaafd27bf91b311506fbfbc52`. 源文件记录在此操作的 `x-source-files`。 [原生 SSE 与工具闭环的 Python 示例](/zh/guides/native-gemini-streaming)提供纯文本和工具两种模式，保留原生结果关联与签名。 [Read in English](/en/api-reference/gemini-generate) ## 媒体内容项 原生 `contents[].parts[]` 可以包含 `inlineData: {mimeType, data}` 或 `fileData: {mimeType, fileUri}`，前者使用纯 Base64；内容格式和来源必须受目标上游支持。`videoMetadata`、`mediaResolution` 是条件支持的原生扩展，不是网关统一转码或抽帧服务。 媒体输入不改变响应协议和完成检查。网关没有在已核查范围内提供 Gemini Files 上传/管理或 Interactions 端点；SDK 自动上传会产生额外的未支持请求。先使用 [视频理解的完整非流式示例](/zh/guides/video-understanding)，流式输出仍按本接口 SSE 事件处理。 ## 内置工具与原生结果元数据 使用 `tools[].googleSearch`、`urlContext` 或 `codeExecution` 的空对象启用受支持的原生工具。检查候选的 `groundingMetadata` / `urlContextMetadata`，或内容块中的 `executableCode` / `codeExecutionResult`。只有 `STOP` 不证明执行成功。当前原生处理器转发原始响应 JSON，不应推断转换后的协议或请求回放中的未知字段也有同样行为。[可运行示例与完成规则](/zh/guides/gemini-builtins)。 ## OpenAPI ````yaml openapi/relay.json POST /v1beta/models/{model}:generateContent openapi: 3.0.3 info: title: API — Core inference API version: 0.5.0 description: >- 面向接入的精选规范，不是全部管理或供应商接口。 / Curated integration specification, not the entire management or provider API. license: name: AGPL-3.0-or-later servers: - url: https://gateway.example.com description: >- Example only; replace with your gateway origin and optional path prefix, without /v1. security: - BearerAuth: [] paths: /v1beta/models/{model}:generateContent: post: summary: Gemini 原生生成 / Native Gemini generation description: >- 精选文本接入字段；允许扩展字段不代表所有渠道支持。原生流式和工具扩展见指南。 / Selected text integration fields; accepting extensions does not guarantee channel support. See the guide for native streaming and tool boundaries. operationId: generateGeminiContent parameters: - name: model in: path required: true description: >- 裸模型 ID，不含 models/ 和动作后缀 / Bare model ID without models/ or an action suffix. schema: type: string example: YOUR_MODEL_ID requestBody: required: true content: application/json: schema: type: object required: - contents properties: contents: type: array minItems: 1 items: type: object properties: role: type: string parts: type: array items: type: object properties: text: type: string thought: type: boolean thoughtSignature: type: string functionCall: type: object properties: id: type: string name: type: string args: type: object additionalProperties: true additionalProperties: true functionResponse: type: object properties: id: type: string name: type: string response: type: object additionalProperties: true additionalProperties: true inlineData: type: object required: - mimeType - data properties: mimeType: type: string example: video/mp4 data: type: string description: >- 纯 Base64，不带 Data URL 前缀 / Plain Base64, no Data URL prefix description: >- 原生内联媒体，格式与大小依模型 / Native inline media; model-dependent formats and limits fileData: type: object properties: mimeType: type: string fileUri: type: string description: >- 上游可访问的 URI；不是网关上传服务 / Upstream-accessible URI, not a gateway upload service videoMetadata: type: object additionalProperties: true description: >- 模型依赖的原生扩展；请核对实际上游结构 / Model-dependent native extension; verify the upstream structure mediaResolution: type: object additionalProperties: true description: >- 模型依赖的原生扩展；请核对实际上游结构 / Model-dependent native extension; verify the upstream structure executableCode: type: object properties: language: type: string example: PYTHON code: type: string additionalProperties: true codeExecutionResult: type: object properties: outcome: type: string description: 检查 OUTCOME_OK / Check OUTCOME_OK output: type: string additionalProperties: true additionalProperties: true additionalProperties: true systemInstruction: type: object properties: role: type: string parts: type: array items: type: object properties: text: type: string thought: type: boolean thoughtSignature: type: string functionCall: type: object properties: id: type: string name: type: string args: type: object additionalProperties: true additionalProperties: true functionResponse: type: object properties: id: type: string name: type: string response: type: object additionalProperties: true additionalProperties: true additionalProperties: true additionalProperties: true tools: type: array items: type: object properties: functionDeclarations: type: array items: type: object required: - name properties: name: type: string description: type: string parameters: type: object additionalProperties: true description: >- 工具参数 Schema；示例额外执行本地校验 / Tool parameter schema; examples also validate locally. additionalProperties: true googleSearch: type: object additionalProperties: true description: >- 以空对象启用；依赖原生模型及渠道支持 / Enable with an empty object; native model and channel support required example: {} urlContext: type: object additionalProperties: true description: >- 以空对象启用；依赖原生模型及渠道支持 / Enable with an empty object; native model and channel support required example: {} codeExecution: type: object additionalProperties: true description: >- 以空对象启用；依赖原生模型及渠道支持 / Enable with an empty object; native model and channel support required example: {} additionalProperties: true additionalProperties: true responses: '200': description: 检查原生完成状态及内容 / Check native completion status and content. content: application/json: schema: type: object properties: candidates: type: array items: type: object properties: index: type: integer content: type: object properties: role: type: string parts: type: array items: type: object properties: text: type: string thought: type: boolean thoughtSignature: type: string functionCall: type: object properties: id: type: string name: type: string args: type: object additionalProperties: true additionalProperties: true functionResponse: type: object properties: id: type: string name: type: string response: type: object additionalProperties: true additionalProperties: true executableCode: type: object properties: language: type: string example: PYTHON code: type: string additionalProperties: true codeExecutionResult: type: object properties: outcome: type: string description: 检查 OUTCOME_OK / Check OUTCOME_OK output: type: string additionalProperties: true additionalProperties: true additionalProperties: true finishReason: type: string groundingMetadata: type: object additionalProperties: true properties: groundingChunks: type: array items: type: object additionalProperties: true groundingSupports: type: array items: type: object additionalProperties: true searchEntryPoint: type: object additionalProperties: true description: >- 保留来源与原始 part 的关联；片段偏移为 UTF-8 字节 / Preserve source and original part association; segment offsets are UTF-8 bytes urlContextMetadata: type: object additionalProperties: true properties: urlMetadata: type: array items: type: object properties: retrievedUrl: type: string urlRetrievalStatus: type: string description: >- 原生响应中的读取状态，HTTP 成功不代表读取成功 / Native retrieval status; HTTP success does not establish retrieval success additionalProperties: true promptFeedback: type: object additionalProperties: true usageMetadata: type: object additionalProperties: true additionalProperties: true example: candidates: - index: 0 finishReason: STOP content: role: model parts: - text: Hello. default: description: >- 网关或上游错误，结构可能随协议变化 / Gateway or upstream error; structure may vary by protocol. content: application/json: schema: type: object additionalProperties: true security: - GeminiApiKey: [] - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer description: 模型调用 API Key，不是控制台登录凭据 / Model API key, not console login credentials GeminiApiKey: type: apiKey in: header name: x-goog-api-key description: 网关令牌 / Gateway token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.