Generate content

Request parameters

• modelstring必填

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

• contentsarray必填◐ Partially supported

  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.

  Multi-turn text, images and tool round trips work, including URL-safe base64 images. Inline audio/wav, text/plain and fileData URLs return 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可选○ Unsupported

      URI based data.

      Tested HTTPS, gs, Files API and YouTube URLs all return 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可选◐ Partially supported

      Inline media bytes.

      image/png works, including URL-safe base64; audio/wav and text/plain return 400. PDF effects are unobservable.

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

  Verified to take effect.

  ▸ 展开子字段（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可选○ Currently ignored

    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.

    Accepted but currently has no effect. Use responseJsonSchema instead.

  • audioTranscriptionConfigobject可选○ Currently ignored

    Optional. Config for audio transcription (speech recognition).

    Accepted but currently has no effect. Tested text models do not apply this option.

  • candidateCountinteger可选◐ Partially supported

    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)

    Multiple candidates work in non-streaming requests; streaming with 2 returns 400.

  • enableAffectiveDialogboolean可选○ Currently ignored

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

    Accepted but currently has no effect. Tested text models do not apply this option.

  • enableEnhancedCivicAnswersboolean可选○ Unsupported

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

    Passing this to the tested text models returns 400.

  • frequencyPenaltynumber可选◐ Partially supported

    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.

    An occasional effect was observed on gemini-2.5-flash; ignored on gemini-2.5-flash-lite. 2.0 may return 400.

  • imageConfigobject可选○ Unsupported

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

    Passing this to the tested text models returns 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].

    Verified to take effect.

  • maxOutputTokensinteger可选◐ Partially supported

    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.

    Limits output budget including thinking; very small budgets may return only thinking or error, and gemini-3.5-flash may truncate early.

  • mediaResolutionstring可选

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

    LOW/MEDIUM/HIGH change image token usage on gemini-2.5-flash.

    取值 MEDIA_RESOLUTION_HIGHMEDIA_RESOLUTION_LOWMEDIA_RESOLUTION_MEDIUMMEDIA_RESOLUTION_UNSPECIFIED
  • presencePenaltynumber可选○ Currently ignored

    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.

    Accepted but currently has no effect. Outputs did not change on gemini-2.5-flash or gemini-2.5-flash-lite.

  • responseFormatobject可选○ Currently ignored

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

    Accepted but currently has no effect. Tested text models do not apply this option.

  • responseJsonSchemaany可选◐ Partially supported

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

    Works on the 2.5 models; 3.5 may truncate with insufficient budget. Cannot be combined with responseSchema.

  • responseLogprobsboolean可选

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

    Verified to take effect.

  • responseMimeTypestring可选◐ Partially supported

    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 works on the 2.5 models; 3.5 may return non-JSON. text/x.enum works on flash-lite.

  • responseModalitiesarray可选◐ Partially supported

    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.

    Tested text models support TEXT; AUDIO returns 400 and IMAGE errors.

  • responseSchemaobject可选◐ Partially supported

    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.

    JSON constraints work on the 2.5 models; 3.5 may truncate with insufficient budget. Requires the matching responseMimeType.

  • seedinteger可选◐ Partially supported

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

    Reproducible on gemini-2.5-flash-lite; accepted but currently ignored on gemini-2.5-flash.

  • speechConfigobject可选○ Currently ignored

    Optional. The speech generation config.

    Accepted but currently has no effect. Tested text models do not apply this option.

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

    Works on gemini-2.5-flash and gemini-2.5-flash-lite; at most five sequences.

  • temperaturenumber可选◐ Partially supported

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

    An effect was observed on gemini-2.5-flash-lite; sampling effects on gemini-2.5-flash are unobservable.

  • 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可选◐ Partially supported

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

      true/false controls returned thinking when thinking is enabled. Passing it alone to flash-lite with thinking disabled by default returns 400.

    • thinkingBudgetinteger可选

      The number of thoughts tokens that the model should generate.

      Zero disables thinking; positive values control the budget and -1 is automatic. Out-of-range values return 400.

    • thinkingLevelstring可选◐ Partially supported

      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 supports MINIMAL/LOW/MEDIUM/HIGH; using it on the 2.5 models returns 400.

      取值 HIGHLOWMEDIUMMINIMALTHINKING_LEVEL_UNSPECIFIED
  • topKinteger可选○ Currently ignored

    Accepted but not effective; sampling does not use topK.

    Accepted but currently has no effect. gemini-2.5-flash-lite still returns different outputs with topK=1; effects on gemini-2.5-flash are unobservable.

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

    Verified on gemini-2.5-flash and gemini-2.5-flash-lite.

  • translationConfigobject可选○ Currently ignored

    Optional. Config for translation.

    Accepted but currently has no effect. Tested text models do not apply this option.

• 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可选○ Unsupported

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

    Tested requests return 502; currently unavailable.

  • computerUseobject可选○ Unsupported

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

    Tested gemini-2.5-flash requests return 400.

  • fileSearchobject可选○ Unsupported

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

    Tested gemini-2.5-flash requests return 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可选○ Currently ignored

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

      Accepted but currently has no effect.

      取值 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.

      Verified to take effect.

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

      Verified to take effect.

    • responseobject可选○ Currently ignored

      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.

      Accepted but currently has no effect.

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

  • googleSearchRetrievalobject可选○ Unsupported

    Optional. Retrieval tool that is powered by Google search.

    Tested gemini-2.5-flash requests return 400.

  • mcpServersarray可选○ Unsupported

    Optional. MCP Servers to connect to.

    Tested gemini-2.5-flash requests return 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.

      Verified to take effect.

    • modestring可选◐ Partially supported

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

      ANY/AUTO/VALIDATED work; NONE occasionally still called tools on flash-lite, then worked on retest.

      取值 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可选

  Accepted but not effective; safety settings never block or alter responses.

  ▸ 展开子字段（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可选○ Unsupported

  Cached content is not supported on this platform; passing it returns a 400 in Google's error format.

  Passing it returns 400; cached-content references are not supported.

• labelsobject可选

  Accepted but not effective; labels are not stored and do not affect request processing.

• modelstring可选○ Currently ignored

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

  Accepted but currently has no effect. The model in the URL path takes precedence.

• ▸ 更多参数（2）

  • serviceTierstring可选

    Accepted but not effective; every request is served at the platform's current service tier.

    取值 flexprioritystandardunspecified
  • storeboolean可选

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

Returns

200

Forced tool use in toolConfig (functionCallingConfig mode ANY, including allowedFunctionNames) is forwarded unchanged on thinking models too — the same as the native Gemini API, so whether it is accepted is up to the upstream model; if the upstream answers 400, the error keeps the Google format and carries the upstream code and status.

Errors follow the Gemini API format — see error codes