official
Chat
Create an chat message
POST
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
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 |
|---|---|---|---|
generationConfig | object | - | Configuration options for content generation. See Generation Configuration |
safetySettings | array<object> | - | List of unique SafetySetting instances for filtering unsafe content. Each SafetyCategory should have at most one setting. See Safety Settings |
tools | array<object> | - | List of tools the model may use to generate the next response. Supported tools include Function and codeExecution. |
systemInstruction | object | - | See System instruction. |
async | boolean | - | Whether to provide asynchronous responses (only supports non-streaming requests) |
Generation Configuration Structure
| Field | Type | Required | Description |
|---|---|---|---|
temperature | number | - | Controls the randomness of the output. Range in 0.0 - 1.0. |
topP | number | - | Nucleus sampling probability threshold. Range in 0.0 - 1.0. |
topK | integer | - | Top-k sampling parameter. |
maxOutputTokens | integer | - | Maximum number of tokens to generate. |
stopSequences | array<string> | - | Sequences at which to stop generation. |
responseMimeType | string | - | MIME type of the response. Can be text/plain application/json. |
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. |
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. |
System Instruction Structure
| Field | Type | Required | Range | Description |
|---|---|---|---|---|
role | string | - | user | The role for the system instruction. If specified, must be user. |
parts | array<object> | ✅ | - | The content parts of the system instruction, containing the instructional text for the model. |
>parts.text | string | ✅ | - | The text content of the system instruction. Used to set the model’s behavior, persona, or context before the conversation begins. |