# 生图配方怎么设计好用？

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

「AI 生图接入是什么?」讲的是把模型接进工作台的流程;这篇讲配方本身的取舍——参数怎么声明好用、什么时候需要异步任务。AI 接入与手动编辑两条路都适用。

## 三条接入路径怎么选

- **AI 接入**:有官方文档原文或能跑通的 cURL 时首选。AI 会研究接口、真实试调出图,验收后保存;目标服务商还没配置时,它会先建好服务商并保管密钥。
- **内置预设起点**:模型已有内置适配(gpt-image、Images API、Grok、Imagen、Gemini 图像、对话出图),只是想改参数或加参数时,在配方编辑页选「内置预设」,应用按当前服务商地址生成一份等价配方起点,小改即存。
- **模板手写**:接口特殊或你熟悉 JSON 时,从五套模板(对话出图 / 百炼原生 / Images API / 图生图 / 异步任务)起步,用编辑页的「校验」和「测试」兜底。

## 参数面板:让设置变成点选

配方里声明的参数会直接渲染成工作台控件。按取值特征选类型:

- 固定枚举(尺寸、质量、风格档)用**点选胶囊**,不要让用户手输易错值;
- 有边界的数值用**步进器**或**滑条**;
- 是/否选项用**开关**;自由文本(种子、风格提示)用**输入框**;
- 参数支持**条件显隐**:比如只在某个选项取特定值时才露出下一级参数。

支持任意像素尺寸的接口,用 `customSize` 声明宽高参数与边界(倍数、像素上下限),工作台即可自由出尺寸,不必枚举一大堆预设档。

## 参考图:一份配方可选两用

`image` 类型参数(最多 4 张)就是图生图入口。把参考图声明为可选(`required: false`)后,不传图时请求体里的注入点会被整体省略——同一份配方无图走文生图、有图走图生图,不会因空字段被接口拒绝。需要 MIME 与数据分字段的接口,再用 `.mime` / `.base64` 子键拆解。

## 异步任务:慢模型的解药

如果生成经常在一两分钟处失败并提示「服务网关提前断开了连接」,多半是中转网关掐断了长连接——图片可能已在服务端生成,只是响应回不来。这时改用异步配方,把"一次等到底"拆成两步:

1. **提交**:正常发起请求,从响应提取任务 ID(`taskIdPath`);
2. **轮询**:按 `pollUrlTemplate` 定期查询任务状态,出现成功值后按提取路径取图。

默认轮询预算约 10 分钟,间隔自适应,限流(429)会自动退避;超时会提示任务可能仍在服务端执行。编辑页的「Async Task 异步任务」模板可以直接起步;凡是"提交返回任务 ID、再查询取结果"的接口都适合这条路。

## 单次张数与排队

配方声明单请求张数上限(1-4 张);Pro 还可调整生成并发与队列长度,边生成边排队,429 限流自动重排、提示词不丢。

## 常见问题

- **保存配方会影响内置适配吗?**——配方接管该模型;删除配方即恢复应用自动识别,模型与密钥保留。
- **图生图是会员功能吗?**——文生图、图生图及配方生成均无需 Pro；免费用户同一时间可运行 1 个任务，多任务提交、排队与并发为 Pro 能力。模型调用费用由服务商收取。
- **想跨服务商复用?**——让 AI 把配方改挂到另一个服务商的同款模型上即可;只有使用 `{{baseUrl}}` 相对地址的配方才能跨服务商复用。