# 接入自己的生图模型

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

## 有自己的生图 API Key，怎么接进工作台？

支持应用内置图像接口的模型，可在 **设置 → 模型与用量 → 服务商管理** 配好 Key、启用模型并打开 **图片生成** 能力，再到生图工作台选择。遇到阿里云百炼等原生接口，使用 **AI 接入生图模型**，让 AI 按官方文档制作并测试生图配方。

“配方”就是这个模型的调用配置。你不需要先学会写 JSON；提供服务商、准确模型 ID、地域和接口资料即可。**只开启“图片生成”只会让模型进入列表，不会自动把聊天接口转换为生图接口。**

## 第一步：准备服务商与模型

在服务商管理中配置自己的 API Key；已经配置过就直接复用，不必再复制到对话。还没配置时，也可在 AI 接入会话中使用 **安全保存密钥**，让 AI 帮你建立服务商。

百炼用户请准备：

- 百炼控制台的模型调用 **API Key**，不要用阿里云 AccessKey ID / Secret 代替。见[获取百炼 API Key](https://help.aliyun.com/zh/model-studio/get-api-key)。
- 准确的 **模型 ID**，例如 `wan2.6-t2i`；请使用你所在地域已开通、可调用的模型，以控制台与该模型文档为准。
- **地域与 API Host**。Key、模型与请求地址要对应；文档中的业务空间域名若含 `{WorkspaceId}`，须换成你自己的业务空间 ID。原有百炼聊天配置可保留，生图地址写在对应模型的配方里。

## 第二步：先选一个能帮你配置的 AI

首次使用，打开 **设置 → 模型与用量 → 服务商管理 → 让 AI 帮我配置**，选一个可正常聊天、支持工具调用的文本模型，进入管理会话后即可返回。

这个是“负责读文档、配置接口的 AI”，与你要接入的“负责画图的模型”可以不同。只会输出图片的模型不能承担接入工作。

## 第三步：进入生图接入，查文档并制作配方

打开 **生图工作台 → 顶部模型名称（未选择时显示“图像模型”）→ AI 接入生图模型**。工作台也可从 **设置 → 助手与能力 → 图像生成** 打开。

生图接入默认开启联网研究，独立于普通聊天的联网开关；优先使用可用的搜索服务，没有配置时提供无需 Key 的基础搜索与网页读取。输入区可切换搜索服务或关闭联网，主动关闭后会保留选择。

可以直接说“查百炼这个模型的官方文档”，也可以贴文档链接。AI 应先读请求与响应正文，再制作配方；搜索摘要不足以确认接口参数。网页无法读取时，把官方请求示例、响应示例和参数说明粘贴进来。

把下面内容复制到 **AI 生图接入**，补全方括号中的信息：

```text
请把阿里云百炼的生图模型接入生图工作台。
服务商名称：[应用中已配置的服务商名称]
模型 ID：[准确的模型 ID]
地域与 API Host：[控制台提供的地域和实际地址]
用途：先接入文生图，每次 1 张。
请先读取我的现有配置，查询并阅读这个模型的官方接口文档，
确认请求地址、必需请求头、尺寸和响应格式；若是异步接口，配置查询任务结果。
使用这个服务商已配置的 API Key 测试配方，不要让我重复粘贴 Key。
真实出图后展示结果，再请我确认保存，并告诉我回工作台如何选择。
```

百炼官方资料：[千问 Qwen-Image](https://help.aliyun.com/zh/model-studio/qwen-image-api)、[万相文生图](https://help.aliyun.com/zh/model-studio/text-to-image-v2-api-reference)。**不同模型与版本的调用方式可能不同**，不要直接套用其他模型的地址、尺寸或配方。百炼聊天的 `compatible-mode` 地址不能直接用来调用这些原生生图接口。

## 第四步：看见测试图片，再确认保存

AI 的配方测试会在本机使用目标服务商当前有效的 Key 发起真实请求，密钥明文不会作为测试工具结果交给 AI。测试图片会显示在会话产物卡片中；拿到任务编号、连接测试通过、或者 AI 说“配置好了”，都不能代替真实出图。

确认测试结果后，在配方保存确认面板中核对服务商与模型。**管理模型对话和生图测试都可能消耗各自服务商的额度**；先测试 1 张，成功后再批量使用。

## 第五步：回工作台使用

返回工作台，打开模型面板，在 **自定义配方** 中选择刚才保存的模型，输入描述并生成。以后可在生成设置里 **编辑配方**；失败时复制工作台报错，回 **AI 接入会话历史** 继续排查。

## 卡住了，先看这里

- **点 AI 接入却打开手动编辑页**：还没选可用的 AI 管理模型。先完成第二步，再回工作台进入。
- **没有联网工具或查询失败**：查看输入区联网状态；开启或切换服务，也可粘贴完整文档。关闭联网研究仍可用现有 Key 测试已有配方，但缺失接口资料时不应猜字段。
- **模型不显示**：核对配方是否真正保存到了目标服务商/模型、模型是否启用；保存有效配方会自动补上图片输出能力。仅保存服务商 Key 并不等于完成生图接入。
- **能聊天，生图却报错**：核对生图原生地址、模型 ID、地域和图片提取方式。不要通过改动整个服务商的聊天路径来修复生图。
- **提示不支持同步调用，或只得到 task_id**：让 AI 核对该模型的异步接口。配方可设置非鉴权请求头（如文档要求的 `X-DashScope-Async: enable`）和任务轮询；必须等待任务成功并提取最终图片。
- **想带参考图**：先确认具体模型支持图像编辑，再让 AI 配置参考图参数；文生图配方不会自动变为图生图配方。图生图配方无需 Pro。

熟悉接口的用户也可手动编辑配方。编辑页的 **DashScope** 和 **Async 异步任务** 是起点模板，需要按实际模型文档修改地址、参数、请求头与提取路径，并测试后再用；不是所有百炼模型通用的一键配置。