MaaS Gemini Native API

Request Method

POST

Request Path:

Non-streaming request: https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/generateContent
Streaming request: https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/streamGenerateContent

Path Parameters

Parameter	Type	Required	Description
`endpointPath`	string	No	Unique identifier for the path, obtained by subscribing to the model
`modelName`	string	Yes	Model name, e.g., MaaS_2.5_pro
`alt`	string	No	Return result in sse format. Value: sse

Body Parameters

Parameter	Type	Required	Description
`cachedContent`	string	No	Name of cached content used as prediction context
`contents`	Content[]	Yes	Conversation content with the model (single or multiple rounds)
`systemInstruction`	Content	No	System instruction
`tools`	Tool[]	No	Function call definition
`safetySettings`	SafetySetting[]	No	Safety settings
`generationConfig`	GenerationConfig	No	Generation configuration
`labels`	map	No	Key-value pair formatted metadata, not supported temporarily

Content Object

Parameter	Type	Required	Description
`role`	string	No	Source of the message: `user` (user) or `model` (model)
`parts`	Part[]	Yes	Ordered list of message parts

Part Object

Parameter	Type	Required	Description
`text`	string	Optional	Text content
`inlineData`	Blob	Optional	Inline data
`fileData`	FileData	Optional	File data
`functionCall`	FunctionCall	Optional	Function call
`functionResponse`	FunctionResponse	Optional	Function response
`videoMetadata`	VideoMetadata	No	Video metadata

Blob Object (Inline Data)

Parameter	Type	Required	Description
`mimeType`	string	Yes	Supported MIME types: `application/pdf`, `audio/mpeg`, `image/png`, `video/mp4`, etc.
`data`	String	Yes	Base64 encoded data (maximum 20MB)

FileData Object

Parameter	Type	Required	Description
`mimeType`	string	Yes	File MIME type
`fileUri`	string	Yes	File URI (Cloud Storage, HTTP, or YouTube)

VideoMetadata Object

Parameter	Type	Required	Description
`startOffset`	Long	No	Video start offset
`endOffset`	Long	No	Video end offset

SafetySetting Object

Parameter	Type	Required	Description
`category`	String	Optional	Safety category: `HARM_CATEGORY_SEXUALLY_EXPLICIT`, `HARM_CATEGORY_HATE_SPEECH`, `HARM_CATEGORY_HARASSMENT`, `HARM_CATEGORY_DANGEROUS_CONTENT`
`threshold`	String	Optional	Blocking threshold: `BLOCK_LOW_AND_ABOVE`, `BLOCK_MEDIUM_AND_ABOVE`, `BLOCK_ONLY_HIGH`, `BLOCK_NONE`, `OFF`
`method`	String	Optional	Blocking method: `SEVERITY` or `PROBABILITY`

GenerationConfig Object

Parameter	Type	Required	Description
`temperature`	float	No	Randomness control (0.0-2.0, default 1.0)
`topP`	float	No	Nucleus sampling (0.0-1.0, default 0.95)
`candidateCount`	int	No	Number of response variants (1-8, default 1)
`maxOutputTokens`	int	No	Maximum number of output tokens
`stopSequences`	string[]	No	Stop sequences (up to 5)
`presencePenalty`	float	No	Presence penalty (-2.0 to 2.0) not supported temporarily
`frequencyPenalty`	float	No	Frequency penalty (-2.0 to 2.0) not supported temporarily
`responseMimeType`	string	No	Response MIME type: `application/json`, `text/plain`, `text/x.enum`
`responseSchema`	json	No	Response schema (to be used with responseMimeType)
`seed`	int	No	Random seed
`responseLogprobs`	boolean	No	Whether to return token log probabilities, not supported temporarily
`logprobs`	int	No	Number of candidate tokens to return (1-5), not supported temporarily
`audioTimestamp`	boolean	No	Whether to enable audio timestamps, not supported temporarily
`thinkingConfig`	ThinkingConfig	No	Thinking configuration

ThinkingConfig Object

Parameter	Type	Required	Description
`includeThoughts`	boolean	No	Indicates whether to include thinking in the result
`thinkingBudget`	int	No	Controls the number of thinking tokens

Response Body

Response Parameters

Parameter	Type	Description
`candidates`	Candidate[]	Generated candidate contents
`usageMetadata`	UsageMetadata	Token usage metadata
`modelVersion`	string	Version of the model used (e.g., `gemini-1.5-flash-002`)

Candidate Object

Parameter	Type	Description
`content`	Content	Generated content
`finishReason`	enum	Reason for termination: `FINISH_REASON_STOP`, `FINISH_REASON_MAX_TOKENS`, `FINISH_REASON_SAFETY`, `FINISH_REASON_RECITATION`, etc.
`safetyRatings`	SafetyRating[]	Safety ratings
`citationMetadata`	CitationMetadata	Citation metadata
`avgLogprobs`	double	Average log probability
`logprobsResult`	LogprobsResult	Log probability result

SafetyRating Object

Parameter	Type	Description
`category`	enum	Safety category
`probability`	enum	Harm probability: `NEGLIGIBLE`, `LOW`, `MEDIUM`, `HIGH`
`blocked`	boolean	Whether it is blocked

CitationMetadata Object

Parameter	Type	Description
`citations`	Citation[]	List of citations

Citation Object

Parameter	Type	Description
`startIndex`	integer	Citation start position
`endIndex`	integer	Citation end position
`uri`	string	Citation source URI
`title`	string	Citation title
`license`	string	Citation license
`publicationDate`	Date	Publication date

UsageMetadata Object

Parameter	Type	Description
`promptTokenCount`	integer	Number of input tokens
`candidatesTokenCount`	integer	Number of output tokens
`totalTokenCount`	integer	Total number of tokens

LogprobsResult Object

Parameter	Type	Description
`topCandidates`	TopCandidates[]	Candidate tokens for each step
`chosenCandidates`	ChosenCandidate[]	Tokens selected by the model

TopCandidates Object

Parameter	Type	Description
`candidates`	CandidateToken[]	List of candidate tokens

CandidateToken Object

Parameter	Type	Description
`token`	string	Token text
`logProbability`	float	Log probability of the token

ChosenCandidate Object

Parameter	Type	Description
`token`	string	Token selected by the model
`logProbability`	float	Log probability of the token

Example Request

Request Parameter Format

{
  "cachedContent": string,
  "contents": [
    {
      "role": string,
      "parts": [
        {
          // Union field data can be only one of the following:
          "text": string,
          "inlineData": {
            "mimeType": string,
            "data": string
          },
          "fileData": {
            "mimeType": string,
            "fileUri": string
          },
          // End of list of possible types for union field data.

          "videoMetadata": {
            "startOffset": {
              "seconds": integer,
              "nanos": integer
            },
            "endOffset": {
              "seconds": integer,
              "nanos": integer
            }
          }
        }
      ]
    }
  ],
  "systemInstruction": {
    "role": string,
    "parts": [
      {
        "text": string
      }
    ]
  },
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": string,
          "description": string,
          "parameters": {
            object (OpenAPI Object Schema)
          }
        }
      ]
    }
  ],
  "safetySettings": [
    {
      "category": enum (HarmCategory),
      "threshold": enum (HarmBlockThreshold)
    }
  ],
  "generationConfig": {
    "temperature": number,
    "topP": number,
    "topK": number,
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "presencePenalty": float,
    "frequencyPenalty": float,
    "stopSequences": [
      string
    ],
    "responseMimeType": string,
    "responseSchema": schema,
    "seed": integer,
    "responseLogprobs": boolean,
    "logprobs": integer,
    "audioTimestamp": boolean
  },
  "labels": {
    string: string
  }
}

Complete Requests

1. Streaming Request

curl --location 'https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/streamGenerateContent?alt=sse' \
--header 'Authorization: Bearer {YOUR AK}' \
--header 'Content-Type: application/json' \
--data '{
    "contents": [
      {
        "role":"user",
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

2. Streaming Structure Request

curl --location 'https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/streamGenerateContent' \
--header 'Authorization: Bearer {YOUR AK}' \
--header 'Content-Type: application/json' \
--data '{
    "contents": [
      {
        "role":"user",
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

3. Non-streaming Request

curl --location 'https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/generateContent' \
--header 'Authorization: Bearer {YOUR AK}' \
--header 'Content-Type: application/json' \
--data '{
    "contents": [
      {
        "role":"user",
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Example Response Results

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": string
          }
        ]
      },
      "finishReason": enum (FinishReason),
      "safetyRatings": [
        {
          "category": enum (HarmCategory),
          "probability": enum (HarmProbability),
          "blocked": boolean
        }
      ],
      "citationMetadata": {
        "citations": [
          {
            "startIndex": integer,
            "endIndex": integer,
            "uri": string,
            "title": string,
            "license": string,
            "publicationDate": {
              "year": integer,
              "month": integer,
              "day": integer
            }
          }
        ]
      },
      "avgLogprobs": double,
      "logprobsResult": {
        "topCandidates": [
          {
            "candidates": [
              {
                "token": string,
                "logProbability": float
              }
            ]
          }
        ],
        "chosenCandidates": [
          {
            "token": string,
            "logProbability": float
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": integer,
    "candidatesTokenCount": integer,
    "totalTokenCount": integer
  },
  "modelVersion": string
}