MaaS_Ge

模型说明

MaaS_Ge_omni_flash_preview_20260630 模型目前仅支持 Interaction API

实践方式

该接口可支持同步任务模式和异步任务模式，在create接口中使用backgroud=true即为异步任务，目前实测异步任务的id可从Get接口中查询任务结果

但对于MaaS_Ge_omni_flash_preview_20260630 模型，异步任务id作为previous_interaction_id在create接口中使用暂不生效（供应商侧正在确认问题）。

参数支持情况

对于MaaS_Ge_omni_flash_preview_20260630 模型

• response_modalities仅支持text和video

• 建议使用step形式的input来传递视频内容

• generation_config.max_output_tokens建议填较大值，实测此参数过小时，可能导致返回Request contains an invalid argument.

• 暂不支持工具调用

• 暂不支持流式调用

功能接口详情

创建 Interaction（生成）

请求 URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/omni/interactions

请求 Header

Header	是否必填	说明
Authorization	是	Bearer {YOUR_AK}
Content-Type	是	application/json

请求 Body 参数

参数名	字段类型	是否必填	默认值	描述
input	string 或 Content 数组 或 Step 数组	是	-	交互的输入（见 input 字段说明）。
system_instruction	string	否	-	交互的系统指令。
tools	array(Tool)	否	-	模型在交互过程中可调用的工具声明列表（见 tools 字段说明）。
response_format	ResponseFormat 或 ResponseFormatList	否	-	强制生成的响应为符合此字段所指定 JSON Schema 的 JSON 对象。
response_mime_type	string	否	-	响应的 MIME 类型。若设置了 response_format，则此字段为必填。
stream	boolean	否	false	仅输入。是否以流式方式返回交互。 当前模型暂不支持流式调用
store	boolean	否	-	仅输入。是否存储响应和请求以供后续检索。
background	boolean	否	-	仅输入。是否在后台运行模型交互。
generation_config	GenerationConfig	否	-	模型配置参数（见 generation_config 字段说明）。
previous_interaction_id	string	否	-	上一次交互的 ID（如有）。
response_modalities	array(string)	否	-	请求的响应模态。可选值：text、image、audio、video、document。

input 字段说明

input 为必填字段，支持以下三种形式之一（与 Google Interactions API 一致）：

1. 字符串（string）

直接传入用户文本，例如：

"input": "请用一句话介绍人工智能。"

2. Content 数组（array of Content）

多模态内容块数组。每个 Content 通过 type 区分类型，详见 Content 类型。

！注意data传递base64数据时，不要携带base64头

示例：

"input": [
  { "type": "text", "text": "请描述这张图片。" },
  { "type": "image", "data": "BASE64_ENCODED_IMAGE", "mime_type": "image/png" }
]

3. Step 数组（array of Step）

结构化步骤数组，用于显式区分用户输入等步骤，详见 Step 类型（input）。

示例：

"input": [
  {
    "type": "user_input",
    "content": [
      { "type": "text", "text": "你好，请介绍一下你自己。" }
    ]
  }
]

Content 类型

Content 为多态对象，通过 type 字段区分具体类型。

TextContent（文本内容块）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "text"。
text	string	是	文本内容。
annotations	array(Annotation)	否	模型生成内容的引用信息（见 Annotation 类型）。

Annotation 类型

annotations 为多态数组，通过 type 区分具体引用类型。

UrlCitation（URL 引用）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "url_citation"。
url	string	否	URL 地址。
title	string	否	URL 标题。
start_index	integer	否	被归因于该来源的响应片段起始位置（以字节计）。
end_index	integer	否	被归因片段的结束位置（不含）。

FileCitation（文件引用）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "file_citation"。
document_uri	string	否	文件的 URI。
file_name	string	否	文件名称。
source	string	否	文本片段所归因的来源。
custom_metadata	object	否	用户提供的检索上下文元数据。
page_number	integer	否	被引用文档的页码（如适用）。
media_id	string	否	图像引用时的媒体 ID（如适用）。
start_index	integer	否	被归因于该来源的响应片段起始位置（以字节计）。
end_index	integer	否	被归因片段的结束位置（不含）。

PlaceCitation（地点引用）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "place_citation"。
place_id	string	否	地点 ID，格式为 places/{place_id}。
name	string	否	地点标题。
url	string	否	地点的 URI 引用。
review_snippets	array(ReviewSnippet)	否	用于生成地点相关回答的用户评价片段。

ReviewSnippet（评价片段）

参数名	字段类型	是否必填	描述
title	string	否	评价标题。
url	string	否	对应 Google Maps 用户评价的链接。
review_id	string	否	评价片段 ID。
start_index	integer	否	被归因于该来源的响应片段起始位置（以字节计）。
end_index	integer	否	被归因片段的结束位置（不含）。

ImageContent（图像内容块）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "image"。
data	string	否	图像内容（Base64 编码）。
uri	string	否	图像 URI。
mime_type	string	否	图像 MIME 类型。可选值：image/png、image/jpeg、image/webp、image/heic、image/heif、image/gif、image/bmp、image/tiff。
resolution	string	否	媒体分辨率。可选值：low、medium、high、ultra_high。

AudioContent（音频内容块）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "audio"。
data	string	否	音频内容（Base64 编码）。
uri	string	否	音频 URI。
mime_type	string	否	音频 MIME 类型。可选值：audio/wav、audio/mp3、audio/aiff、audio/aac、audio/ogg、audio/flac、audio/mpeg、audio/m4a、audio/l16、audio/opus、audio/alaw、audio/mulaw。
channels	integer	否	音频声道数。
sample_rate	integer	否	音频采样率。

VideoContent（视频内容块）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "video"。
data	string	否	视频内容（Base64 编码）。
uri	string	否	视频 URI。
mime_type	string	否	视频 MIME 类型。可选值：video/mp4、video/mpeg、video/mpg、video/mov、video/avi、video/x-flv、video/webm、video/wmv、video/3gpp。
resolution	string	否	媒体分辨率。可选值：low、medium、high、ultra_high。

DocumentContent（文档内容块）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "document"。
data	string	否	文档内容（Base64 编码）。
uri	string	否	文档 URI。
mime_type	string	否	文档 MIME 类型。可选值：application/pdf。

Step 类型（input）

Step 为多态对象，通过 type 字段区分具体类型。以下为常用输入步骤类型：

UserInputStep（用户输入步骤）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "user_input"。
content	array(Content)	否	用户提供的输入内容，元素为上述 Content 类型。

ModelOutputStep（模型输出步骤）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "model_output"。
content	array(Content)	否	模型生成的输出内容，元素为上述 Content 类型。

ThoughtStep（思考步骤）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "thought"。
signature	string	否	用于后端校验的签名哈希。
summary	ThoughtSummaryContent	否	思考摘要，结构与 TextContent 相同（type 为 "text"，含 text 字段）。

tools 字段说明

tools 为工具声明数组，每个 Tool 通过 type 区分具体类型。

Function（函数工具）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "function"。
name	string	否	函数名称。
description	string	否	函数描述。
parameters	object	否	函数参数的 JSON Schema。

CodeExecution（代码执行工具）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "code_execution"。

GoogleSearch（Google 搜索工具）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "google_search"。
search_types	array(string)	否	启用的搜索增强类型。可选值：web_search、image_search、enterprise_web_search。

UrlContext（URL 上下文工具）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "url_context"。

GoogleMaps（Google 地图工具）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "google_maps"。
enable_widget	boolean	否	是否在工具调用结果的响应中返回 widget 上下文 token。
latitude	number	否	用户位置的纬度。
longitude	number	否	用户位置的经度。

Retrieval（文件检索工具）

参数名	字段类型	是否必填	描述
type	string	是	固定为 "retrieval"。
retrieval_types	array(string)	否	启用的文件检索类型。可选值：vertex_ai_search。
vertex_ai_search_config	VertexAISearchConfig	否	Vertex AI Search 配置（见 vertex_ai_search_config 嵌套字段）。

vertex_ai_search_config 嵌套字段

参数名	字段类型	是否必填	描述
engine	string	否	Agent Platform Search 引擎。
datastores	array(string)	否	Agent Platform Search 数据存储。

generation_config 字段说明

参数名	字段类型	是否必填	描述
temperature	number	否	控制输出的随机性。
top_p	number	否	采样时考虑的最大累积 token 概率。
seed	integer	否	用于解码的可复现性种子。
stop_sequences	array(string)	否	遇到这些字符序列时停止输出交互。
thinking_level	string	否	模型应生成的思考 token 级别。可选值：minimal、low、medium、high。
thinking_summaries	string	否	是否在响应中包含思考摘要。可选值：auto、none。
max_output_tokens	integer	否	响应中包含的最大 token 数。
speech_config	SpeechConfig	否	语音交互配置（见 speech_config 嵌套字段）。
image_config	ImageConfig	否	图像交互配置（见 image_config 嵌套字段）。
tool_choice	ToolChoiceConfig 或 ToolChoiceType	否	工具选择配置。

speech_config 嵌套字段

参数名	字段类型	是否必填	描述
voice	string	否	说话者的声音。
language	string	否	语音的语言。
speaker	string	否	说话者名称，应与提示中给出的说话者名称一致。

image_config 嵌套字段

参数名	字段类型	是否必填	描述
aspect_ratio	string	否	宽高比。可选值：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9、1:8、8:1、1:4、4:1。
image_size	string	否	图像尺寸。可选值：512、1K、2K、4K。

响应参数（同步，stream=false）

返回 Interaction 资源。

参数名	字段类型	描述
id	string	输出字段。交互的唯一标识符。
status	string	输出字段。交互状态。可选值：in_progress、requires_action、completed、failed、cancelled、incomplete。
created	string	输出字段。响应创建时间，ISO 8601 格式（YYYY-MM-DDThh:mm:ssZ）。
updated	string	输出字段。响应最后更新时间，ISO 8601 格式。
role	string	输出字段。交互的角色。
model	string	用于生成交互的模型名称。
system_instruction	string	交互的系统指令。
tools	array(Tool)	模型在交互过程中可调用的工具声明列表。
usage	Usage	输出字段。交互请求的 token 用量统计（见 usage 字段说明），用于计费。
response_modalities	array(string)	请求的响应模态（TEXT、IMAGE、AUDIO 等）。
response_mime_type	string	响应的 MIME 类型。
previous_interaction_id	string	上一次交互的 ID（如有）。
steps	array(Step)	输出字段。构成交互的步骤列表（见 steps 字段说明）。
object	string	固定为 "interaction"。

usage 字段说明

参数名	字段类型	描述
total_input_tokens	integer	提示（上下文）中的 token 数。
input_tokens_by_modality	array(ModalityTokens)	按模态拆分的输入 token 用量。
total_cached_tokens	integer	提示中已缓存部分的 token 数。
cached_tokens_by_modality	array(ModalityTokens)	按模态拆分的缓存 token 用量。
total_output_tokens	integer	所有生成响应的 token 总数。
output_tokens_by_modality	array(ModalityTokens)	按模态拆分的输出 token 用量。
total_tool_use_tokens	integer	工具调用提示中的 token 数。
tool_use_tokens_by_modality	array(ModalityTokens)	按模态拆分的工具调用 token 用量。
total_thought_tokens	integer	思考类模型的思考 token 数。
total_tokens	integer	交互请求的总 token 数（提示 + 响应 + 其他内部 token）。

ModalityTokens 对象

参数名	字段类型	描述
modality	string	与 token 计数关联的模态。可选值：text、image、audio、video、document。
tokens	integer	该模态的 token 数。

steps 字段说明

steps 为输出字段，表示交互中的各个步骤。步骤类型与请求 input 中的 Step 类型（input） 一致，常见类型如下：

UserInputStep（用户输入步骤）

参数名	字段类型	描述
type	string	固定为 "user_input"。
content	array(Content)	用户提供的输入内容。

ModelOutputStep（模型输出步骤）

参数名	字段类型	描述
type	string	固定为 "model_output"。
content	array(Content)	模型生成的输出内容。

ThoughtStep（思考步骤）

参数名	字段类型	描述
type	string	固定为 "thought"。
signature	string	用于后端校验的签名哈希。
summary	ThoughtSummaryContent	思考摘要。

content 中的 Content 块类型与上文 Content 类型 一致（text、image、audio、video、document 等）。

流式响应（stream=true）

当 stream=true 时，响应为 SSE（Content-Type: text/event-stream）流，每个事件包含 event 行与 data 行。data 为 JSON 对象，其中 event_type 标识事件类型。

本接口涉及的主要 SSE 事件如下：

事件名	event_type	说明
interaction.created	interaction.created	交互已创建。interaction 包含 id、status 等初始信息。
step.delta	step.delta	增量内容。index 为步骤索引，delta 为增量数据（如 type: "text" 时的 text 字段）。
interaction.completed	interaction.completed	交互完成。interaction 包含最终状态及 usage 用量统计。
done	-	流结束标记，data 为 [DONE]。

请求示例（同步）

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/omni/interactions' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
    "input": [
        {
            "type": "user_input",
            "content": [
                {
                    "type": "text",
                    "text": "Generate a cute cat, playing with kids."
                }
            ]
        }
    ],
    "response_modalities": ["text", "video"]
}'

响应示例（同步）

{
    "id": "rnVLaoO1KuKF694Pr4GXgQI",
    "status": "completed",
    "role": "model",
    "created": "2026-07-06T09:30:56Z",
    "updated": "2026-07-06T09:30:56Z",
    "object": "interaction",
    "model": "gemini-omni-flash-preview",
    "usage": {
        "total_input_tokens": 9,
        "input_tokens_by_modality": [
            {
                "modality": "text",
                "tokens": 9
            }
        ],
        "total_output_tokens": 57920,
        "output_tokens_by_modality": [
            {
                "modality": "video",
                "tokens": 57920
            }
        ],
        "total_tool_use_tokens": 0,
        "total_thought_tokens": 331,
        "total_tokens": 58260
    },
    "steps": [
        {
            "type": "thought",
            "signature": "signature",
            "summary": [
                {
                    "text": "**Creating a Charming Scene**\n\nI'm developing a prompt for a video model, envisioning a playful scene. It starts in a sunny living room with a boy and girl interacting with a cat. Close-ups will highlight the cat's joy and focus, as well as the children's reactions. The video will culminate with the cat resting on the boy's lap. The entire scene will have cheerful background music and sound effects.\n\n\n",
                    "type": "text"
                }
            ]
        },
        {
            "type": "model_output",
            "content": [
                {
                    "type": "video",
                    "data": "video data encoded by base64"
                    "mime_type": "video/mp4"
                }
            ]
        }
    ]
}

查询Get接口

请求 URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/omni/interactions/{interactionId}

请求 Header

Header	是否必填	说明
Authorization	是	Bearer {YOUR_AK}
Content-Type	是	application/json

请求 Query 参数

参数名	字段类型	是否必填	默认值	描述
stream	boolean	否	-	是否以 SSE 流式拉取；默认 false
last_event_id	string	否	-	流式续传时上一事件 ID（仅 stream=true）

响应参数

响应体与同步创建响应 相同。

请求示例

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/omni/interactions/{interactionId}' \
--header 'Authorization: Bearer {YOUR_AK}'