Web Search

Authorization

Auth Type: Bearer Auth (In: header)
Format: Authorization: Bearer <YOUR_API_KEY>
Description: Use Bearer <YOUR_API_KEY>. Format: Authorization: Bearer sk-xxxxxx.
API Key: where API Key is your AGCloud API KEY

Google Gemini API provides two actions for content generation, distinguished by whether they return responses incrementally (streaming) or all at once (non-streaming).

Request Body

Core Parameters

Field	Type	Required	Default	Description
`contents`	array	✅	-	Content of the current conversation with the model. For single-turn queries, this contains one instance. For multi-turn queries (e.g., chat), this contains the conversation history and the latest request.
`>contents.role`	string	✅	-	The role of the message sender. Can be `user` `model`.
`>contents.parts`	array	✅	-	The content parts of the message, which can contain different types of content (text, inlineData, etc.).
`>>contents.parts.text`	string	✅	-	Text content of the part. For multimodal input details

Advanced Parameters

Field	Type	Required	Description
`tools`	`array<object>`	-	List of tools the model may use to generate the next response. Supported tools include Function and codeExecution.
`toolConfig`	`object`	-	Configuration for any tools specified in the request.
`generationConfig`	`object`	-	Configuration options for content generation.
`safetySettings`	`array<object>`	-	List of unique SafetySetting instances for filtering unsafe content. Each SafetyCategory should have at most one setting

Web Search Grounding allows Gemini models to connect with real-time web content, providing more accurate answers with verifiable sources.

{
  "tools": [
    {
      "google_search": {}
    }
  ]
}

{
  "tools": [
    {
      "google_search": {
        "timeRangeFilter": {
          "startTime": "2026-01-01T00:00:00Z",
          "endTime": "2026-01-01T12:00:00Z"
        }
      }
    }
  ]
}

Tools Structure

Field	Type	Required	Range	Description
`googleSearch`	`object`	-	-	Array of tools to use for the request.
`>googleSearch.timeRangeFilter`	`object`	-	-	Optional time range filter for the search.
`>>googleSearch.timeRangeFilter.startTime`	`string`	-	`2024-01-01T00:00:00Z` or timestamp	Optional start time for the search in ISO 8601 format or timestamp.
`>>googleSearch.timeRangeFilter.endTime`	`string`	-	`2024-01-01T00:00:00Z` or timestamp	Optional end time for the search in ISO 8601 format or timestamp. Note: For Gemini 3 models, the time span cannot exceed 24 hours.

Tool Config Structure

Field	Type	Required	Range	Description
`functionCallingConfig`	`object`	-	-	Control tool/function call behavior
`>functionCallingConfig.mode`	`enum`	-	`MODE_UNSPECIFIED` `AUTO` `ANY` `NONE`	Control model whether to call tools.
`>functionCallingConfig.allowedFunctionNames`	`array<string>`	-	`google_search`	Restricting the functions that can be called. Must be `google_search`

Generation Config Structure

Field	Type	Range	Description
`temperature`	`number`	`0.0 - 1.0`	Controls the randomness of the output.
`topP`	`number`	`0.0 - 1.0`	Nucleus sampling probability threshold.
`topK`	`integer`	-	Top-k sampling parameter.
`maxOutputTokens`	`integer`	-	Maximum number of tokens to generate.
`thinkingConfig`	`object`	-	Indicates whether to include thoughts in the response. If true, thoughts are only returned when thinking is enabled.
`>thinkingConfig.includeThoughts`	`boolean`	-	Sequences at which to stop generation.
`>thinkingConfig.thinkingBudget`	`integer`	`0` - `24576`	For Gemini 2.x models. Specifies the maximum number of tokens for generated thoughts.
`>thinkingConfig.thinkingLevel`	`enum`	`low` `medium` `high` `minimal`	Recommended for Gemini 3 or newer models. Using it with older models may cause errors. Default `high`
`imageConfig`	`object`	-	Configuration for image generation. If set for models that don’t support these configuration options, the system will return an error.
`>imageConfig.aspectRatio`	`string`	`1:1` `2:3` `3:2` `3:4` `4:3` `9:16` `16:9` `21:9`	Aspect ratio of the generated image. If not specified, the model will select the appropriate aspect ratio based on the specified content.
`>imageConfig.imageSize`	`string`	`1k` `2k` `4k`	Approximate size of the generated image. If not specified, default `1k`.
`mediaResolution`	`enum`	`MEDIA_RESOLUTION_UNSPECIFIED` `MEDIA_RESOLUTION_LOW` `MEDIA_RESOLUTION_MEDIUM` `MEDIA_RESOLUTION_HIGH`	If specified, uses the specified media resolution.

Note: thinkingConfig.thinking_level is only supported on Gemini 3.0 and above. It cannot be used together with thinking_budget; doing so will return an error.

Safety Settings Structure

Field	Type	Required	Range	Description
`category`	`string`	✅	`HARM_CATEGORY_HATE_SPEECH` `HARM_CATEGORY_SEXUALLY_EXPLICIT` `HARM_CATEGORY_DANGEROUS_CONTENT` `HARM_CATEGORY_HARASSMENT` `HARM_CATEGORY_CIVIC_INTEGRITY`	The harm category to apply the safety setting to.
`threshold`	`string`	✅	`BLOCK_ONLY_HIGH` `BLOCK_MEDIUM_AND_ABOVE` `BLOCK_LOW_AND_ABOVE` `BLOCK_NONE`	The threshold for blocking content.

Multimodal input

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "base64-encoded-image-data"
          }
        },
        {
          "text": "Describe this image."
        }
      ]
    }
  ]
}

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "application/pdf",
            "data": "base64-encoded-pdf-data"
          }
        },
        {
          "text": "Summarize the content of this PDF document."
        }
      ]
    }
  ]
}

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "image/png",
            "fileUri": "https://robohash.org/50.png"
          }
        },
        {
          "text": "What is shown in this JPEG image?"
        }
      ]
    }
  ]
}

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "application/pdf",
            "fileUri": "https://pdfobject.com/pdf/sample.pdf"
          }
        },
        {
          "text": "Extract key information from this PDF file."
        }
      ]
    }
  ]
}

Input Parameters

Field	Type	Required	Range	Description
`parts`	`array<object>`	✅	`text` `inlineData` `fileData`	The content parts of the message, which can contain different types of content .
`>parts.inlineData`	`object`	✅	-	Inline media content. If used, data must be base64-encoded.
`>>parts.inlineData.mimeType`	`string`	✅ if inlineData is used	`application/pdf` `image/jpeg`	The IANA-standard MIME type of the source data. If the provided MIME type is not supported, the system will return an error.
`>>parts.inlineData.data`	`string`	✅ if inlineData is used	-	Base64 encoded data.
`>parts.fileData`	`object`	-	-	File media content. If used, fileUri must be provided.
`>>parts.fileData.mimeType`	`string`	-	`application/pdf` `image/jpeg`	The IANA-standard MIME type of the source data.
`>>parts.fileData.fileUri`	`string`	✅ if fileData is used	-	The URI of the file to be processed.

​Authorization

​Request Body

​Core Parameters

​Advanced Parameters

​Web Search

​Tools Structure

​Tool Config Structure

​Generation Config Structure

​Safety Settings Structure

​Multimodal input

​Input Parameters

Authorization

Request Body

Core Parameters

Advanced Parameters

Web Search

Tools Structure

Tool Config Structure

Generation Config Structure

Safety Settings Structure

Multimodal input

Input Parameters