# Gemini Embedding 2 向量嵌入

> 大语言模型

Gemini Embedding 2（`gemini-embedding-2`）是 Google 的多模态嵌入模型，可将文本、图片、视频、音频和 PDF 转换为高维向量，用于多模态语义搜索、内容推荐、聚类分析和异常检测。单个请求可以混合多种模态；只需要纯文本嵌入时也可以使用 OpenAI 兼容的 `POST /v1/embeddings`。

`content.parts[]` 既支持文本 Part `{"text":"..."}`，也支持文件 Part `{"file_data":{"mime_type":"...","file_uri":"..."}}`，文件需通过服务端可访问的地址提供。响应返回 `embedding.values` 向量和 `usageMetadata` 分模态 token 用量。

## 输出维度

`outputDimensionality` 支持 128 至 3072，默认 3072。降到 768 或 1536 可减少存储和计算成本，语义搜索精度略有下降但多数场景可忽略；追求最高精度时保持默认值。

## 单请求限制

| 模态 | 数量上限 | 其他限制 | 支持的 MIME |
| --- | --- | --- | --- |
| 图片 | 6 | — | `image/png`、`image/jpeg`、`image/webp`、`image/bmp`、`image/heic`、`image/heif`、`image/avif` |
| 文档 | 1 | 最多 6 页 | `application/pdf` |
| 视频 | 1 | 含音频最长 80 秒，不含音频最长 120 秒 | `video/mp4`、`video/mpeg` |
| 音频 | 1 | 最长 180 秒 | `audio/mp3`、`audio/wav` |

## 请求地址

`POST https://api.modelverse.cn/v1beta/models/{modelsId}:embedContent`

## 请求参数

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| modelsId | path | string | Yes | 固定使用 `gemini-embedding-2`。 |

## 请求体

## 响应

- **200** — 嵌入向量和用量信息。
- **400** — 请求参数无效，例如 `outputDimensionality` 超出范围、文件 URI 不可访问或 MIME 类型不匹配。
- **default** — 错误响应。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "gemini-addons接口文档",
    "version": "v1beta",
    "description": "本文档说明 ModelVerse 上 Gemini 的扩展接口，覆盖媒体分析、显式缓存、Gemini Embedding 2 向量嵌入和 Vertex 风格批量预测任务，包含请求体、响应体、示例以及错误响应等内容。"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "中国大陆"
    },
    {
      "url": "https://api.umodelverse.ai",
      "description": "海外"
    },
    {
      "url": "https://api-us-ca.umodelverse.ai",
      "description": "美国洛杉矶"
    },
    {
      "url": "https://api-sg.umodelverse.ai",
      "description": "新加坡"
    },
    {
      "url": "https://api-ge-fra.umodelverse.ai",
      "description": "法兰克福"
    }
  ],
  "tags": [
    {
      "name": "Gemini Add-ons",
      "description": "Gemini 媒体分析、显式缓存、向量嵌入和批量预测任务。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "xGoogApiKey": []
    }
  ],
  "paths": {
    "/v1beta/models/{modelsId}:generateContent": {
      "post": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "geminiMediaAnalysis",
        "summary": "Gemini 媒体分析",
        "description": "使用 Gemini `generateContent` 分析图片、视频、音频、PDF 或文本文件。先上传文件，再在分析请求中引用文件地址，并附上问题或指令。\n\n## 文件地址与大文件分析\n\n支持以下两类地址：\n\n| 地址 | 使用方式 |\n| --- | --- |\n| `gs://bucket/object` | 使用本平台上传响应中的 `gcs_uri`。推荐用于大文件分析，由模型直接读取 GCS 文件，无需把文件内容编码进分析请求。 |\n| `https://...` / `http://...` | 使用上传响应中的 `s3_url` 或其他服务端可访问的公网地址；签名 URL 必须仍在有效期内。 |\n\n`gs://` 是上传成功后的文件引用地址。上传步骤仍然通过 `multipart/form-data` 发送本地文件。不要手工拼接 bucket 或把任意第三方 GCS 地址当作本平台已上传文件。\n\n## 1. 上传媒体文件\n\n调用 `POST /v1/files`，每次上传一个文件。使用 `Authorization: Bearer <MODELVERSE_API_KEY>` 或 `x-goog-api-key: <MODELVERSE_API_KEY>` 认证，上传和分析使用同一环境及同一公司、组织下的 API Key。\n\n| 表单字段 | 类型 | 必填 | 说明 |\n| --- | --- | --- | --- |\n| `purpose` | string | 是 | 固定为 `batch:gcs`，媒体分析上传也使用此值。 |\n| `usage` | string | 本流程必填 | 传 `inference`，表示文件用于在线推理。接口省略此字段时默认为 `batch`，因此媒体分析应显式填写。 |\n| `model` | string | 是 | `usage=inference` 时必填，例如 `gemini-4-argon`。建议填写后续分析使用的模型 ID；上传成功不代表该模型一定可调用，模型可用性在分析时校验。 |\n| `file` | binary | 是 | 本地媒体或文档文件，支持 PDF、图片、视频、音频等；可分析的格式取决于所选模型。 |\n\n以下 PDF 示例使用 API 地址 `https://api.modelverse.cn` 和 `gemini-4-argon`。请先在环境变量中设置 `MODELVERSE_API_KEY`，修改本地文件路径；在其他已支持该功能的环境使用时，替换 `BASE_URL` 和可用模型 ID。命令需要 `curl` 和 `jq`，按顺序执行。\n\n```bash\nBASE_URL=\"https://api.modelverse.cn\"\nMODEL=\"gemini-4-argon\"\nFILE_PATH=\"/path/to/document.pdf\"\nPROMPT=\"请概括这份 PDF 的主要内容，并列出关键章节。\"\n\ncurl --fail-with-body --location \"$BASE_URL/v1/files\" \\\n  --header \"Authorization: Bearer $MODELVERSE_API_KEY\" \\\n  --form 'purpose=batch:gcs' \\\n  --form 'usage=inference' \\\n  --form \"model=$MODEL\" \\\n  --form \"file=@$FILE_PATH;type=application/pdf\" \\\n  --output upload.json\n```\n\n成功响应示例（bucket、对象名和签名 URL 均为示意，使用实际响应中的值）：\n\n```json\n{\n  \"id\": \"6fd9bc58-d80e-47cb-b6ab-5b0e19173487.pdf\",\n  \"object\": \"file\",\n  \"bytes\": 52428800,\n  \"created_at\": 1794441600,\n  \"expires_at\": 1795046400,\n  \"filename\": \"document.pdf\",\n  \"purpose\": \"batch:gcs\",\n  \"gcs_uri\": \"gs://example-modelverse-bucket/6fd9bc58-d80e-47cb-b6ab-5b0e19173487.pdf\",\n  \"s3_url\": \"https://storage.googleapis.com/example-modelverse-bucket/6fd9bc58-d80e-47cb-b6ab-5b0e19173487.pdf?REPLACE_WITH_RETURNED_SIGNATURE\"\n}\n```\n\n| 响应字段 | 说明 |\n| --- | --- |\n| `id` | 平台文件标识；分析时使用完整的 `gcs_uri`，不要只传 `id`。 |\n| `gcs_uri` | `gs://` 开头的完整文件地址，传给下一步的 `fileData.fileUri`。 |\n| `s3_url` | 带签名的 HTTPS 地址，也可用于媒体分析；不要手工修改签名参数。 |\n| `bytes` / `filename` | 文件大小（字节）和原始文件名。 |\n| `created_at` / `expires_at` | 创建和过期时间，Unix 秒级时间戳；当前上传文件有效期为 7 天，以响应中的 `expires_at` 为准。 |\n\n## 2. 引用文件进行分析\n\n从上一步保存的 `upload.json` 提取 `gcs_uri`，作为 `fileData.fileUri`；PDF 的 `mimeType` 使用 `application/pdf`。以下命令会生成请求 JSON、发起分析并打印文本结果：\n\n```bash\nGCS_URI=$(jq -er '.gcs_uri | select(startswith(\"gs://\"))' upload.json)\njq -n --arg uri \"$GCS_URI\" --arg prompt \"$PROMPT\" '{\n  contents: [{\n    role: \"user\",\n    parts: [\n      {fileData: {fileUri: $uri, mimeType: \"application/pdf\"}},\n      {text: $prompt}\n    ]\n  }]\n}' > analysis-request.json\n\ncurl --fail-with-body --location \"$BASE_URL/v1beta/models/$MODEL:generateContent\" \\\n  --header \"Authorization: Bearer $MODELVERSE_API_KEY\" \\\n  --header 'Content-Type: application/json' \\\n  --data-binary @analysis-request.json \\\n  --output analysis.json\n\njq -r '.candidates[]?.content.parts[]? | .text // empty' analysis.json\n```\n\n分析结果位于 `candidates[].content.parts[].text`，token 用量位于 `usageMetadata`。请求示例还提供图片、视频、音频、文本文件和 GCS PDF 的写法。\n\n## 使用限制与排查\n\n- 上传请求体上限为 **1 GiB（1,073,741,824 字节，包含 multipart 开销）**。`gs://` 支持大文件引用，但实际可分析的文件大小、页数、时长和上下文 token 数仍受所选模型限制。\n- GCS 文件必须已在当前公司、组织下通过本平台上传且未过期。文件过期后重新上传，并使用新返回的 `gcs_uri`；`gs://` 不代表永久有效。\n- 同一次请求引用多个 GCS 文件时，文件必须属于同一服务方和项目；如同时使用显式缓存，缓存也必须与文件匹配。遇到不匹配错误时，使用同一环境和组织重新准备文件或缓存。\n- 媒体 Part 支持 `fileData.mimeType` / `fileData.fileUri` 和 `file_data.mime_type` / `file_data.file_uri` 两种写法，同一字段不要同时传两种。`mimeType` 必须与实际格式一致，例如 PDF 为 `application/pdf`、JPEG 为 `image/jpeg`、MP4 为 `video/mp4`、MP3 为 `audio/mpeg`。\n- `gs://` URI 必须包含 bucket 和对象路径，不带查询参数或片段；不要给它追加 HTTPS 签名参数。\n\n| 错误或现象 | 处理方式 |\n| --- | --- |\n| 上传提示 `model is required for inference uploads` | 补充非空 `model` 表单字段。 |\n| 上传提示 `usage must be batch or inference` | 媒体分析上传使用 `usage=inference`。 |\n| `400`，`invalid GCS file URI` / `GCS file mimeType is required` | 使用上传响应中的完整 `gcs_uri`，并填写正确 MIME 类型。 |\n| `404`，`GCS file not found or expired` | 检查环境、公司和组织是否一致，以及文件是否过期；必要时重新上传。 |\n| `400`，`file provider is not available for requested model` | 当前文件不支持所请求模型，确认该环境下模型与文件的兼容性。 |\n| `400`，`referenced files belong to different providers or projects` | 同一请求中的 GCS 文件来源不兼容，重新准备匹配的文件。 |\n| `503`，`affinity_unavailable` | 文件服务暂不可用，稍后重试；持续失败时提供请求标识联系支持。 |\n| 公网地址读取失败 | 检查服务端能否访问地址、签名是否过期，以及 MIME 类型是否正确。 |\n\n更多格式与模型能力请参考 [Gemini 官方文档](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/image-understanding)。",
        "parameters": [
          {
            "name": "modelsId",
            "in": "path",
            "required": true,
            "description": "支持所传媒体格式的 Gemini 模型 ID，例如 `gemini-4-argon`。",
            "schema": {
              "type": "string",
              "example": "gemini-4-argon"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeminiMediaGenerateContentRequest"
              },
              "examples": {
                "gcsPdf": {
                  "summary": "GCS PDF 大文件分析",
                  "description": "将 fileUri 替换为上传响应中的 gcs_uri。",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "fileData": {
                              "fileUri": "gs://example-modelverse-bucket/6fd9bc58-d80e-47cb-b6ab-5b0e19173487.pdf",
                              "mimeType": "application/pdf"
                            }
                          },
                          {
                            "text": "请概括这份 PDF 的主要内容，并列出关键章节。"
                          }
                        ]
                      }
                    ]
                  }
                },
                "image": {
                  "summary": "图片分析",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "file_data": {
                              "mime_type": "image/jpeg",
                              "file_uri": "https://example-file-host/modelverse/demo-image.jpg"
                            }
                          },
                          {
                            "text": "请描述这张图片中的主要对象和场景。"
                          }
                        ]
                      }
                    ]
                  }
                },
                "video": {
                  "summary": "视频分析",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "file_data": {
                              "mime_type": "video/mp4",
                              "file_uri": "https://example-file-host/modelverse/demo-video.mp4"
                            }
                          },
                          {
                            "text": "请总结这个视频的主要事件，并按时间顺序列出关键片段。"
                          }
                        ]
                      }
                    ]
                  }
                },
                "audio": {
                  "summary": "音频分析",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "file_data": {
                              "mime_type": "audio/mpeg",
                              "file_uri": "https://example-file-host/modelverse/demo-audio.mp3"
                            }
                          },
                          {
                            "text": "请转写这段音频，并总结其核心观点。"
                          }
                        ]
                      }
                    ]
                  }
                },
                "textFile": {
                  "summary": "文本文件分析",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "fileData": {
                              "mimeType": "text/plain",
                              "fileUri": "https://example-file-host/modelverse/demo.txt"
                            }
                          },
                          {
                            "text": "这个文本文件里写了什么内容？"
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "分析成功，返回 Gemini 内容生成响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiMediaGenerateContentResponse"
                },
                "examples": {
                  "success": {
                    "summary": "媒体分析结果",
                    "value": {
                      "candidates": [
                        {
                          "content": {
                            "role": "model",
                            "parts": [
                              {
                                "text": "画面中包含一台笔记本电脑和一杯咖啡，整体场景像是办公桌面。"
                              }
                            ]
                          },
                          "finishReason": "STOP"
                        }
                      ],
                      "usageMetadata": {
                        "promptTokenCount": 258,
                        "candidatesTokenCount": 32,
                        "totalTokenCount": 290
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误、媒体 MIME 类型不匹配、GCS URI 无效，或文件与所请求模型不兼容。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiMediaErrorResponse"
                },
                "examples": {
                  "gcsError": {
                    "value": {
                      "error": {
                        "message": "GCS file mimeType is required",
                        "type": "invalid_request_error",
                        "code": "param_error",
                        "param": "req_example"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "GCS 文件不存在、已过期或不属于当前公司和组织。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiMediaErrorResponse"
                },
                "examples": {
                  "gcsError": {
                    "value": {
                      "error": {
                        "message": "GCS file not found or expired",
                        "type": "not_found_error",
                        "code": "not_found",
                        "param": "req_example"
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "文件服务暂不可用，可稍后重试。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiMediaErrorResponse"
                },
                "examples": {
                  "gcsError": {
                    "value": {
                      "error": {
                        "message": "GCS file provider credentials unavailable",
                        "type": "internal_error",
                        "code": "affinity_unavailable",
                        "param": "req_example"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiMediaErrorResponse"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "python",
            "label": "Python：上传 PDF 并分析（pip install httpx google-genai）",
            "source": "import os\nfrom pathlib import Path\n\nimport httpx\nfrom google import genai\nfrom google.genai.types import HttpOptions, Part\n\nbase_url = os.environ.get(\"MODELVERSE_BASE_URL\", \"https://api.modelverse.cn\")\napi_key = os.environ[\"MODELVERSE_API_KEY\"]\nmodel = \"gemini-4-argon\"\nfile_path = Path(\"/path/to/document.pdf\")\n\nwith httpx.Client(timeout=600.0) as http:\n    with file_path.open(\"rb\") as media:\n        uploaded = http.post(\n            f\"{base_url}/v1/files\",\n            headers={\"Authorization\": f\"Bearer {api_key}\"},\n            data={\"purpose\": \"batch:gcs\", \"usage\": \"inference\", \"model\": model},\n            files={\"file\": (file_path.name, media, \"application/pdf\")},\n        )\n    uploaded.raise_for_status()\n    gcs_uri = uploaded.json()[\"gcs_uri\"]\n\nwith genai.Client(\n    api_key=api_key,\n    http_options=HttpOptions(api_version=\"v1beta\", base_url=base_url, timeout=600_000),\n) as client:\n    response = client.models.generate_content(\n        model=model,\n        contents=[\n            Part.from_uri(file_uri=gcs_uri, mime_type=\"application/pdf\"),\n            \"请概括这份 PDF 的主要内容，并列出关键章节。\",\n        ],\n    )\n    print(response.text)"
          }
        ]
      }
    },
    "/v1beta/cachedContents": {
      "post": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "createGeminiCachedContent",
        "summary": "Gemini 显式缓存",
        "description": "Gemini 显式缓存用于复用需要反复发送的大段上下文，例如产品手册、知识库、固定系统规则、图片、音频或视频。先把公共上下文创建为缓存，后续请求只发送 `cache_id` 和本次的新问题，可以减少重复传输与重复处理。\n\n创建请求中的 `systemInstruction`（可选的固定角色和回答规则，仅支持文本 Part）和 `contents`（需要反复使用的文本或媒体资料）作为同一个缓存整体保存，两者至少要有一个非空 Part。缓存内容创建后不可修改，也不支持手动删除，只能延长有效期（见「Gemini 延长缓存有效期」），到期自动失效并从查询结果中消失。\n\n## 支持模型与最低缓存 token 数\n\n| 模型 ID | 最低缓存 token 数 |\n| --- | ---: |\n| `gemini-2.5-flash` | 2,048 |\n| `gemini-3.5-flash-lite`、`gemini-3.5-flash`、`gemini-3.6-flash`、`gemini-3.1-pro-preview`、`gemini-3-flash-preview` | 4,096 |\n\n不在表中的 Gemini 模型即使能正常生成内容也不能创建显式缓存；缓存内容低于最低 token 数会创建失败。\n\n## 使用缓存\n\n创建成功后保存响应中的 `cache_id`（不要使用 Google 的 `projects/.../cachedContents/...` 资源名），再调用同一模型的 `generateContent` 或 `streamGenerateContent`，只发送 `cachedContent` 和本次新问题：\n\n```json\n{\n  \"cachedContent\": \"cache_abc123\",\n  \"contents\": [{ \"role\": \"user\", \"parts\": [{ \"text\": \"请根据缓存的产品手册总结主要功能。\" }] }]\n}\n```\n\n- 必须使用创建缓存时的同一个 API Key 和同一个模型，且缓存仍在有效期内；同公司的其他 API Key 不可见该缓存。\n- 不要再次传入 `systemInstruction`、`tools`、`toolConfig`；`generationConfig`、`safetySettings` 和本次独有的 `contents`（可包含新的 `inlineData` 图片）照常传。\n- 本次请求的新内容不会写回原缓存，需要复用时必须创建新缓存。\n- 命中缓存时，响应 `usageMetadata.cachedContentTokenCount` 为本次复用的缓存 token 数。\n\n## 有效期与计费\n\n- `ttl` 与 `expire_time` 只能传一个；都不传时默认约 60 分钟，实际过期时间以响应的 `expire_time` 为准。\n- `ttl` 最小 60 秒，创建或更新后的最终过期时间不能超过本次请求时间起 7 天。\n- 创建时缓存内全部 token 计一次输入费用，从 `created_at` 到 `expire_time` 期间产生存储费用；延长有效期只对新增的存储时段计费。\n- 使用缓存时缓存 token 按缓存读取计费，且不会自动刷新有效期；实际价格以 ModelVerse 计费说明为准。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeminiCacheCreateCachedContentRequest"
              },
              "examples": {
                "create": {
                  "summary": "创建产品手册缓存",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "product-manual",
                    "ttl": "3600s",
                    "systemInstruction": {
                      "parts": [
                        {
                          "text": "你是产品支持助手。优先依据缓存资料回答；资料中没有答案时明确说明，不要猜测。"
                        }
                      ]
                    },
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "text": "这里放入需要反复使用的完整产品手册、常见问题和处理流程……"
                          }
                        ]
                      }
                    ]
                  }
                },
                "textImage": {
                  "summary": "文本和图片",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "product-image-context",
                    "ttl": "3600s",
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "text": "这是产品控制台截图，蓝色区域表示可用额度，灰色区域表示已使用额度。"
                          },
                          {
                            "inlineData": {
                              "mimeType": "image/png",
                              "data": "<IMAGE_BASE64>",
                              "displayName": "console.png"
                            }
                          },
                          {
                            "text": "后续回答需要结合上述界面含义解释截图内容。"
                          }
                        ]
                      }
                    ]
                  }
                },
                "pdfText": {
                  "summary": "PDF 和文本说明",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "product-manual",
                    "ttl": "7200s",
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "inlineData": {
                              "mimeType": "application/pdf",
                              "data": "<PDF_BASE64>",
                              "displayName": "product-manual.pdf"
                            }
                          },
                          {
                            "text": "后续问题优先依据这份产品手册回答；手册没有相关信息时明确说明。"
                          }
                        ]
                      }
                    ]
                  }
                },
                "audioGlossary": {
                  "summary": "音频和背景词表",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "meeting-audio",
                    "ttl": "3600s",
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "text": "背景词表：ModelVerse 是产品名，UMInfer 是服务名，UCloud 是公司名。"
                          },
                          {
                            "inlineData": {
                              "mimeType": "audio/mpeg",
                              "data": "<AUDIO_BASE64>",
                              "displayName": "weekly-meeting.mp3"
                            }
                          },
                          {
                            "text": "后续生成摘要时保留以上专有名词的大小写。"
                          }
                        ]
                      }
                    ]
                  }
                },
                "fewShot": {
                  "summary": "系统规则、多轮文本和图片",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "inspection-examples",
                    "ttl": "3600s",
                    "systemInstruction": {
                      "parts": [
                        {
                          "text": "你是设备质检助手，必须按照“外观、接口、风险”三个部分输出。"
                        }
                      ]
                    },
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "text": "请检查这台样例设备。"
                          },
                          {
                            "inlineData": {
                              "mimeType": "image/jpeg",
                              "data": "<SAMPLE_IMAGE_BASE64>",
                              "displayName": "sample-device.jpg"
                            }
                          }
                        ]
                      },
                      {
                        "role": "model",
                        "parts": [
                          {
                            "text": "外观：外壳完整。接口：接口无遮挡。风险：未发现明显风险。"
                          }
                        ]
                      }
                    ]
                  }
                },
                "multiImage": {
                  "summary": "文本和多张图片",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "device-images",
                    "ttl": "3600s",
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "text": "第一张是设备正面："
                          },
                          {
                            "inlineData": {
                              "mimeType": "image/jpeg",
                              "data": "<FRONT_IMAGE_BASE64>",
                              "displayName": "device-front.jpg"
                            }
                          },
                          {
                            "text": "第二张是设备背面："
                          },
                          {
                            "inlineData": {
                              "mimeType": "image/jpeg",
                              "data": "<BACK_IMAGE_BASE64>",
                              "displayName": "device-back.jpg"
                            }
                          }
                        ]
                      }
                    ]
                  }
                },
                "videoRequirement": {
                  "summary": "视频和分析要求",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "console-demo-video",
                    "ttl": "3600s",
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "inlineData": {
                              "mimeType": "video/mp4",
                              "data": "<VIDEO_BASE64>",
                              "displayName": "console-demo.mp4"
                            }
                          },
                          {
                            "text": "这是控制台操作录屏。后续回答需要区分页面跳转、用户输入和系统返回结果。"
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功，返回 ModelVerse 缓存 ID。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheCachedContent"
                },
                "examples": {
                  "success": {
                    "summary": "创建成功",
                    "value": {
                      "cache_id": "cache_abc123",
                      "model": "gemini-2.5-flash",
                      "display_name": "product-manual",
                      "status": "active",
                      "created_at": "2026-07-24T02:00:00Z",
                      "updated_at": "2026-07-24T02:00:00Z",
                      "expire_time": "2026-07-24T03:00:00Z",
                      "total_token_count": 11426
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效，例如缓存内容过短、`ttl` 与 `expire_time` 同时传入、模型不支持显式缓存。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheErrorResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "listGeminiCachedContents",
        "summary": "Gemini 查询缓存列表",
        "description": "查询当前 API Key 下仍有效的 Gemini 显式缓存。缓存的创建与使用见「Gemini 显式缓存」。\n\n- 只返回当前 API Key 创建、尚未过期且状态为 `active` 的缓存，同公司下的其他 API Key 不可见。\n- 每个 `cache_id` 只返回最新的成功状态，按创建时间倒序排列。\n- 没有有效缓存时返回 `{\"cachedContents\":[]}`。\n- 创建和更新响应的时间字段为 `created_at`、`updated_at`、`expire_time`；本接口沿用 Gemini 列表结构，时间字段为 `createTime`、`updateTime`、`expireTime`。",
        "responses": {
          "200": {
            "description": "缓存列表。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheListCachedContentsResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "cachedContents": [
                        {
                          "cache_id": "cache_abc123",
                          "model": "gemini-2.5-flash",
                          "status": "active",
                          "display_name": "product-manual",
                          "createTime": "2026-07-24T02:00:00Z",
                          "updateTime": "2026-07-24T02:00:00Z",
                          "expireTime": "2026-07-24T03:00:00Z",
                          "total_token_count": 11426
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1beta/cachedContents/{cache_id}": {
      "patch": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "updateGeminiCachedContent",
        "summary": "Gemini 延长缓存有效期",
        "description": "延长 Gemini 显式缓存的有效期，不修改缓存内容和模型。请求体必须且只能包含 `ttl` 或 `expire_time` 之一，缓存的创建与使用见「Gemini 显式缓存」。\n\n- `ttl` 叠加在**当前过期时间**上，而不是从请求时间重新计算：当前过期时间为 `10:30:00Z` 时，`{\"ttl\":\"600s\"}` 之后的新过期时间为 `10:40:00Z`。\n- `expire_time` 必须晚于当前过期时间、比请求时间至少晚 60 秒；无需查询或回传旧的过期时间，服务端会读取并校验缓存当前状态。\n- 最终过期时间不能超过本次请求时间起 7 天，因此可延长的时长受剩余有效期影响。\n- 响应中 `old_expire_time` 为更新前的过期时间，`expire_time` 为更新后实际生效的过期时间。",
        "parameters": [
          {
            "name": "cache_id",
            "in": "path",
            "required": true,
            "description": "创建缓存返回的 ModelVerse 缓存 ID。",
            "schema": {
              "type": "string",
              "example": "cache_abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeminiCacheUpdateCachedContentRequest"
              },
              "examples": {
                "ttl": {
                  "summary": "使用相对 TTL 延长",
                  "value": {
                    "ttl": "600s"
                  }
                },
                "expireTime": {
                  "summary": "使用绝对时间延长",
                  "value": {
                    "expire_time": "2026-07-24T12:00:00Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "更新成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheCachedContent"
                },
                "examples": {
                  "success": {
                    "value": {
                      "cache_id": "cache_abc123",
                      "model": "gemini-2.5-flash",
                      "display_name": "product-manual",
                      "status": "active",
                      "created_at": "2026-07-24T02:00:00Z",
                      "updated_at": "2026-07-24T02:10:00Z",
                      "old_expire_time": "2026-07-24T03:00:00Z",
                      "expire_time": "2026-07-24T03:10:00Z"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1beta/models/{modelsId}:embedContent": {
      "post": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "embedGeminiContent",
        "summary": "Gemini Embedding 2 向量嵌入",
        "description": "Gemini Embedding 2（`gemini-embedding-2`）是 Google 的多模态嵌入模型，可将文本、图片、视频、音频和 PDF 转换为高维向量，用于多模态语义搜索、内容推荐、聚类分析和异常检测。单个请求可以混合多种模态；只需要纯文本嵌入时也可以使用 OpenAI 兼容的 `POST /v1/embeddings`。\n\n`content.parts[]` 既支持文本 Part `{\"text\":\"...\"}`，也支持文件 Part `{\"file_data\":{\"mime_type\":\"...\",\"file_uri\":\"...\"}}`，文件需通过服务端可访问的地址提供。响应返回 `embedding.values` 向量和 `usageMetadata` 分模态 token 用量。\n\n## 输出维度\n\n`outputDimensionality` 支持 128 至 3072，默认 3072。降到 768 或 1536 可减少存储和计算成本，语义搜索精度略有下降但多数场景可忽略；追求最高精度时保持默认值。\n\n## 单请求限制\n\n| 模态 | 数量上限 | 其他限制 | 支持的 MIME |\n| --- | --- | --- | --- |\n| 图片 | 6 | — | `image/png`、`image/jpeg`、`image/webp`、`image/bmp`、`image/heic`、`image/heif`、`image/avif` |\n| 文档 | 1 | 最多 6 页 | `application/pdf` |\n| 视频 | 1 | 含音频最长 80 秒，不含音频最长 120 秒 | `video/mp4`、`video/mpeg` |\n| 音频 | 1 | 最长 180 秒 | `audio/mp3`、`audio/wav` |",
        "parameters": [
          {
            "name": "modelsId",
            "in": "path",
            "required": true,
            "description": "固定使用 `gemini-embedding-2`。",
            "schema": {
              "type": "string",
              "example": "gemini-embedding-2"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeminiEmbeddingEmbedContentRequest"
              },
              "examples": {
                "multimodal": {
                  "summary": "多模态嵌入",
                  "value": {
                    "content": {
                      "parts": [
                        {
                          "text": "这是什么？"
                        },
                        {
                          "text": "这个和什么类似？"
                        },
                        {
                          "file_data": {
                            "mime_type": "video/mp4",
                            "file_uri": "https://example.com/video.mp4"
                          }
                        },
                        {
                          "file_data": {
                            "mime_type": "image/png",
                            "file_uri": "https://example.com/image.png"
                          }
                        },
                        {
                          "file_data": {
                            "mime_type": "audio/wav",
                            "file_uri": "https://example.com/audio.wav"
                          }
                        },
                        {
                          "file_data": {
                            "mime_type": "application/pdf",
                            "file_uri": "https://example.com/document.pdf"
                          }
                        }
                      ]
                    }
                  }
                },
                "outputDimensionality": {
                  "summary": "指定输出维度",
                  "value": {
                    "outputDimensionality": 768,
                    "content": {
                      "parts": [
                        {
                          "text": "查找关于机器学习的视频教程"
                        },
                        {
                          "file_data": {
                            "mime_type": "image/png",
                            "file_uri": "https://example.com/ml-diagram.png"
                          }
                        }
                      ]
                    }
                  }
                },
                "semanticSearch": {
                  "summary": "多模态语义搜索",
                  "value": {
                    "content": {
                      "parts": [
                        {
                          "text": "查找关于机器学习的视频教程"
                        },
                        {
                          "file_data": {
                            "mime_type": "image/png",
                            "file_uri": "https://example.com/ml-diagram.png"
                          }
                        }
                      ]
                    }
                  }
                },
                "videoOnly": {
                  "summary": "视频内容嵌入",
                  "value": {
                    "content": {
                      "parts": [
                        {
                          "file_data": {
                            "mime_type": "video/mp4",
                            "file_uri": "https://example.com/tutorial.mp4"
                          }
                        }
                      ]
                    }
                  }
                },
                "pdf": {
                  "summary": "PDF 文档嵌入",
                  "value": {
                    "content": {
                      "parts": [
                        {
                          "text": "总结这份报告的关键点"
                        },
                        {
                          "file_data": {
                            "mime_type": "application/pdf",
                            "file_uri": "https://example.com/report.pdf"
                          }
                        }
                      ]
                    }
                  }
                },
                "audio": {
                  "summary": "音频内容嵌入",
                  "value": {
                    "content": {
                      "parts": [
                        {
                          "file_data": {
                            "mime_type": "audio/wav",
                            "file_uri": "https://example.com/speech.wav"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "嵌入向量和用量信息。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiEmbeddingEmbedContentResponse"
                },
                "examples": {
                  "success": {
                    "summary": "嵌入响应",
                    "value": {
                      "embedding": {
                        "values": [
                          0.0015015427,
                          0.014678672,
                          -0.018105509,
                          -0.013457718,
                          0.015227248,
                          0.003112343
                        ]
                      },
                      "usageMetadata": {
                        "promptTokenCount": 2517,
                        "totalTokenCount": 2517,
                        "promptTokensDetails": [
                          {
                            "modality": "VIDEO",
                            "tokenCount": 330
                          },
                          {
                            "modality": "TEXT",
                            "tokenCount": 5
                          },
                          {
                            "modality": "DOCUMENT",
                            "tokenCount": 1548
                          },
                          {
                            "modality": "IMAGE",
                            "tokenCount": 258
                          },
                          {
                            "modality": "AUDIO",
                            "tokenCount": 376
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效，例如 `outputDimensionality` 超出范围、文件 URI 不可访问或 MIME 类型不匹配。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiEmbeddingErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiEmbeddingErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/files": {
      "post": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "uploadGeminiBatchGcsFile",
        "summary": "Gemini 上传批量输入文件",
        "description": "上传 Gemini 批量任务输入文件。`purpose` 固定为 `batch:gcs`，文件为 JSONL。上传返回的 `id` 是 GCS 对象名，创建任务时需拼成完整 GCS URI，例如 `gs://gemini-batch-001/<上传返回的id>`。",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/GeminiBatchUploadGeminiBatchFileRequest"
              },
              "examples": {
                "default": {
                  "summary": "上传 JSONL 文件",
                  "value": {
                    "purpose": "batch:gcs",
                    "file": "/path/to/your-input.jsonl"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "上传成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchFileObject"
                },
                "examples": {
                  "success": {
                    "value": {
                      "id": "1773236148797418904_gemini-3.1-pro-preview.jsonl",
                      "object": "file",
                      "bytes": 224,
                      "created_at": 1773236150,
                      "expires_at": 0,
                      "filename": "1773236148797418904_gemini-3.1-pro-preview.jsonl",
                      "purpose": "batch:gcs"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1beta/batchPredictionJobs": {
      "post": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "createGeminiBatchPredictionJob",
        "summary": "Gemini 批量任务",
        "description": "创建 Gemini（Vertex 风格）批量预测任务，适用于大批量异步文本生成。`model` 须使用 batch 模型名称；支持的 batch 模型可以在星图模型广场查看。\n\n完整流程分四步，每步对应一个接口：\n\n1. **上传输入文件**（`POST /v1/files`，见「Gemini 上传批量输入文件」）：上传 JSONL，`purpose` 固定 `batch:gcs`，记下响应中的 `id`。\n2. **创建批量任务**（本接口）：`inputConfig.gcsSource.uris` 传上一步 `id` 拼成的完整 GCS URI `gs://gemini-batch-001/<id>`，只支持单个字符串（不是数组）；`outputConfig.gcsDestination.outputUriPrefix` 必须为 `gs://gemini-batch-001/output`。Bucket `gemini-batch-001` 由平台分配。\n3. **查询任务状态**（`GET /v1beta/batchPredictionJobs/{job_id}`，见「Gemini 查询批量任务状态」）：`job_id` 取创建响应 `name` 的最后一段，轮询到 `JOB_STATE_SUCCEEDED` 或失败为止。\n4. **下载结果**（`GET /v1/batchPredictionJobs/content`，见「Gemini 下载批量任务结果」）：`file_id` 传任务查询响应中的 `outputInfo.gcsOutputDirectory`（输出目录，不是单个文件），服务会返回该目录下的 `predictions.jsonl`。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeminiBatchCreateBatchPredictionJobRequest"
              },
              "examples": {
                "default": {
                  "summary": "创建 Gemini 批量预测任务",
                  "value": {
                    "displayName": "my-cloud-storage-batch-inference-job",
                    "model": "publishers/google/models/gemini-3.1-pro-preview",
                    "inputConfig": {
                      "instancesFormat": "jsonl",
                      "gcsSource": {
                        "uris": "gs://gemini-batch-001/1773236148797418904_gemini-3.1-pro-preview.jsonl"
                      }
                    },
                    "outputConfig": {
                      "predictionsFormat": "jsonl",
                      "gcsDestination": {
                        "outputUriPrefix": "gs://gemini-batch-001/output"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功，返回 Vertex 风格任务对象。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchBatchPredictionJob"
                },
                "examples": {
                  "success": {
                    "value": {
                      "name": "projects/279887244472/locations/global/batchPredictionJobs/7737084104264384512",
                      "displayName": "my-cloud-storage-batch-inference-job",
                      "model": "publishers/google/models/gemini-3.1-pro-preview",
                      "inputConfig": {
                        "instancesFormat": "jsonl",
                        "gcsSource": {
                          "uris": [
                            "gs://gvideo.modelverse.cn/batch_prompt_for_batch_gemini_predict.jsonl"
                          ]
                        }
                      },
                      "outputConfig": {
                        "predictionsFormat": "jsonl",
                        "gcsDestination": {
                          "outputUriPrefix": "gs://gvideo.modelverse.cn/test"
                        }
                      },
                      "outputInfo": {
                        "gcsOutputDirectory": "gs://gvideo.modelverse.cn/test/prediction-model-2026-02-28T08:22:20.427871Z"
                      },
                      "state": "JOB_STATE_SUCCEEDED",
                      "completionStats": {
                        "successfulCount": "2"
                      },
                      "createTime": "2026-02-28T08:22:22.313780Z",
                      "startTime": "2026-02-28T08:23:12.172401Z",
                      "endTime": "2026-02-28T08:27:35.914509Z",
                      "updateTime": "2026-02-28T08:27:35.914509Z",
                      "modelVersionId": "1"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效，例如 GCS URI 格式错误、输入输出格式不支持或模型不可用。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1beta/batchPredictionJobs/{job_id}": {
      "get": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "getGeminiBatchPredictionJob",
        "summary": "Gemini 查询批量任务状态",
        "description": "根据创建任务后得到的 `job_id` 查询 Gemini 批量任务状态。`job_id` 通常是创建响应 `name` 的最后一段。任务完成后，从 `outputInfo.gcsOutputDirectory` 取输出目录用于下载结果。",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "description": "任务 ID，即创建任务响应 `name` 中最后一段。",
            "schema": {
              "type": "string",
              "example": "7737084104264384512"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "任务详情。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchBatchPredictionJob"
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/batchPredictionJobs/content": {
      "get": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "downloadGeminiBatchPredictionJobContent",
        "summary": "Gemini 下载批量任务结果",
        "description": "下载已完成 Gemini 批量任务的 `predictions.jsonl`。`file_id` 必须传任务查询响应中的输出目录 `outputInfo.gcsOutputDirectory`，不是单个文件名；服务会在该目录下定位并返回结果文件。",
        "parameters": [
          {
            "name": "file_id",
            "in": "query",
            "required": true,
            "description": "任务输出目录，例如 `gs://gemini-batch-001/output/prediction-model-...`。",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "`predictions.jsonl` 文件内容。",
            "content": {
              "application/jsonl": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "xGoogApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-goog-api-key",
        "description": "Gemini 兼容 API Key 请求头。"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key"
      }
    },
    "schemas": {
      "GeminiMediaGenerateContentRequest": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "contents"
        ],
        "properties": {
          "contents": {
            "type": "array",
            "minItems": 1,
            "description": "对话内容列表。媒体分析时通常传入一个 user 消息，包含媒体 Part 和文本问题。",
            "items": {
              "$ref": "#/components/schemas/GeminiMediaContent"
            }
          }
        }
      },
      "GeminiMediaContent": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "role": {
            "type": "string",
            "description": "消息角色。媒体分析通常只传一条 `user` 消息。",
            "enum": [
              "user",
              "model"
            ]
          },
          "parts": {
            "type": "array",
            "description": "消息部件数组，可同时包含媒体 Part 和文本问题。",
            "items": {
              "$ref": "#/components/schemas/GeminiMediaPart"
            }
          }
        }
      },
      "GeminiMediaPart": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "text": {
            "type": "string",
            "description": "问题或指令文本。"
          },
          "file_data": {
            "$ref": "#/components/schemas/GeminiMediaFileData"
          },
          "fileData": {
            "$ref": "#/components/schemas/GeminiMediaFileDataCamel"
          }
        }
      },
      "GeminiMediaFileData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "mime_type",
          "file_uri"
        ],
        "description": "媒体文件（snake_case 写法）。与 `fileData` 等价，同一个 Part 只使用其中一种。",
        "properties": {
          "mime_type": {
            "type": "string",
            "description": "媒体 MIME 类型，必须与实际文件格式一致。",
            "examples": [
              "image/jpeg",
              "video/mp4",
              "audio/mpeg",
              "application/pdf"
            ]
          },
          "file_uri": {
            "type": "string",
            "format": "uri",
            "description": "媒体文件地址。支持上传响应中的 `gcs_uri`（gs://，推荐大文件）或 `s3_url`（HTTPS），也支持服务端可访问的公网 URL。GCS 文件须属于当前公司、组织且未过期；直接使用返回值，不要自行拼接。"
          }
        }
      },
      "GeminiMediaFileDataCamel": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "mimeType",
          "fileUri"
        ],
        "description": "媒体文件（camelCase 写法）。与 `file_data` 等价，同一个 Part 只使用其中一种。",
        "properties": {
          "mimeType": {
            "type": "string",
            "description": "媒体 MIME 类型，必须与实际文件格式一致。"
          },
          "fileUri": {
            "type": "string",
            "format": "uri",
            "description": "媒体文件地址。支持上传响应中的 `gcs_uri`（gs://，推荐大文件）或 `s3_url`（HTTPS），也支持服务端可访问的公网 URL。GCS 文件须属于当前公司、组织且未过期；直接使用返回值，不要自行拼接。"
          }
        }
      },
      "GeminiMediaGenerateContentResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "candidates": {
            "type": "array",
            "description": "生成结果列表，文本分析结果在 `candidates[].content.parts[].text`。",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "usageMetadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "token 用量，包含 `promptTokenCount`、`candidatesTokenCount`、`totalTokenCount`。"
          }
        }
      },
      "GeminiMediaErrorResponse": {
        "$ref": "#/components/schemas/ModelVerseErrorResponse"
      },
      "GeminiCacheCreateCachedContentRequest": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "model"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "支持显式缓存的 Gemini 模型 ID。创建缓存和使用缓存时必须保持一致。",
            "examples": [
              "gemini-2.5-flash",
              "gemini-3-flash-preview"
            ]
          },
          "contents": {
            "type": "array",
            "description": "需要缓存的实际资料，支持 `text` 和 `inlineData` Part。",
            "items": {
              "$ref": "#/components/schemas/GeminiCacheContent"
            }
          },
          "systemInstruction": {
            "$ref": "#/components/schemas/GeminiCacheSystemInstruction"
          },
          "displayName": {
            "type": "string",
            "description": "便于识别缓存的展示名称。"
          },
          "ttl": {
            "description": "相对有效期，推荐使用字符串，例如 `3600s`。也兼容 seconds/nanos 对象。",
            "oneOf": [
              {
                "type": "string",
                "title": "string"
              },
              {
                "type": "object",
                "additionalProperties": true,
                "title": "object"
              }
            ]
          },
          "expire_time": {
            "type": "string",
            "format": "date-time",
            "description": "绝对过期时间，使用 RFC 3339 格式。"
          }
        },
        "description": "创建缓存请求。支持字段命名兼容：`displayName/display_name`、`systemInstruction/system_instruction`、`inlineData/inline_data`、`mimeType/mime_type`、`cachedContent/cached_content`、`expireTime/expire_time`。同一字段不要同时传入两种写法。"
      },
      "GeminiCacheUpdateCachedContentRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "延长有效期请求。必须且只能包含 `ttl` 或 `expire_time` 之一。",
        "properties": {
          "ttl": {
            "description": "在当前过期时间上继续增加的时长，推荐字符串如 `600s`，也兼容 seconds/nanos 对象。最小 60 秒。",
            "oneOf": [
              {
                "type": "string",
                "title": "string"
              },
              {
                "type": "object",
                "additionalProperties": true,
                "title": "object"
              }
            ]
          },
          "expire_time": {
            "type": "string",
            "format": "date-time",
            "description": "新的绝对过期时间，RFC 3339 格式。必须晚于当前过期时间，比请求时间至少晚 60 秒，且不超过 7 天。"
          }
        },
        "minProperties": 1,
        "maxProperties": 1
      },
      "GeminiCacheSystemInstruction": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "parts": {
            "type": "array",
            "description": "一起缓存的固定角色和回答规则，只支持文本 Part。",
            "items": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "text": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "GeminiCacheContent": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "role": {
            "type": "string",
            "description": "消息角色。Few-shot 示例可用 `model` 角色给出示范回答。",
            "enum": [
              "user",
              "model"
            ]
          },
          "parts": {
            "type": "array",
            "description": "需要缓存的部件数组，可混合 `text` 和 `inlineData`。",
            "items": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "text": {
                  "type": "string",
                  "description": "文本内容。"
                },
                "inlineData": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "Base64 编码的 Blob。所有 `inlineData` 解码后的二进制内容合计不能超过 10 MiB。",
                  "required": [
                    "mimeType",
                    "data"
                  ],
                  "properties": {
                    "mimeType": {
                      "type": "string",
                      "description": "文件的标准 MIME 类型，必须与实际内容一致。",
                      "examples": [
                        "image/png",
                        "application/pdf",
                        "audio/mpeg",
                        "video/mp4"
                      ]
                    },
                    "data": {
                      "type": "string",
                      "description": "文件内容的 Base64 字符串（例如 `base64 -w 0 product-manual.pdf`），不要加 `data:application/pdf;base64,` 之类的 Data URL 前缀。"
                    },
                    "displayName": {
                      "type": "string",
                      "description": "便于模型和调用方识别文件的名称。"
                    }
                  }
                }
              }
            }
          }
        },
        "description": "缓存内容消息。同一个 `parts` 数组可以混合多个文本和 Blob，但每个 Part 只能是 `text` 或 `inlineData` 其中一种；`systemInstruction.parts[]` 只支持文本，媒体必须放在 `contents[].parts[].inlineData`。缓存接口不支持 `fileData`、Cloud Storage URI 和本地文件路径。\n\n常见 MIME 包括 `image/png`、`image/jpeg`、`image/webp`、`image/heic`、`application/pdf`、`text/plain`、`audio/mpeg`、`audio/wav`、`audio/flac`、`video/mp4`、`video/webm`、`video/quicktime` 等，实际支持取决于所选模型的多模态能力，切换模型时需重新确认。"
      },
      "GeminiCacheCachedContent": {
        "type": "object",
        "additionalProperties": true,
        "description": "缓存对象。创建和更新响应使用 `created_at`、`updated_at`、`expire_time`；查询缓存列表沿用 Gemini 列表结构，使用 `createTime`、`updateTime`、`expireTime`。",
        "properties": {
          "cache_id": {
            "type": "string",
            "description": "ModelVerse 缓存 ID，后续使用、更新时都传这个值。"
          },
          "model": {
            "type": "string",
            "description": "创建缓存使用的 ModelVerse 模型 ID。"
          },
          "display_name": {
            "type": "string",
            "description": "创建时提供的展示名称；未提供则不返回。"
          },
          "status": {
            "type": "string",
            "description": "缓存状态，有效缓存为 `active`。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "缓存创建时间（创建、更新响应）。"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "最近一次更新时间（创建、更新响应）。"
          },
          "old_expire_time": {
            "type": "string",
            "format": "date-time",
            "description": "更新前的过期时间，仅延长有效期的响应返回。"
          },
          "expire_time": {
            "type": "string",
            "format": "date-time",
            "description": "上游实际生效的过期时间。"
          },
          "createTime": {
            "type": "string",
            "format": "date-time",
            "description": "缓存创建时间（查询缓存列表响应）。"
          },
          "updateTime": {
            "type": "string",
            "format": "date-time",
            "description": "最近一次更新时间（查询缓存列表响应）。"
          },
          "expireTime": {
            "type": "string",
            "format": "date-time",
            "description": "上游实际生效的过期时间（查询缓存列表响应）。"
          },
          "total_token_count": {
            "type": "integer",
            "description": "整个缓存的 token 数，含 `systemInstruction` 和 `contents`。"
          }
        }
      },
      "GeminiCacheListCachedContentsResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "cachedContents": {
            "type": "array",
            "description": "仍然有效的缓存列表，没有有效缓存时为空数组。",
            "items": {
              "$ref": "#/components/schemas/GeminiCacheCachedContent"
            }
          }
        }
      },
      "GeminiCacheErrorResponse": {
        "$ref": "#/components/schemas/ModelVerseErrorResponse"
      },
      "GeminiEmbeddingEmbedContentRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "content"
        ],
        "properties": {
          "content": {
            "$ref": "#/components/schemas/GeminiEmbeddingContent"
          },
          "outputDimensionality": {
            "type": "integer",
            "minimum": 128,
            "maximum": 3072,
            "default": 3072,
            "description": "输出嵌入向量维度。较低维度可减少存储和计算成本。"
          }
        }
      },
      "GeminiEmbeddingContent": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "parts"
        ],
        "properties": {
          "parts": {
            "type": "array",
            "minItems": 1,
            "description": "内容部件数组，支持文本和多模态文件。",
            "items": {
              "$ref": "#/components/schemas/GeminiEmbeddingPart"
            }
          }
        }
      },
      "GeminiEmbeddingPart": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "text": {
            "type": "string",
            "description": "要嵌入的文本内容。"
          },
          "file_data": {
            "$ref": "#/components/schemas/GeminiEmbeddingFileData"
          }
        }
      },
      "GeminiEmbeddingFileData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "mime_type",
          "file_uri"
        ],
        "properties": {
          "mime_type": {
            "type": "string",
            "description": "文件 MIME 类型，例如 `video/mp4`、`image/png`、`audio/wav` 或 `application/pdf`。"
          },
          "file_uri": {
            "type": "string",
            "format": "uri",
            "description": "可被服务端访问的文件地址。"
          }
        },
        "description": "文件 Part。常见类型：图片 image/png、image/jpeg、image/webp；视频 video/mp4、video/mpeg；音频 audio/wav、audio/mp3、audio/mpeg；文档 application/pdf。文件 URI 需要服务端可访问。"
      },
      "GeminiEmbeddingEmbedContentResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "embedding": {
            "type": "object",
            "additionalProperties": true,
            "description": "嵌入结果。",
            "properties": {
              "values": {
                "type": "array",
                "description": "嵌入向量，浮点数列表。",
                "items": {
                  "type": "number"
                }
              }
            }
          },
          "usageMetadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "token 用量。",
            "properties": {
              "promptTokenCount": {
                "type": "integer",
                "description": "输入的总 token 数。"
              },
              "totalTokenCount": {
                "type": "integer",
                "description": "总 token 数。"
              },
              "promptTokensDetails": {
                "type": "array",
                "description": "各模态的 token 用量明细。",
                "items": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "modality": {
                      "type": "string",
                      "description": "模态类型。",
                      "enum": [
                        "TEXT",
                        "IMAGE",
                        "VIDEO",
                        "AUDIO",
                        "DOCUMENT"
                      ]
                    },
                    "tokenCount": {
                      "type": "integer",
                      "description": "该模态的 token 数。"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "GeminiEmbeddingErrorResponse": {
        "$ref": "#/components/schemas/ModelVerseErrorResponse"
      },
      "GeminiBatchUploadGeminiBatchFileRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "purpose",
          "file"
        ],
        "properties": {
          "purpose": {
            "type": "string",
            "const": "batch:gcs",
            "description": "Gemini 批量任务输入文件固定为 `batch:gcs`。"
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "JSONL 输入文件。"
          }
        }
      },
      "GeminiBatchFileObject": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": {
            "type": "string",
            "description": "文件在存储中的对象名。创建任务时需拼成完整 GCS URI `gs://gemini-batch-001/<id>`。"
          },
          "object": {
            "type": "string",
            "const": "file",
            "description": "固定为 `file`。"
          },
          "bytes": {
            "type": "integer",
            "format": "int64",
            "description": "文件大小（字节）。"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "创建时间戳。"
          },
          "filename": {
            "type": "string",
            "description": "文件名。"
          },
          "purpose": {
            "type": "string",
            "description": "与请求一致，固定为 `batch:gcs`。"
          }
        }
      },
      "GeminiBatchCreateBatchPredictionJobRequest": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "model",
          "inputConfig",
          "outputConfig"
        ],
        "properties": {
          "displayName": {
            "type": "string",
            "description": "任务展示名称。"
          },
          "model": {
            "type": "string",
            "description": "须使用 batch 模型名称；支持的 batch 模型可以在星图模型广场查看。",
            "examples": [
              "publishers/google/models/gemini-3.1-pro-preview",
              "publishers/google/models/gemini-3-flash-preview"
            ]
          },
          "inputConfig": {
            "type": "object",
            "additionalProperties": true,
            "description": "输入配置。",
            "required": [
              "instancesFormat",
              "gcsSource"
            ],
            "properties": {
              "instancesFormat": {
                "type": "string",
                "examples": [
                  "jsonl"
                ]
              },
              "gcsSource": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "uris": {
                    "oneOf": [
                      {
                        "type": "string",
                        "title": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "title": "array"
                      }
                    ],
                    "description": "输入文件的完整 GCS URI，只支持单个字符串形式，格式为 `gs://gemini-batch-001/<上传返回的 id>`。"
                  }
                }
              }
            }
          },
          "outputConfig": {
            "type": "object",
            "additionalProperties": true,
            "description": "输出配置。",
            "required": [
              "predictionsFormat",
              "gcsDestination"
            ],
            "properties": {
              "predictionsFormat": {
                "type": "string",
                "examples": [
                  "jsonl"
                ]
              },
              "gcsDestination": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "outputUriPrefix": {
                    "type": "string",
                    "description": "输出目录前缀，必须为 `gs://gemini-batch-001/output`。"
                  }
                }
              }
            }
          }
        }
      },
      "GeminiBatchBatchPredictionJob": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "name": {
            "type": "string",
            "description": "任务资源名或短 ID。"
          },
          "state": {
            "type": "string",
            "description": "任务状态。`JOB_STATE_PENDING` 已创建等待调度，`JOB_STATE_RUNNING` 进行中，`JOB_STATE_SUCCEEDED` 成功完成，`JOB_STATE_FAILED` 失败，`JOB_STATE_CANCELLED` 已取消，`JOB_STATE_PAUSED` 已暂停。",
            "enum": [
              "JOB_STATE_PENDING",
              "JOB_STATE_RUNNING",
              "JOB_STATE_SUCCEEDED",
              "JOB_STATE_FAILED",
              "JOB_STATE_CANCELLED",
              "JOB_STATE_PAUSED"
            ]
          },
          "outputInfo": {
            "type": "object",
            "additionalProperties": true,
            "description": "输出信息，任务完成后可用。",
            "properties": {
              "gcsOutputDirectory": {
                "type": "string",
                "description": "输出目录，用于下载结果时作为 `file_id`。"
              }
            }
          },
          "completionStats": {
            "type": "object",
            "additionalProperties": true,
            "description": "完成统计，例如 `successfulCount`。"
          }
        }
      },
      "GeminiBatchErrorResponse": {
        "$ref": "#/components/schemas/ModelVerseErrorResponse"
      },
      "ModelVerseErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "description": "错误响应。`error.message` 为错误描述，`error.code` 为错误码，`error.param` 通常为便于排查的请求标识。",
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": true,
            "description": "错误详情。"
          }
        }
      }
    }
  }
}
```
