# AI 生图接入是什么？

> Cube Agent 2.2.0 正式版（构建 2002007）使用说明。
> 分类：图像生成。内容基准：2026-11-07。
> 网页：https://cubeagent.app/docs/recipe_onboarding/

## 它能做什么

生图工作台内置支持 OpenAI 图像接口、Gemini、Imagen、Grok 等常见接口范式，但各家生图接口的细节差异很大（参数名、请求体结构、图片在响应里的位置都不一样），无法全部内置。**AI 生图接入** 把这类"接不进来"的生图模型交给 AI 处理：你在专用管理会话里贴上接口文档或描述需求，AI 自动试调接口、根据报错迭代修正，真实出图验收后保存为一份**配方**，模型随即出现在工作台，与内置模型同样使用。

入口在 **生图工作台 → 顶部配置胶囊 → 模型选择 → AI 接入生图模型**。与 AI 服务商管理一致，它也使用专用管理会话：标题栏固定标识当前模式，会话自动保留、可续用，不出现在任何会话列表里。

## 什么是配方

配方是一份声明式数据，完整描述"怎么调用一个生图接口"：

- **地址与鉴权**：URL 模板（`{{baseUrl}}` 会替换为所属服务商地址）与鉴权方式；密钥始终引用所属服务商，不会写进配方。
- **接口请求头**：`requestHeaders` 可声明接口所需的固定非鉴权头，例如百炼异步开关；鉴权由服务商 Key 自动附加，不要把 Key 写进配方。
- **请求体模板**：任意 JSON 结构加占位符（`{{prompt}}`、`{{modelId}}`、`{{count}}`、`{{param.参数名}}`），各平台的特殊要求（例如 content 必须是数组格式）直接照写即可。
- **参数表**：比例、尺寸、风格、种子等参数与取值范围。工作台的生成设置面板按参数表动态渲染——配方没声明的参数不会出现，每个模型的设置面板恰好只有它支持的选项。支持任意像素尺寸的接口还可在配方中声明 `customSize`，把工作台的宽 × 高输入映射到一个 `size` 参数或独立的 `width` / `height` 参数，并附带各自的范围、像素和倍数限制；关闭自定义尺寸时，仍可使用参数表中配置的常用预置尺寸。
- **提取路径**：声明图片在响应中的位置（支持数组展开与按字段过滤）与错误信息位置；提取失败时还有自动深扫兜底。

配方挂在具体模型上，保存后该模型自动标记为图片输出能力。

## 直接对它说

- "帮我接入硅基流动的 Seedream，接口文档已粘贴。"
- "新加的这个中转和 A 站一样，把 A 的生图配方复用到它的同款模型上。"
- "生图报错了：{粘贴工作台复制的报错}，帮我修一下配方。"

AI 会先读取本机真实配置再动手；目标服务还不是已配置的服务商时，会先新建服务商挂好地址与密钥，再开始试调。**保存前必须真实生成一张图验收**，测试图会直接出现在会话里；保存配方需要你确认，确认前 AI 不会声称已完成。

## 多服务商复用

多个服务商只有地址不同、模型相同时，配方可以直接复用：告诉 AI 复制到哪个服务商的同款模型即可，AI 会读取现有配方改挂过去，并先对新服务商出图验证再保存。只有 URL 模板使用 `{{baseUrl}}` 相对形式的配方才能跨服务商复用；写死完整地址的配方（如 DashScope 官方原生端点）不可跨服务商复用。

## 安全与清理

- 密钥可经输入区 **安全保存密钥** 按钮存入本机（对话里只显示脱敏引用，模型全程看不到明文），也可直接使用已配置服务商的密钥。
- 配方保存与服务商写入都需要逐次确认；联网搜索在输入区可开关、可切换引擎。
- 试调产生的测试图片随会话保留（回到该管理会话即可查看）；删除会话时连带清理，不留垃圾文件。

## 工作台配合

- 配方模型在配置胶囊上带渐变小圆点标识；生成设置面板底部可打开 **请求预览**，查看按当前参数实时组装的实际请求（密钥已脱敏），排障时一目了然。
- 生成失败时，错误行提供两个入口：**复制**（复制含服务商与模型信息的报错上下文，带去 AI 会话咨询或建配方）与 **编辑配方**（一键带着报错进入配方编辑页手动修复）。

## 手动编辑

不经过 AI 也可以管理配方：选中模型尚无配方时，生成设置面板会出现 **为此模型配置生图配方** 入口；模型已有内置适配（gpt-image、Gemini 图像、Imagen、Grok 等）时入口显示为 **基于内置预设微调配方**，编辑页会自动生成一份配方起点，改参数保存即可，不必从模板或 AI 从头配。GPT Image 预设支持最多 4 张参考图，添加参考图后自动切换到文件上传编辑接口；保留原名称和请求结构的旧 GPT 预设会在读取时自动补齐，原有参数和保存的 JSON 保留。Gemini 图像与对话出图预设支持单张参考图。已有配方则从设置面板 → **编辑配方** 进入编辑页。编辑页另内置多套起点模板（OpenAI 兼容对话出图 / DashScope 原生 / Images API / 图生图 / 异步任务），支持 JSON 校验、真实测试生成与保存，也可在编辑页删除配方（清空配方，模型与密钥保留；内置适配模型删除配方后即恢复预设行为）；把目标服务商或模型切换后再保存，即为复制。尚未设置 AI 管理模型时，「AI 接入生图模型」入口也会先打开这里；可在服务商管理页设置管理模型后使用 AI 接入。

## 最佳实践：一次接成功

1. **备好材料**：官方接口文档原文或能跑通的 cURL 示例最有效，地址、请求体、**响应示例**缺一不可——响应示例决定图片提取路径；实在没有文档，再口头描述需求。
2. **一次接一个模型**：先在最容易成功的官方站接入并验收，再让 AI 把配方复用到同款模型的中转上。只有 URL 模板使用 `{{baseUrl}}` 相对形式的配方才能跨服务商复用。
3. **走报错闭环**：工作台生成失败时，用错误行的 **复制** 带走完整上下文去问 AI，比口头说「报错了」高效得多；想自己动手就用 **编辑配方**。
4. **验收后再批量**：保存前必须真实出图；保存后先在生成设置面板底部打开 **请求预览** 核对参数，再批量生成。
5. **密钥不粘贴明文**：用输入区 **安全保存密钥** 按钮存入本机，或直接使用已配置服务商的密钥。

## 当前边界

文生图与图生图使用不同接口时，可声明 editRequest（包含 urlTemplate、requestEncoding、bodyTemplateJson）：有参考图时使用此分支，无图时仍使用主模板；参数、鉴权和响应提取规则共用。图片参数也可仅在编辑分支中引用。GPT Image 内置预设已包含此配置。

配方在参数表中声明 `image` 参数后即可使用参考图（图生图），未声明的纯文生图配方暂不支持；参考图以 base64 内联注入，可选参数（required:false）在未添加参考图时自动省略请求体中的注入点，一份配方可同时覆盖文生图与图生图，单图参数还支持 `{{param.<键>.mime}}` / `{{param.<键>.base64}}` 子键拆解（供 Gemini 原生 inline_data 这类 MIME 与数据分字段的接口）；文件上传类接口（如 OpenAI images/edits）可设置 requestEncoding 为 multipart/form-data：bodyTemplateJson 用顶层对象描述表单，普通字段为字符串、数字或布尔值，图片字段完整引用 {{param.<键>}}，字段名按接口要求填写 image 或 image[]；多图按同一字段名上传，不支持嵌套对象、数组及图片 .mime/.base64 子键。省略 requestEncoding 时保持原有 JSON 行为。需要"提交任务后轮询取图"的接口请使用配方的 async 段（详见「生图配方怎么设计好用?」）。