请求参数

• 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

toolConfig 的强制工具（functionCallingConfig mode ANY，含 allowedFunctionNames） 在思考模型上同样忠实转发给上游——与 Gemini 原生 API 一致，是否接受由上游模型 决定：如果上游返回 400，错误保持 Google 格式并携带上游的代码与状态。

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

请求参数

• 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 格式返回，参见 错误码

请求参数

• modelstring必填

  path: Required. The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

• contentsarray可选◐ 部分支持

  Optional. The input given to the model as a prompt. This field is ignored when `generate_content_request` is set.

  原生透传；本地估算。与 generateContentRequest 同传返回 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.

    • 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.

      原生透传；本地读取 PNG/JPEG/GIF 头估算图片 token，不把 base64 当文本；其他媒体使用近似额度。

    • 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.

• generateContentRequestobject可选◐ 部分支持

  Optional. The overall input given to the `Model`. This includes the prompt as well as other model steering information like [system instructions](https://ai.google.dev/gemini-api/docs/system-instructions), and/or function declarations for [function calling](https://ai.google.dev/gemini-api/docs/function-calling). `Model`s/`Content`s and `generate_content_request`s are mutually exclusive. You can either send `Model` + `Content`s or a `generate_content_request`, but never both.

  原生路径保留 systemInstruction 和 tools 并映射模型；本地计入估算。

  ▸ 展开子字段（11）

  • cachedContentstring可选○ 未支持

    Optional. The name of the content [cached](https://ai.google.dev/gemini-api/docs/caching) to use as context to serve the prediction. Format: `cachedContents/{cachedContent}`

  • 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.

  • generationConfigobject可选

    Optional. Configuration options for model generation and outputs.

  • labelsobject可选

    Optional. Labels with user-defined metadata for the request. Optional. Labels must follow standard unified Cloud label requirements: - Label keys must start with a letter. - Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. - International characters are allowed. Usage: - Safety identifiers from aggregators: Use the key `safety_identifier` (e.g. `{"safety_identifier": "user_session_123"}`)

  • modelstring可选

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

  • safetySettingsarray可选

    Optional. A list of unique `SafetySetting` instances for blocking unsafe content. This will be enforced on the `GenerateContentRequest.contents` and `GenerateContentResponse.candidates`. There should not be more than one setting for each `SafetyCategory` type. The API will block any contents and responses that fail to meet the thresholds set by these settings. This list overrides the default settings for each `SafetyCategory` specified in the safety_settings. If there is no `SafetySetting` for a given `SafetyCategory` provided in the list, the API will use the default safety setting for that category. Harm categories HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_CIVIC_INTEGRITY, HARM_CATEGORY_JAILBREAK are supported. Refer to the [guide](https://ai.google.dev/gemini-api/docs/safety-settings) for detailed information on available safety settings. Also refer to the [Safety guidance](https://ai.google.dev/gemini-api/docs/safety-guidance) to learn how to incorporate safety considerations in your AI applications.

  • serviceTierstring可选

    Optional. The service tier of the request.

    取值 flexprioritystandardunspecified
  • storeboolean可选

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

  • systemInstructionobject可选

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

  • 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.

  • 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.

返回

200

按模型族校准的估算值（包括中文和工具定义），响应头为 x-praxis-token-count: estimated；不能用作精确用量或计费依据。

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

请求参数

• modelstring必填

  path: Required. The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

• contentobject必填◐ 部分支持

  Required. The content to embed. Only the `parts.text` fields will be counted.

  仅文本部件生效；图片（含多模态嵌入模型）返回 400。

  ▸ 展开子字段（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.

• embedContentConfigobject可选◐ 部分支持

  Optional. Configuration for the EmbedContent request.

  仅 outputDimensionality 可用（受模型限制）；autoTruncate、documentOcr、audioTrackExtraction 等其余配置返回 400。

  ▸ 展开子字段（6）

  • audioTrackExtractionboolean可选○ 未支持

    Optional. Whether to extract audio from video content.

    传入返回 400；此嵌入配置当前不支持。

  • autoTruncateboolean可选○ 未支持

    Optional. Whether to silently truncate the input content if it's longer than the maximum sequence length.

    传入返回 400；此嵌入配置当前不支持。

  • documentOcrboolean可选○ 未支持

    Optional. Whether to enable OCR for document content.

    传入返回 400；此嵌入配置当前不支持。

  • outputDimensionalityinteger可选◐ 部分支持

    Optional. Reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.

    text-embedding-3-small、qwen3-vl-embedding 支持已测维度；doubao-embedding-vision 需至少 1024；bge-m3、qwen3-embedding-0.6b 报错。

  • taskTypestring可选○ 未支持

    Optional. The task type of the embedding.

    传入返回 400；此嵌入配置当前不支持。

    取值 CLASSIFICATIONCLUSTERINGCODE_RETRIEVAL_QUERYFACT_VERIFICATIONQUESTION_ANSWERINGRETRIEVAL_DOCUMENTRETRIEVAL_QUERYSEMANTIC_SIMILARITYTASK_TYPE_UNSPECIFIED
  • titlestring可选○ 未支持

    Optional. The title for the text.

    传入返回 400；此嵌入配置当前不支持。

• modelstring可选

  Required. The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

  必须与 URL 路径中的模型一致，否则返回 400。

• outputDimensionalityinteger可选◐ 部分支持

  Optional. Deprecated: Please use EmbedContentConfig.output_dimensionality instead. Optional reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end. Supported by newer models since 2024 only. You cannot set this value if using the earlier model (`models/embedding-001`).

  text-embedding-3-small、qwen3-vl-embedding 支持已测维度；doubao-embedding-vision 需至少 1024；bge-m3、qwen3-embedding-0.6b 报错。

• taskTypestring可选○ 未支持

  Optional. Deprecated: Please use EmbedContentConfig.task_type instead. Optional task type for which the embeddings will be used. Not supported on earlier models (`models/embedding-001`).

  传入返回 400。

  取值 CLASSIFICATIONCLUSTERINGCODE_RETRIEVAL_QUERYFACT_VERIFICATIONQUESTION_ANSWERINGRETRIEVAL_DOCUMENTRETRIEVAL_QUERYSEMANTIC_SIMILARITYTASK_TYPE_UNSPECIFIED
• titlestring可选○ 未支持

  Optional. Deprecated: Please use EmbedContentConfig.title instead. An optional title for the text. Only applicable when TaskType is `RETRIEVAL_DOCUMENT`. Note: Specifying a `title` for `RETRIEVAL_DOCUMENT` provides better quality embeddings for retrieval.

  传入返回 400。

返回

200

只接受文本部件；图像等多模态部件会被拒绝。taskType、title 以及 autoTruncate / documentOcr / audioTrackExtraction 等检索配置在平台上没有等价语义， 请求携带时会收到 400（INVALID_ARGUMENT），不会静默忽略——因为不同 taskType 生成的向量行为不同，静默丢弃会悄悄改变检索质量。outputDimensionality 映射为 返回向量的维度。

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

请求参数

• modelstring必填

  path: Required. The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

• requestsarray必填

  Required. Embed requests for the batch. The model in each of these requests must match the model specified `BatchEmbedContentsRequest.model`.

  支持 1–100 项，返回顺序与输入一致；维度必须一致。

  ▸ 展开子字段（6）

  • contentobject可选◐ 部分支持

    Required. The content to embed. Only the `parts.text` fields will be counted.

    仅文本部件生效；图片（含多模态嵌入模型）返回 400。

  • embedContentConfigobject可选◐ 部分支持

    Optional. Configuration for the EmbedContent request.

    仅 outputDimensionality 可用（受模型限制）；autoTruncate、documentOcr、audioTrackExtraction 等其余配置返回 400。

    ▸ 展开子字段（6）

    • audioTrackExtractionboolean可选○ 未支持

      Optional. Whether to extract audio from video content.

      传入返回 400；此嵌入配置当前不支持。

    • autoTruncateboolean可选○ 未支持

      Optional. Whether to silently truncate the input content if it's longer than the maximum sequence length.

      传入返回 400；此嵌入配置当前不支持。

    • documentOcrboolean可选○ 未支持

      Optional. Whether to enable OCR for document content.

      传入返回 400；此嵌入配置当前不支持。

    • outputDimensionalityinteger可选◐ 部分支持

      Optional. Reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end.

      text-embedding-3-small、qwen3-vl-embedding 支持已测维度；doubao-embedding-vision 需至少 1024；bge-m3、qwen3-embedding-0.6b 报错。

    • taskTypestring可选○ 未支持

      Optional. The task type of the embedding.

      传入返回 400；此嵌入配置当前不支持。

      取值 CLASSIFICATIONCLUSTERINGCODE_RETRIEVAL_QUERYFACT_VERIFICATIONQUESTION_ANSWERINGRETRIEVAL_DOCUMENTRETRIEVAL_QUERYSEMANTIC_SIMILARITYTASK_TYPE_UNSPECIFIED
    • titlestring可选○ 未支持

      Optional. The title for the text.

      传入返回 400；此嵌入配置当前不支持。

  • modelstring可选

    Required. The model's resource name. This serves as an ID for the Model to use. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

    必须与 URL 路径中的模型一致，否则返回 400。

  • outputDimensionalityinteger可选◐ 部分支持

    Optional. Deprecated: Please use EmbedContentConfig.output_dimensionality instead. Optional reduced dimension for the output embedding. If set, excessive values in the output embedding are truncated from the end. Supported by newer models since 2024 only. You cannot set this value if using the earlier model (`models/embedding-001`).

    text-embedding-3-small、qwen3-vl-embedding 支持已测维度；doubao-embedding-vision 需至少 1024；bge-m3、qwen3-embedding-0.6b 报错。

  • taskTypestring可选○ 未支持

    Optional. Deprecated: Please use EmbedContentConfig.task_type instead. Optional task type for which the embeddings will be used. Not supported on earlier models (`models/embedding-001`).

    传入返回 400。

    取值 CLASSIFICATIONCLUSTERINGCODE_RETRIEVAL_QUERYFACT_VERIFICATIONQUESTION_ANSWERINGRETRIEVAL_DOCUMENTRETRIEVAL_QUERYSEMANTIC_SIMILARITYTASK_TYPE_UNSPECIFIED
  • titlestring可选○ 未支持

    Optional. Deprecated: Please use EmbedContentConfig.title instead. An optional title for the text. Only applicable when TaskType is `RETRIEVAL_DOCUMENT`. Note: Specifying a `title` for `RETRIEVAL_DOCUMENT` provides better quality embeddings for retrieval.

    传入返回 400。

返回

200

requests 中每一项的约束与 embedContent 相同（文本部件、同上拒绝规则）；批量内 所有条目的 outputDimensionality 必须一致。当前官方 JS 与 Python SDK 的 embedContent 调用实际走的就是这个批量端点。

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

请求参数

• pageSizeinteger可选

  query: The maximum number of `Models` to return (per page). If unspecified, 50 models will be returned per page. This method returns at most 1000 models per page, even if you pass a larger page_size.

  支持分页；0、负数和非数字返回 400，超过上限会截断。

• pageTokenstring可选

  query: A page token, received from a previous `ListModels` call. Provide the `page_token` returned by one request as an argument to the next request to retrieve the next page. When paginating, all other parameters provided to `ListModels` must match the call that provided the page token.

  已验证生效。

返回

200

向量嵌入模型会以 embedContent 作为其唯一受支持的方法列出。当模型目录 暂时不可用时，generateContent 的行为保持不变：显式要求图像输出 （responseModalities 含 IMAGE）的请求仍走图像通道；未显式声明的旧式图像请求 在该窗口内会按文本对话处理——降级期间每个响应都带 X-Praxis-Route-Degraded: model-catalog-unavailable 头以示区别。

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

请求参数

• namestring必填

  path: Required. The resource name of the model. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

返回

200

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