MaaS Gemini原生协议 API

请求方法

POST

请求路径：

非流式请求：https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/generateContent
流式请求: https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/streamGenerateContent

路径参数

参数	类型	必需	描述
`endpointPath`	string	否	路径唯一标识，通过订购模型获取
`modelName`	string	是	模型名称，例如 MaaS_2.5_pro
`alt`	string	否	sse格式返回结果。值：sse

Body参数

参数	类型	必需	描述
`cachedContent`	string	否	用作预测上下文的缓存内容名称
`contents`	Content[]	是	与模型的对话内容（单轮或多轮）
`systemInstruction`	Content	否	系统指令
`tools`	Tool[]	否	函数调用定义
`safetySettings`	SafetySetting[]	否	安全设置
`generationConfig`	GenerationConfig	否	生成配置
`labels`	map	否	键值对格式的元数据，暂不支持

Content 对象

参数	类型	必需	描述
`role`	string	否	消息来源：`user`（用户）或 `model`（模型）
`parts`	Part[]	是	消息的有序部分列表

Part 对象

参数	类型	必需	描述
`text`	string	可选	文本内容
`inlineData`	Blob	可选	内联数据
`fileData`	FileData	可选	文件数据
`functionCall`	FunctionCall	可选	函数调用
`functionResponse`	FunctionResponse	可选	函数响应
`videoMetadata`	VideoMetadata	否	视频元数据

Blob 对象（内联数据）

参数	类型	必需	描述
`mimeType`	string	是	支持的 MIME 类型： `application/pdf`, `audio/mpeg`, `image/png`, `video/mp4` 等
`data`	String	是	base64 编码数据（最大 20MB）

FileData 对象

参数	类型	必需	描述
`mimeType`	string	是	文件 MIME 类型
`fileUri`	string	是	文件 URI（Cloud Storage、HTTP 或 YouTube）

VideoMetadata 对象

参数	类型	必需	描述
`startOffset`	Long	否	视频起始偏移
`endOffset`	Long	否	视频结束偏移

SafetySetting 对象

参数	类型	必需	描述
`category`	String	可选	安全类别： `HARM_CATEGORY_SEXUALLY_EXPLICIT`, `HARM_CATEGORY_HATE_SPEECH`, `HARM_CATEGORY_HARASSMENT`, `HARM_CATEGORY_DANGEROUS_CONTENT`
`threshold`	String	可选	屏蔽阈值： `BLOCK_LOW_AND_ABOVE`, `BLOCK_MEDIUM_AND_ABOVE`, `BLOCK_ONLY_HIGH`, `BLOCK_NONE`, `OFF`
`method`	String	可选	屏蔽方法：`SEVERITY` 或 `PROBABILITY`

GenerationConfig 对象

参数	类型	必需	描述
`temperature`	float	否	随机性控制（0.0-2.0，默认 1.0）
`topP`	float	否	核采样（0.0-1.0，默认 0.95）
`candidateCount`	int	否	响应变体数量（1-8，默认 1）
`maxOutputTokens`	int	否	最大输出 token 数
`stopSequences`	string[]	否	停止序列（最多 5 个）
`presencePenalty`	float	否	存在惩罚（-2.0 到 2.0）暂不支持
`frequencyPenalty`	float	否	频率惩罚（-2.0 到 2.0）暂不支持
`responseMimeType`	string	否	响应 MIME 类型： `application/json`, `text/plain`, `text/x.enum`
`responseSchema`	json	否	响应模式（需配合 responseMimeType）
`seed`	int	否	随机种子
`responseLogprobs`	boolean	否	是否返回 token 对数概率，暂不支持
`logprobs`	int	否	返回的候选 token 数量（1-5），暂不支持
`audioTimestamp`	boolean	否	是否启用音频时间戳，暂不支持
thinkingConfig	ThinkingConfig	否	思考配置

ThinkingConfig 对象

参数	类型	必需	描述
`includeThoughts`	boolean	否	指示是否在结果中是否包含thinking
`thinkingBudget`	int	否	控制思考token的数量

响应正文

响应参数

参数	类型	描述
`candidates`	Candidate[]	生成的候选内容
`usageMetadata`	UsageMetadata	token 使用元数据
`modelVersion`	string	使用的模型版本（如 `gemini-1.5-flash-002`）

Candidate 对象

参数	类型	描述
`content`	Content	生成的内容
`finishReason`	enum	停止原因： `FINISH_REASON_STOP`, `FINISH_REASON_MAX_TOKENS`, `FINISH_REASON_SAFETY`, `FINISH_REASON_RECITATION` 等
`safetyRatings`	SafetyRating[]	安全评分
`citationMetadata`	CitationMetadata	引用元数据
`avgLogprobs`	double	平均对数概率
`logprobsResult`	LogprobsResult	对数概率结果

SafetyRating 对象

参数	类型	描述
`category`	enum	安全类别
`probability`	enum	有害概率： `NEGLIGIBLE`, `LOW`, `MEDIUM`, `HIGH`
`blocked`	boolean	是否被阻止

CitationMetadata 对象

参数	类型	描述
`citations`	Citation[]	引用列表

Citation 对象

参数	类型	描述
`startIndex`	integer	引用起始位置
`endIndex`	integer	引用结束位置
`uri`	string	引用来源 URI
`title`	string	引用标题
`license`	string	引用许可
`publicationDate`	Date	发布日期

UsageMetadata 对象

参数	类型	描述
`promptTokenCount`	integer	输入 token 数
`candidatesTokenCount`	integer	输出 token 数
`totalTokenCount`	integer	总 token 数

LogprobsResult 对象

参数	类型	描述
`topCandidates`	TopCandidates[]	每个步骤的候选 token
`chosenCandidates`	ChosenCandidate[]	模型选择的 token

TopCandidates 对象

参数	类型	描述
`candidates`	CandidateToken[]	候选 token 列表

CandidateToken 对象

参数	类型	描述
`token`	string	token 文本
`logProbability`	float	token 的对数概率

ChosenCandidate 对象

参数	类型	描述
`token`	string	模型选择的 token
`logProbability`	float	token 的对数概率

示例请求

请求参数格式

{
  "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
  }
}

完整请求

1. 流式请求：

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.流式结构请求

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.非流式请求

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"
          }
        ]
      }
    ]
  }'

响应结果示例

{
  "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
}