流式生成内容

请求参数

• modelstring必填

  path: Required. The name of the `Model` to use for generating the completion. Format: `models/{model}`.

• contentsarray必填◐ 部分支持

  Required. The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries like [chat](https://ai.google.dev/gemini-api/docs/text-generation#chat), this is a repeated field that contains the conversation history and the latest request.

  多轮、文本、图片和工具往返生效，图片支持 URL-safe base64；audio/wav、text/plain 内联媒体及 fileData URL 返回 400。

  ▸ 展开子字段（2）

  • partsarray可选

    Ordered `Parts` that constitute a single message. Parts may have different MIME types.

    ▸ 展开子字段（16）

    • audioTranscriptionobject可选

      Optional. Audio (input or output) transcription. This is only set when this Part contains audio data.

    • codeExecutionResultobject可选

      Result of executing the `ExecutableCode`.

    • executableCodeobject可选

      Code generated by the model that is meant to be executed.

    • fileDataobject可选○ 未支持

      URI based data.

      已测 HTTPS、gs、Files API 和 YouTube URL 均返回 400。

    • functionCallobject可选

      A predicted `FunctionCall` returned from the model that contains a string representing the `FunctionDeclaration.name` with the arguments and their values.

    • functionResponseobject可选

      The result output of a `FunctionCall` that contains a string representing the `FunctionDeclaration.name` and a structured JSON object containing any output from the function is used as context to the model.

    • inlineDataobject可选◐ 部分支持

      Inline media bytes.

      image/png 生效（含 URL-safe base64）；audio/wav、text/plain 返回 400；PDF 效果不可观测。

    • mediaProcessingstring可选

      Optional. How the model processes this part's media for understanding. Only meaningful for video parts (`inline_data` or `file_data` with video mime). Non-video parts ignore this field.

      取值 AGENTICMEDIA_PROCESSING_UNSPECIFIEDSTATIC
    • mediaResolutionobject可选

      Optional. Media resolution for the input media.

    • partMetadataobject可选

      Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams.

    • textstring可选

      Inline text.

    • thoughtboolean可选

      Optional. Indicates if the part is thought from the model.

    • thoughtSignaturestring可选

      Optional. An opaque signature for the thought so it can be reused in subsequent requests.

    • toolCallobject可选

      Server-side tool call. This field is populated when the model predicts a tool invocation that should be executed on the server. The client is expected to echo this message back to the API.

    • toolResponseobject可选

      The output from a server-side `ToolCall` execution. This field is populated by the client with the results of executing the corresponding `ToolCall`.

    • videoMetadataobject可选

      Optional. Video metadata. The metadata should only be specified while the video data is presented in inline_data or file_data.

  • rolestring可选

    Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

• systemInstructionobject可选

  Optional. Developer set [system instruction(s)](https://ai.google.dev/gemini-api/docs/system-instructions). Currently, text only.

  已验证生效。

  ▸ 展开子字段（2）

  • partsarray可选

    Ordered `Parts` that constitute a single message. Parts may have different MIME types.

  • rolestring可选

    Optional. The producer of the content. Must be either 'user' or 'model'. Useful to set for multi-turn conversations, otherwise can be left blank or unset.

• generationConfigobject可选

  Optional. Configuration options for model generation and outputs.

  ▸ 展开子字段（25）

  • _responseJsonSchemaany可选○ 当前不生效

    Optional. Output schema of the generated response. This is an alternative to `response_schema` that accepts [JSON Schema](https://json-schema.org/). If set, `response_schema` must be omitted, but `response_mime_type` is required. While the full JSON Schema may be sent, not all features are supported. Specifically, only the following properties are supported: - `$id` - `$defs` - `$ref` - `$anchor` - `type` - `format` - `title` - `description` - `enum` (for strings and numbers) - `items` - `prefixItems` - `minItems` - `maxItems` - `minimum` - `maximum` - `anyOf` - `oneOf` (interpreted the same as `anyOf`) - `properties` - `additionalProperties` - `required` The non-standard `propertyOrdering` property may also be set. Cyclic references are unrolled to a limited degree and, as such, may only be used within non-required properties. (Nullable properties are not sufficient.) If `$ref` is set on a sub-schema, no other properties, except for than those starting as a `$`, may be set. Deprecated. Use `response_format` instead.

    接受但当前不生效。请使用 responseJsonSchema。

  • audioTranscriptionConfigobject可选○ 当前不生效

    Optional. Config for audio transcription (speech recognition).

    接受但当前不生效。已测文本模型不应用此选项。

  • candidateCountinteger可选◐ 部分支持

    Optional. Number of generated responses to return. If unset, this will default to 1. Please note that this doesn't work for previous generation models (Gemini 1.0 family)

    非流式支持多个候选；流式设置 2 返回 400。

  • enableAffectiveDialogboolean可选○ 当前不生效

    Optional. If enabled, the model will detect emotions and adapt its responses accordingly.

    接受但当前不生效。已测文本模型不应用此选项。

  • enableEnhancedCivicAnswersboolean可选○ 未支持

    Optional. Enables enhanced civic answers. It may not be available for all models.

    已测文本模型传入返回 400。

  • frequencyPenaltynumber可选◐ 部分支持

    Optional. Frequency penalty applied to the next token's logprobs, multiplied by the number of times each token has been seen in the respponse so far. A positive penalty will discourage the use of tokens that have already been used, proportional to the number of times the token has been used: The more a token is used, the more difficult it is for the model to use that token again increasing the vocabulary of responses. Caution: A _negative_ penalty will encourage the model to reuse tokens proportional to the number of times the token has been used. Small negative values will reduce the vocabulary of a response. Larger negative values will cause the model to start repeating a common token until it hits the max_output_tokens limit.

    gemini-2.5-flash 偶发观察到效果；gemini-2.5-flash-lite 接受但当前不生效；2.0 可能返回 400。

  • imageConfigobject可选○ 未支持

    Optional. Config for image generation. An error will be returned if this field is set for models that don't support these config options.

    已测文本模型传入返回 400。

  • logprobsinteger可选

    Optional. Only valid if response_logprobs=True. This sets the number of top logprobs, including the chosen candidate, to return at each decoding step in the Candidate.logprobs_result. The number must be in the range of [0, 20].

    已验证生效。

  • maxOutputTokensinteger可选◐ 部分支持

    Optional. The maximum number of tokens to include in a response candidate. Note: The default value varies by model, see the `Model.output_token_limit` attribute of the `Model` returned from the `getModel` function.

    限制输出预算；思考占用预算，极小预算可能只返回思考或报错，gemini-3.5-flash 可能提前截断。

  • mediaResolutionstring可选

    Optional. If specified, the media resolution specified will be used.

    gemini-2.5-flash 的 LOW/MEDIUM/HIGH 改变图片 token 消耗。

    取值 MEDIA_RESOLUTION_HIGHMEDIA_RESOLUTION_LOWMEDIA_RESOLUTION_MEDIUMMEDIA_RESOLUTION_UNSPECIFIED
  • presencePenaltynumber可选○ 当前不生效

    Optional. Presence penalty applied to the next token's logprobs if the token has already been seen in the response. This penalty is binary on/off and not dependant on the number of times the token is used (after the first). Use frequency_penalty for a penalty that increases with each use. A positive penalty will discourage the use of tokens that have already been used in the response, increasing the vocabulary. A negative penalty will encourage the use of tokens that have already been used in the response, decreasing the vocabulary.

    接受但当前不生效。gemini-2.5-flash 和 gemini-2.5-flash-lite 输出未变化。

  • responseFormatobject可选○ 当前不生效

    Optional. Configuration for the response output format. Allows specifying output configuration per modality (text, audio, image) in a flat structure.

    接受但当前不生效。已测文本模型不应用此选项。

  • responseJsonSchemaany可选◐ 部分支持

    Optional. An internal detail. Use `responseJsonSchema` rather than this field.

    2.5 系列生效；3.5 预算不足可能截断。不可与 responseSchema 同传。

  • responseLogprobsboolean可选

    Optional. If true, export the logprobs results in response.

    已验证生效。

  • responseMimeTypestring可选◐ 部分支持

    Optional. MIME type of the generated candidate text. Supported MIME types are: `text/plain`: (default) Text output. `application/json`: JSON response in the response candidates. `text/x.enum`: ENUM as a string response in the response candidates. Refer to the [docs](https://ai.google.dev/gemini-api/docs/prompting_with_media#plain_text_formats) for a list of all supported text MIME types.

    application/json 在 2.5 系列生效，3.5 可能返回非 JSON；text/x.enum 在 flash-lite 生效。

  • responseModalitiesarray可选◐ 部分支持

    Optional. The requested modalities of the response. Represents the set of modalities that the model can return, and should be expected in the response. This is an exact match to the modalities of the response. A model may have multiple combinations of supported modalities. If the requested modalities do not match any of the supported combinations, an error will be returned. An empty list is equivalent to requesting only text.

    已测文本模型支持 TEXT；AUDIO 返回 400，IMAGE 返回错误。

  • responseSchemaobject可选◐ 部分支持

    Optional. Output schema of the generated candidate text. Schemas must be a subset of the [OpenAPI schema](https://spec.openapis.org/oas/v3.0.3#schema) and can be objects, primitives or arrays. If set, a compatible `response_mime_type` must also be set. Compatible MIME types: `application/json`: Schema for JSON response. Refer to the [JSON text generation guide](https://ai.google.dev/gemini-api/docs/json-mode) for more details. Deprecated. Use `response_format` instead.

    2.5 系列的 JSON 约束生效；3.5 预算不足可能截断；需正确指定 responseMimeType。

  • seedinteger可选◐ 部分支持

    Optional. Seed used in decoding. If not set, the request uses a randomly generated seed.

    gemini-2.5-flash-lite 可复现；gemini-2.5-flash 接受但当前不生效。

  • speechConfigobject可选○ 当前不生效

    Optional. The speech generation config.

    接受但当前不生效。已测文本模型不应用此选项。

  • stopSequencesarray可选

    Optional. The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a `stop_sequence`. The stop sequence will not be included as part of the response.

    gemini-2.5-flash、gemini-2.5-flash-lite 生效；最多 5 项。

  • temperaturenumber可选◐ 部分支持

    Optional. Controls the randomness of the output. Note: The default value varies by model, see the `Model.temperature` attribute of the `Model` returned from the `getModel` function. Values can range from [0.0, 2.0].

    gemini-2.5-flash-lite 观察到效果；gemini-2.5-flash 的采样差异不可观测。

  • thinkingConfigobject可选

    Optional. Config for thinking features. An error will be returned if this field is set for models that don't support thinking.

    ▸ 展开子字段（3）

    • includeThoughtsboolean可选◐ 部分支持

      Indicates whether to include thoughts in the response. If true, thoughts are returned only when available.

      思考开启时 true/false 控制是否返回思考；flash-lite 默认未开启思考时单传此字段返回 400。

    • thinkingBudgetinteger可选

      The number of thoughts tokens that the model should generate.

      0 关闭思考；正数控制思考预算，-1 为自动。越界值返回 400。

    • thinkingLevelstring可选◐ 部分支持

      Optional. Controls the maximum depth of the model's internal reasoning process before it produces a response. The default value is model-dependent. Refer to the [Thinking levels guide](https://ai.google.dev/gemini-api/docs/thinking#thinking-levels) for more details. Recommended for Gemini 3 or later models. Use with earlier models results in an error.

      gemini-3.5-flash 支持 MINIMAL/LOW/MEDIUM/HIGH；用于 2.5 系列返回 400。

      取值 HIGHLOWMEDIUMMINIMALTHINKING_LEVEL_UNSPECIFIED
  • topKinteger可选○ 当前不生效

    接受该参数但不生效：采样不使用 topK。

    接受但当前不生效。gemini-2.5-flash-lite 在 topK=1 时仍返回不同输出；gemini-2.5-flash 不可观测。

  • topPnumber可选

    Optional. The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and Top-p (nucleus) sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability. Note: The default value varies by `Model` and is specified by the`Model.top_p` attribute returned from the `getModel` function. An empty `top_k` attribute indicates that the model doesn't apply top-k sampling and doesn't allow setting `top_k` on requests.

    gemini-2.5-flash 和 gemini-2.5-flash-lite 已验证生效。

  • translationConfigobject可选○ 当前不生效

    Optional. Config for translation.

    接受但当前不生效。已测文本模型不应用此选项。

• toolsarray可选

  Optional. A list of `Tools` the `Model` may use to generate the next response. A `Tool` is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the `Model`. Supported `Tool`s are `Function` and `code_execution`. Refer to the [Function calling](https://ai.google.dev/gemini-api/docs/function-calling) and the [Code execution](https://ai.google.dev/gemini-api/docs/code-execution) guides to learn more.

  ▸ 展开子字段（9）

  • codeExecutionobject可选○ 未支持

    Optional. Enables the model to execute code as part of generation.

    已测请求返回 502，当前不可用。

  • computerUseobject可选○ 未支持

    Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations.

    已测 gemini-2.5-flash 返回 400。

  • fileSearchobject可选○ 未支持

    Optional. FileSearch tool type. Tool to retrieve knowledge from Semantic Retrieval corpora.

    已测 gemini-2.5-flash 返回 400。

  • functionDeclarationsarray可选

    Optional. A list of `FunctionDeclarations` available to the model that can be used for function calling. The model or system does not execute the function. Instead the defined function may be returned as a FunctionCall with arguments to the client side for execution. The model may decide to call a subset of these functions by populating FunctionCall in the response. The next conversation turn may contain a FunctionResponse with the Content.role "function" generation context for the next model turn.

    ▸ 展开子字段（7）

    • behaviorstring可选○ 当前不生效

      Optional. Specifies the function Behavior. Currently only supported by the BidiGenerateContent method.

      接受但当前不生效。

      取值 BLOCKINGNON_BLOCKINGUNSPECIFIED
    • descriptionstring可选

      Required. A brief description of the function.

    • namestring可选

      Required. The name of the function. Must be a-z, A-Z, 0-9, or contain underscores, colons, dots, and dashes, with a maximum length of 128.

    • parametersobject可选

      Optional. Describes the parameters to this function. Reflects the Open API 3.03 Parameter Object string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter.

      已验证生效。

    • parametersJsonSchemaany可选

      Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: ``` { "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] } ``` This field is mutually exclusive with `parameters`.

      已验证生效。

    • responseobject可选○ 当前不生效

      Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function.

      接受但当前不生效。

    • responseJsonSchemaany可选

      Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`.

  • googleMapsobject可选

    Optional. Tool that allows grounding the model's response with geospatial context related to the user's query.

  • googleSearchobject可选

    Optional. GoogleSearch tool type. Tool to support Google Search in Model. Powered by Google.

    gemini-2.5-flash 返回 groundingMetadata。

  • googleSearchRetrievalobject可选○ 未支持

    Optional. Retrieval tool that is powered by Google search.

    已测 gemini-2.5-flash 返回 400。

  • mcpServersarray可选○ 未支持

    Optional. MCP Servers to connect to.

    已测 gemini-2.5-flash 返回 400。

  • urlContextobject可选

    Optional. Tool to support URL context retrieval.

• toolConfigobject可选

  Optional. Tool configuration for any `Tool` specified in the request. Refer to the [Function calling guide](https://ai.google.dev/gemini-api/docs/function-calling#function_calling_mode) for a usage example.

  ▸ 展开子字段（3）

  • functionCallingConfigobject可选

    Optional. Function calling config.

    ▸ 展开子字段（2）

    • allowedFunctionNamesarray可选

      Optional. A set of function names that, when provided, limits the functions the model will call. This should only be set when the Mode is ANY or VALIDATED. Function names should match [FunctionDeclaration.name]. When set, model will predict a function call from only allowed function names.

      已验证生效。

    • modestring可选◐ 部分支持

      Optional. Specifies the mode in which function calling should execute. If unspecified, the default value will be set to AUTO.

      ANY/AUTO/VALIDATED 生效；NONE 在 flash-lite 偶发仍调用工具，复测生效。

      取值 ANYAUTOMODE_UNSPECIFIEDNONEVALIDATED
  • includeServerSideToolInvocationsboolean可选

    Optional. If true, the API response will include the server-side tool calls and responses within the `Content` message. This allows clients to observe the server's tool interactions.

  • retrievalConfigobject可选

    Optional. Retrieval config.

• safetySettingsarray可选

  接受该参数但不生效：安全设置不会拦截或改变任何回复。

  ▸ 展开子字段（2）

  • categorystring可选

    Required. The category for this setting.

    取值 HARM_CATEGORY_CIVIC_INTEGRITYHARM_CATEGORY_DANGEROUSHARM_CATEGORY_DANGEROUS_CONTENTHARM_CATEGORY_DEROGATORYHARM_CATEGORY_HARASSMENTHARM_CATEGORY_HATE_SPEECHHARM_CATEGORY_JAILBREAKHARM_CATEGORY_MEDICALHARM_CATEGORY_SEXUALHARM_CATEGORY_SEXUALLY_EXPLICITHARM_CATEGORY_TOXICITYHARM_CATEGORY_UNSPECIFIEDHARM_CATEGORY_VIOLENCE
  • thresholdstring可选

    Required. Controls the probability threshold at which harm is blocked.

    取值 BLOCK_LOW_AND_ABOVEBLOCK_MEDIUM_AND_ABOVEBLOCK_NONEBLOCK_ONLY_HIGHHARM_BLOCK_THRESHOLD_UNSPECIFIEDOFF
• cachedContentstring可选○ 未支持

  平台不支持上下文缓存：传入会返回 400（Google 错误格式）。

  传入返回 400；当前不支持引用上下文缓存。

• labelsobject可选

  接受该参数但不生效：标签不会被存储，也不参与请求处理。

• modelstring可选○ 当前不生效

  Required. The name of the `Model` to use for generating the completion. Format: `models/{model}`.

  接受但当前不生效。以 URL 路径里的模型名为准。

• ▸ 更多参数（2）

  • serviceTierstring可选

    接受该参数但不生效：所有请求都按平台当前的服务档位处理。

    取值 flexprioritystandardunspecified
  • storeboolean可选

    Optional. Configures the logging behavior for a given request. If set, it takes precedence over the project-level logging config.

返回

200

错误按 Gemini API 格式返回，参见 错误码