| name | image-generation-advanced |
| description | 高级图片生成与编辑，支持文生图、图生图、多图合成，异步任务轮询。需要 AI 生成图片、对图片做内容编辑或风格转换时优先使用该工具。 |
| license | MIT |
能力概述
图片生成与编辑（高级版）提供高质量的图片生成与精细编辑能力，支持以下三种模式：
| 模式 | 说明 |
|---|
| 文生图 | 仅提供文字提示词，生成对应图片 |
| 图生图 | 上传一张图片 + 提示词，进行风格转换或编辑 |
| 多图生图 | 上传多张图片 + 提示词，智能合成 |
两个接口（异步任务模型）：
| 接口 | 方法 | Endpoint |
|---|
| 提交任务 | POST | https://app-bo4w33bsdqm9-api-ra5EZDjVKkXa-gateway.appmiaoda.com/image-generation/submit |
| 查询状态 | POST/GET | https://app-bo4w33bsdqm9-api-VaOwP2jDmAga-gateway.appmiaoda.com/image-generation/task |
任务状态：PENDING → PROCESSING → SUCCESS / FAILED
完成后返回 imageUrl（CDN 链接，建议转存至 Supabase Storage 保持持久性）。
平台差异：
| 平台 | 查询接口调用方式 | 说明 |
|---|
| Web | POST body { taskId } | 标准用法 |
| MiniProgram | GET 查询参数 ?taskId=... | Miaoda 代理会丢弃小 POST body，改用 GET 参数 |
| App | POST body { taskId } | 同 Web；图片上传需使用 expo/fetch + ArrayBuffer 方式转存至 Supabase Storage |
详见 references/image-generation-api.md。
使用前决策
调用本工具前，先判断场景是否真的需要 AI 生成：
| 场景 | 推荐方案 |
|---|
| 根据文字描述生成全新图片 | ✅ 本工具（文生图） |
| 上传图片 + 提示词做风格转换或内容编辑 | ✅ 本工具（图生图） |
| 多张图片智能合成新图 | ✅ 本工具（多图生图） |
| 图片内容审核 / 质量评分 | ❌ 改用视觉模型直接分析，无需生成 |
Prompt 编写规范
底层模型（Gemini Imagen 系列）对英文提示词的输出质量明显优于中文，请始终先将用户需求翻译/改写为英文后再提交 API。
写作原则：
- 使用描述句，直接描述目标画面，而非告诉模型"帮我生成……"
- 具体优于抽象：
"a ginger cat sitting in a sunlit garden" 好于 "可爱的猫"
- 避免否定词：不写
"no background"，改写 "isolated on pure white background"
- 末尾加质量修饰词提升细节：
high quality, detailed, 8k, photorealistic
文生图模板：
[Subject], [Action/Pose/State], [Scene/Environment], [Lighting], [Style], [Quality]
示例：
A golden retriever puppy, sitting and looking up curiously, in a cozy living room with warm afternoon lighting, watercolor illustration style, high quality, detailed
图生图额外建议：
- 先描述希望保留的内容，再描述希望改变的内容
- 风格迁移时明确目标风格，例如
"convert to anime style" 或 "oil painting style"
生成期用法（Agent 直接调用）
适用于 Agent 脚本直接调用，密钥由平台注入。
在调用 API 之前，先将用户需求翻译/改写为英文提示词，底层 Gemini Imagen 系列模型对英文输入的图像质量明显优于中文。
const apiKey = process.env["INTEGRATIONS_API_KEY"]!;
async function submitImageGeneration(prompt: string): Promise<string> {
const response = await fetch(
"https://app-bo4w33bsdqm9-api-ra5EZDjVKkXa-gateway.appmiaoda.com/image-generation/submit",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Gateway-Authorization": `Bearer ${apiKey}`,
},
body: JSON.stringify({
contents: [{ parts: [{ text: prompt }] }],
}),
}
);
if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
const json = await response.json();
if (json.status !== 0) throw new Error(`API error: ${json.message}`);
return json.data.taskId;
}
(): <{
: ;
?: ;
?: { : ; : };
}> {
response = (
,
{
: ,
: {
: ,
: ,
},
: .({ taskId }),
}
);
(!response.) ();
json = response.();
(json. !== ) ();
{
: json..,
: json..?.,
: json..,
};
}
(): <> {
taskId = (prompt);
= ;
= * * ;
deadline = .() + ;
(.() < deadline) {
( (r, ));
result = (taskId);
(result. === ) result.!;
(result. === ) {
();
}
}
();
}
空间位置描述（生成期 Prompt 增强）：
在提示词中加入空间位置词可显著提高构图准确性：
| 位置关键词 | 说明 | 示例 |
|---|
centered / in the center | 主体居中 | "a red rose, centered, white background" |
in the top-left / bottom-right corner | 角落定位 | "logo in the top-left corner" |
in the foreground / background | 前景/背景层次 | "flowers in the foreground, mountains in the background" |
on the left side / right side | 左右分布 | "person on the left, product on the right" |
filling the entire frame | 占满画面 | "texture filling the entire frame" |
生成期文件下载（必须执行）：
生成接口返回的 URL 是 CDN 临时链接，在生成期（Agent 直接调用场景）获得 URL 后，必须立即使用 Bash 工具将文件下载到本地，以便用户查看结果。
curl -L -o <本地路径> "<生成的文件 URL>"
完整生成期工作流（含下载步骤）：
- 调用生成函数获取文件 URL
- 使用 Bash 工具执行
curl -L -o <本地路径> "<url>" 将文件下载到本地
- 告知用户文件已保存到对应路径
注意：上游 CDN 链接有时效性，应在获得 URL 后立即下载，不要延迟。
完整参数说明（含图生图、多图合成）详见 references/image-generation-api.md。
生成后用法（应用内通过 Edge Function 调用）
应用内通过 Edge Function 代理调用，密钥不暴露给前端。
平台实现差异：
| 平台 | Edge Function 差异 | 前端调用方式 |
|---|
| Web | 查询接口用 POST body | supabase.functions.invoke |
| MiniProgram | 查询接口用 GET + URL 参数（绕过代理 body 丢失问题） | supabase.functions.invoke("query-task?taskId=...") with method: "GET" |
完整 Edge Function 代码和前端调用代码详见 references/image-generation-api.md。
