{ "apiVersion": "yingce.plugin/v2", "id": "google-gemini-image", "name": "Google Gemini Image", "version": "2.0.0", "author": "Google / 影策", "description": "Google Gemini Image 独立请求协议插件。", "documentation": "# Google Gemini Image\n\n该目录是独立官方协议插件源码。后端从生成的 `google-gemini-image.yingce-plugin` 包加载，不依赖系统内置 `host:` 适配器。\n\n完整接口见 [docs/interface.md](docs/interface.md)。\n\n---\n\n# Google Gemini Image 接口字段\n\n## 协议身份\n\n- 插件 ID：`google-gemini-image`。\n- Provider ID：`gemini-image`。\n- 能力：`image`。\n- 默认 Base URL：`https://generativelanguage.googleapis.com`。\n- 鉴权驱动：`google-api-key`。\n- 创建：`POST /v1beta/models/{{model}}:generateContent`。\n- 生命周期：同步响应。\n\n## 配置字段\n\n| 字段 | 类型 | 必填 | 含义 |\n| --- | --- | --- | --- |\n| `apiKey` | secret | 是 | API Key |\n\n## 统一字段映射\n\n| 统一字段 | 类型 | 必填 | 上游映射 | 说明 |\n| --- | --- | --- | --- | --- |\n| `model` | string | 是 | `model` | 图片模型 ID。 |\n| `prompt` | string | 是 | `prompt` | 图片提示词。 |\n| `images` | media[] | 否 | `provider image/reference fields` | 参考图或编辑源图，role 由业务层确定。 |\n| `imageCount` | integer | 否 | `n/sample_count` | 输出数量。 |\n| `aspectRatio` | string | 否 | `size/aspect_ratio` | 比例或尺寸，语义按协议说明。 |\n| `resolution` | string | 否 | `resolution/imageSize` | 分辨率档位。 |\n| `quality` | string | 否 | `quality` | 质量档位。 |\n| `providerOptions` | object | 否 | `provider-specific fields` | 插件命名空间内的厂商扩展字段。 |\n\n## 上游请求模板逐字段清单\n\n下表由插件请求模板生成，覆盖 body、query、headers 和 multipart 文件声明中的每个字段。\n\n| 上游位置 | 值或转换表达式 |\n| --- | --- |\n| `create.method` | `\"POST\"` |\n| `create.path` | `\"/v1beta/models/{{model}}:generateContent\"` |\n| `create.contentType` | `\"application/json\"` |\n| `create.body.contents[0].role` | `\"user\"` |\n| `create.body.contents[0].parts` | `{\"$concatArrays\":[[{\"text\":{\"$ref\":\"request.prompt\"}}],{\"$map\":{\"from\":{\"$ref\":\"request.images\"},\"as\":\"media\",\"in\":{\"$if\":{\"condition\":{\"$ref\":\"media.dataUrl\"},\"then\":{\"inlineData\":{\"mimeType\":{\"$dataMime\":{\"$ref\":\"media.dataUrl\"}},\"data\":{\"$dataPayload\":{\"$ref\":\"media.dataUrl\"}}}},\"else\":{\"fileData\":{\"mimeType\":{\"$omitEmpty\":{\"$ref\":\"media.mimeType\"}},\"fileUri\":{\"$ref\":\"media.url\"}}}}}}}]}` |\n| `create.body.generationConfig.responseModalities` | `{\"$coalesce\":[{\"$ref\":\"request.providerOptions.gemini-image.responseModalities\"},[\"TEXT\",\"IMAGE\"]]}` |\n| `create.body.generationConfig.imageConfig.aspectRatio` | `{\"$omitEmpty\":{\"$ref\":\"request.aspectRatio\"}}` |\n| `create.body.generationConfig.imageConfig.imageSize` | `{\"$omitEmpty\":{\"$coalesce\":[{\"$switch\":{\"cases\":[{\"when\":{\"$in\":[{\"$lower\":{\"$ref\":\"request.quality\"}},[\"1k\",\"low\"]]},\"then\":\"1K\"},{\"when\":{\"$in\":[{\"$lower\":{\"$ref\":\"request.quality\"}},[\"2k\",\"medium\"]]},\"then\":\"2K\"},{\"when\":{\"$in\":[{\"$lower\":{\"$ref\":\"request.quality\"}},[\"4k\",\"high\"]]},\"then\":\"4K\"}],\"default\":null}},{\"$switch\":{\"cases\":[{\"when\":{\"$in\":[{\"$lower\":{\"$ref\":\"request.resolution\"}},[\"1k\",\"low\"]]},\"then\":\"1K\"},{\"when\":{\"$in\":[{\"$lower\":{\"$ref\":\"request.resolution\"}},[\"2k\",\"medium\"]]},\"then\":\"2K\"},{\"when\":{\"$in\":[{\"$lower\":{\"$ref\":\"request.resolution\"}},[\"4k\",\"high\"]]},\"then\":\"4K\"}],\"default\":null}}]}}` |\n| `create.body.generationConfig.temperature` | `{\"$omitEmpty\":{\"$ref\":\"request.providerOptions.gemini-image.temperature\"}}` |\n| `create.body.generationConfig.topP` | `{\"$omitEmpty\":{\"$ref\":\"request.providerOptions.gemini-image.topP\"}}` |\n| `create.body.generationConfig.topK` | `{\"$omitEmpty\":{\"$ref\":\"request.providerOptions.gemini-image.topK\"}}` |\n| `create.body.generationConfig.seed` | `{\"$omitEmpty\":{\"$ref\":\"request.providerOptions.gemini-image.seed\"}}` |\n| `create.body.safetySettings` | `{\"$omitEmpty\":{\"$ref\":\"request.providerOptions.gemini-image.safetySettings\"}}` |\n| `create.body.systemInstruction` | `{\"$omitEmpty\":{\"$coalesce\":[{\"$ref\":\"request.providerOptions.gemini-image.systemInstruction\"},{\"$if\":{\"condition\":{\"$ref\":\"request.instructions\"},\"then\":{\"parts\":[{\"text\":{\"$ref\":\"request.instructions\"}}]},\"else\":null}}]}}` |\n\n## Provider 扩展键\n\n- `providerOptions.gemini-image.responseModalities`\n- `providerOptions.gemini-image.safetySettings`\n- `providerOptions.gemini-image.seed`\n- `providerOptions.gemini-image.systemInstruction`\n- `providerOptions.gemini-image.temperature`\n- `providerOptions.gemini-image.topK`\n- `providerOptions.gemini-image.topP`\n\n动态模型或工作流允许使用文档声明的完整 `parameters/input/extra_body` 对象；该对象是协议本身的开放 schema，不会被宿主裁剪。\n\n## 响应映射逐字段清单\n\n| 映射位置 | 上游路径或转换表达式 |\n| --- | --- |\n| `response.status` | `\"succeeded\"` |\n| `response.images` | `{\"$map\":{\"from\":{\"$filter\":{\"from\":{\"$ref\":\"response.candidates.0.content.parts\"},\"as\":\"part\",\"where\":{\"$or\":[{\"$ref\":\"part.inlineData\"},{\"$ref\":\"part.inline_data\"}]}}},\"as\":\"part\",\"in\":{\"dataUrl\":{\"$concat\":[\"data:\",{\"$coalesce\":[{\"$ref\":\"part.inlineData.mimeType\"},{\"$ref\":\"part.inline_data.mime_type\"},\"image/png\"]},\";base64,\",{\"$coalesce\":[{\"$ref\":\"part.inlineData.data\"},{\"$ref\":\"part.inline_data.data\"}]}]}}}}` |\n| `response.text` | `{\"$map\":{\"from\":{\"$filter\":{\"from\":{\"$ref\":\"response.candidates.0.content.parts\"},\"as\":\"part\",\"where\":{\"$ref\":\"part.text\"}}},\"as\":\"part\",\"in\":{\"$ref\":\"part.text\"}}}` |\n| `response.usage` | `{\"$ref\":\"response.usageMetadata\"}` |\n| `response.errorPaths[0]` | `\"error.code\"` |\n| `response.messagePaths[0]` | `\"error.message\"` |\n\n## 响应与错误\n\n插件把上游 task/status/text/media/usage 映射为统一结果。临时媒体 URL 标记为 ephemeral，由宿主立即下载持久化。HTTP 错误、业务 code 和 error object 保持失败语义，不包装成成功。\n\n## 兼容边界\n\nimageSize 只映射 1K/2K/4K；未知质量值（如视频清晰度 720）必须省略。多图输出由宿主按次创建，不映射 candidateCount。\n\n\n## Manifest 完整接口定义\n\n以下 JSON 与插件包内实际 `manifest.json` 逐字段一致，覆盖插件身份、权限、配置、鉴权、参数、校验、创建、Agent、查询、取消、结果下载、响应和 Agent 响应映射。`documentation` 字段的值就是当前完整文档；为避免文档在自身内部无限递归，JSON 中仅用等义占位文本表示正文。\n\n```json\n{\n \"apiVersion\": \"yingce.plugin/v2\",\n \"id\": \"google-gemini-image\",\n \"name\": \"Google Gemini Image\",\n \"version\": \"2.0.0\",\n \"author\": \"Google / 影策\",\n \"description\": \"Google Gemini Image 独立请求协议插件。\",\n \"documentation\": \"<当前插件的完整 documentation，由 README.md 与 docs/interface.md 拼接而成；为避免 JSON 递归，此处不重复展开正文。>\",\n \"permissions\": [\n \"generation.run\",\n \"media.read\"\n ],\n \"configuration\": {\n \"fields\": [\n {\n \"name\": \"apiKey\",\n \"type\": \"secret\",\n \"label\": \"API Key\",\n \"required\": true\n }\n ]\n },\n \"contributes\": {\n \"providers\": [\n {\n \"id\": \"gemini-image\",\n \"label\": \"Google Gemini Image\",\n \"capabilities\": [\n \"image\"\n ],\n \"scopes\": [\n \"admin.system-channel\",\n \"user.custom-channel\",\n \"canvas\",\n \"creation\",\n \"agent\"\n ],\n \"baseUrl\": \"https://generativelanguage.googleapis.com\",\n \"requiresPublicMediaUrls\": false,\n \"auth\": {\n \"type\": \"google-api-key\",\n \"field\": \"apiKey\"\n },\n \"parameters\": [\n {\n \"name\": \"model\",\n \"type\": \"string\",\n \"required\": true,\n \"mapping\": \"model\",\n \"description\": \"图片模型 ID。\"\n },\n {\n \"name\": \"prompt\",\n \"type\": \"string\",\n \"required\": true,\n \"mapping\": \"prompt\",\n \"description\": \"图片提示词。\"\n },\n {\n \"name\": \"images\",\n \"type\": \"media[]\",\n \"required\": false,\n \"mapping\": \"provider image/reference fields\",\n \"description\": \"参考图或编辑源图，role 由业务层确定。\"\n },\n {\n \"name\": \"imageCount\",\n \"type\": \"integer\",\n \"required\": false,\n \"mapping\": \"n/sample_count\",\n \"description\": \"输出数量。\"\n },\n {\n \"name\": \"aspectRatio\",\n \"type\": \"string\",\n \"required\": false,\n \"mapping\": \"size/aspect_ratio\",\n \"description\": \"比例或尺寸，语义按协议说明。\"\n },\n {\n \"name\": \"resolution\",\n \"type\": \"string\",\n \"required\": false,\n \"mapping\": \"resolution/imageSize\",\n \"description\": \"分辨率档位。\"\n },\n {\n \"name\": \"quality\",\n \"type\": \"string\",\n \"required\": false,\n \"mapping\": \"quality\",\n \"description\": \"质量档位。\"\n },\n {\n \"name\": \"providerOptions\",\n \"type\": \"object\",\n \"required\": false,\n \"mapping\": \"provider-specific fields\",\n \"description\": \"插件命名空间内的厂商扩展字段。\"\n }\n ],\n \"create\": {\n \"method\": \"POST\",\n \"path\": \"/v1beta/models/{{model}}:generateContent\",\n \"contentType\": \"application/json\",\n \"body\": {\n \"contents\": [\n {\n \"role\": \"user\",\n \"parts\": {\n \"$concatArrays\": [\n [\n {\n \"text\": {\n \"$ref\": \"request.prompt\"\n }\n }\n ],\n {\n \"$map\": {\n \"from\": {\n \"$ref\": \"request.images\"\n },\n \"as\": \"media\",\n \"in\": {\n \"$if\": {\n \"condition\": {\n \"$ref\": \"media.dataUrl\"\n },\n \"then\": {\n \"inlineData\": {\n \"mimeType\": {\n \"$dataMime\": {\n \"$ref\": \"media.dataUrl\"\n }\n },\n \"data\": {\n \"$dataPayload\": {\n \"$ref\": \"media.dataUrl\"\n }\n }\n }\n },\n \"else\": {\n \"fileData\": {\n \"mimeType\": {\n \"$omitEmpty\": {\n \"$ref\": \"media.mimeType\"\n }\n },\n \"fileUri\": {\n \"$ref\": \"media.url\"\n }\n }\n }\n }\n }\n }\n }\n ]\n }\n }\n ],\n \"generationConfig\": {\n \"responseModalities\": {\n \"$coalesce\": [\n {\n \"$ref\": \"request.providerOptions.gemini-image.responseModalities\"\n },\n [\n \"TEXT\",\n \"IMAGE\"\n ]\n ]\n },\n \"imageConfig\": {\n \"aspectRatio\": {\n \"$omitEmpty\": {\n \"$ref\": \"request.aspectRatio\"\n }\n },\n \"imageSize\": {\n \"$omitEmpty\": {\n \"$coalesce\": [\n {\n \"$switch\": {\n \"cases\": [\n {\n \"when\": {\n \"$in\": [\n {\n \"$lower\": {\n \"$ref\": \"request.quality\"\n }\n },\n [\n \"1k\",\n \"low\"\n ]\n ]\n },\n \"then\": \"1K\"\n },\n {\n \"when\": {\n \"$in\": [\n {\n \"$lower\": {\n \"$ref\": \"request.quality\"\n }\n },\n [\n \"2k\",\n \"medium\"\n ]\n ]\n },\n \"then\": \"2K\"\n },\n {\n \"when\": {\n \"$in\": [\n {\n \"$lower\": {\n \"$ref\": \"request.quality\"\n }\n },\n [\n \"4k\",\n \"high\"\n ]\n ]\n },\n \"then\": \"4K\"\n }\n ],\n \"default\": null\n }\n },\n {\n \"$switch\": {\n \"cases\": [\n {\n \"when\": {\n \"$in\": [\n {\n \"$lower\": {\n \"$ref\": \"request.resolution\"\n }\n },\n [\n \"1k\",\n \"low\"\n ]\n ]\n },\n \"then\": \"1K\"\n },\n {\n \"when\": {\n \"$in\": [\n {\n \"$lower\": {\n \"$ref\": \"request.resolution\"\n }\n },\n [\n \"2k\",\n \"medium\"\n ]\n ]\n },\n \"then\": \"2K\"\n },\n {\n \"when\": {\n \"$in\": [\n {\n \"$lower\": {\n \"$ref\": \"request.resolution\"\n }\n },\n [\n \"4k\",\n \"high\"\n ]\n ]\n },\n \"then\": \"4K\"\n }\n ],\n \"default\": null\n }\n }\n ]\n }\n }\n },\n \"temperature\": {\n \"$omitEmpty\": {\n \"$ref\": \"request.providerOptions.gemini-image.temperature\"\n }\n },\n \"topP\": {\n \"$omitEmpty\": {\n \"$ref\": \"request.providerOptions.gemini-image.topP\"\n }\n },\n \"topK\": {\n \"$omitEmpty\": {\n \"$ref\": \"request.providerOptions.gemini-image.topK\"\n }\n },\n \"seed\": {\n \"$omitEmpty\": {\n \"$ref\": \"request.providerOptions.gemini-image.seed\"\n }\n }\n },\n \"safetySettings\": {\n \"$omitEmpty\": {\n \"$ref\": \"request.providerOptions.gemini-image.safetySettings\"\n }\n },\n \"systemInstruction\": {\n \"$omitEmpty\": {\n \"$coalesce\": [\n {\n \"$ref\": \"request.providerOptions.gemini-image.systemInstruction\"\n },\n {\n \"$if\": {\n \"condition\": {\n \"$ref\": \"request.instructions\"\n },\n \"then\": {\n \"parts\": [\n {\n \"text\": {\n \"$ref\": \"request.instructions\"\n }\n }\n ]\n },\n \"else\": null\n }\n }\n ]\n }\n }\n }\n },\n \"response\": {\n \"status\": \"succeeded\",\n \"images\": {\n \"$map\": {\n \"from\": {\n \"$filter\": {\n \"from\": {\n \"$ref\": \"response.candidates.0.content.parts\"\n },\n \"as\": \"part\",\n \"where\": {\n \"$or\": [\n {\n \"$ref\": \"part.inlineData\"\n },\n {\n \"$ref\": \"part.inline_data\"\n }\n ]\n }\n }\n },\n \"as\": \"part\",\n \"in\": {\n \"dataUrl\": {\n \"$concat\": [\n \"data:\",\n {\n \"$coalesce\": [\n {\n \"$ref\": \"part.inlineData.mimeType\"\n },\n {\n \"$ref\": \"part.inline_data.mime_type\"\n },\n \"image/png\"\n ]\n },\n \";base64,\",\n {\n \"$coalesce\": [\n {\n \"$ref\": \"part.inlineData.data\"\n },\n {\n \"$ref\": \"part.inline_data.data\"\n }\n ]\n }\n ]\n }\n }\n }\n },\n \"text\": {\n \"$map\": {\n \"from\": {\n \"$filter\": {\n \"from\": {\n \"$ref\": \"response.candidates.0.content.parts\"\n },\n \"as\": \"part\",\n \"where\": {\n \"$ref\": \"part.text\"\n }\n }\n },\n \"as\": \"part\",\n \"in\": {\n \"$ref\": \"part.text\"\n }\n }\n },\n \"usage\": {\n \"$ref\": \"response.usageMetadata\"\n },\n \"errorPaths\": [\n \"error.code\"\n ],\n \"messagePaths\": [\n \"error.message\"\n ]\n }\n }\n ]\n }\n}\n```\n\n", "permissions": [ "generation.run", "media.read" ], "configuration": { "fields": [ { "name": "apiKey", "type": "secret", "label": "API Key", "required": true } ] }, "contributes": { "providers": [ { "id": "gemini-image", "label": "Google Gemini Image", "capabilities": [ "image" ], "scopes": [ "admin.system-channel", "user.custom-channel", "canvas", "creation", "agent" ], "baseUrl": "https://generativelanguage.googleapis.com", "requiresPublicMediaUrls": false, "auth": { "type": "google-api-key", "field": "apiKey" }, "parameters": [ { "name": "model", "type": "string", "required": true, "mapping": "model", "description": "图片模型 ID。" }, { "name": "prompt", "type": "string", "required": true, "mapping": "prompt", "description": "图片提示词。" }, { "name": "images", "type": "media[]", "required": false, "mapping": "provider image/reference fields", "description": "参考图或编辑源图，role 由业务层确定。" }, { "name": "imageCount", "type": "integer", "required": false, "mapping": "n/sample_count", "description": "输出数量。" }, { "name": "aspectRatio", "type": "string", "required": false, "mapping": "size/aspect_ratio", "description": "比例或尺寸，语义按协议说明。" }, { "name": "resolution", "type": "string", "required": false, "mapping": "resolution/imageSize", "description": "分辨率档位。" }, { "name": "quality", "type": "string", "required": false, "mapping": "quality", "description": "质量档位。" }, { "name": "providerOptions", "type": "object", "required": false, "mapping": "provider-specific fields", "description": "插件命名空间内的厂商扩展字段。" } ], "create": { "method": "POST", "path": "/v1beta/models/{{model}}:generateContent", "contentType": "application/json", "body": { "contents": [ { "role": "user", "parts": { "$concatArrays": [ [ { "text": { "$ref": "request.prompt" } } ], { "$map": { "from": { "$ref": "request.images" }, "as": "media", "in": { "$if": { "condition": { "$ref": "media.dataUrl" }, "then": { "inlineData": { "mimeType": { "$dataMime": { "$ref": "media.dataUrl" } }, "data": { "$dataPayload": { "$ref": "media.dataUrl" } } } }, "else": { "fileData": { "mimeType": { "$omitEmpty": { "$ref": "media.mimeType" } }, "fileUri": { "$ref": "media.url" } } } } } } } ] } } ], "generationConfig": { "responseModalities": { "$coalesce": [ { "$ref": "request.providerOptions.gemini-image.responseModalities" }, [ "TEXT", "IMAGE" ] ] }, "imageConfig": { "aspectRatio": { "$omitEmpty": { "$ref": "request.aspectRatio" } }, "imageSize": { "$omitEmpty": { "$coalesce": [ { "$switch": { "cases": [ { "when": { "$in": [ { "$lower": { "$ref": "request.quality" } }, [ "1k", "low" ] ] }, "then": "1K" }, { "when": { "$in": [ { "$lower": { "$ref": "request.quality" } }, [ "2k", "medium" ] ] }, "then": "2K" }, { "when": { "$in": [ { "$lower": { "$ref": "request.quality" } }, [ "4k", "high" ] ] }, "then": "4K" } ], "default": null } }, { "$switch": { "cases": [ { "when": { "$in": [ { "$lower": { "$ref": "request.resolution" } }, [ "1k", "low" ] ] }, "then": "1K" }, { "when": { "$in": [ { "$lower": { "$ref": "request.resolution" } }, [ "2k", "medium" ] ] }, "then": "2K" }, { "when": { "$in": [ { "$lower": { "$ref": "request.resolution" } }, [ "4k", "high" ] ] }, "then": "4K" } ], "default": null } } ] } } }, "temperature": { "$omitEmpty": { "$ref": "request.providerOptions.gemini-image.temperature" } }, "topP": { "$omitEmpty": { "$ref": "request.providerOptions.gemini-image.topP" } }, "topK": { "$omitEmpty": { "$ref": "request.providerOptions.gemini-image.topK" } }, "seed": { "$omitEmpty": { "$ref": "request.providerOptions.gemini-image.seed" } } }, "safetySettings": { "$omitEmpty": { "$ref": "request.providerOptions.gemini-image.safetySettings" } }, "systemInstruction": { "$omitEmpty": { "$coalesce": [ { "$ref": "request.providerOptions.gemini-image.systemInstruction" }, { "$if": { "condition": { "$ref": "request.instructions" }, "then": { "parts": [ { "text": { "$ref": "request.instructions" } } ] }, "else": null } } ] } } } }, "response": { "status": "succeeded", "images": { "$map": { "from": { "$filter": { "from": { "$ref": "response.candidates.0.content.parts" }, "as": "part", "where": { "$or": [ { "$ref": "part.inlineData" }, { "$ref": "part.inline_data" } ] } } }, "as": "part", "in": { "dataUrl": { "$concat": [ "data:", { "$coalesce": [ { "$ref": "part.inlineData.mimeType" }, { "$ref": "part.inline_data.mime_type" }, "image/png" ] }, ";base64,", { "$coalesce": [ { "$ref": "part.inlineData.data" }, { "$ref": "part.inline_data.data" } ] } ] } } } }, "text": { "$map": { "from": { "$filter": { "from": { "$ref": "response.candidates.0.content.parts" }, "as": "part", "where": { "$ref": "part.text" } } }, "as": "part", "in": { "$ref": "part.text" } } }, "usage": { "$ref": "response.usageMetadata" }, "errorPaths": [ "error.code" ], "messagePaths": [ "error.message" ] } } ] } }