Image Generation Advanced

能力概述

图片生成与编辑（高级版）提供高质量的图片生成与精细编辑能力，支持以下三种模式：

两个接口（异步任务模型）：

任务状态：PENDING → PROCESSING → SUCCESS / FAILED

完成后返回 imageUrl（CDN 链接，建议转存至 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;
}

/** 查询任务状态 */
async function queryTaskStatus(taskId: string): Promise<{
  status: string;
  imageUrl?: string;
  error?: { code: string; message: string };
}> {
  const response = await fetch(
    "https://app-bo4w33bsdqm9-api-VaOwP2jDmAga-gateway.appmiaoda.com/image-generation/task",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Gateway-Authorization": `Bearer ${apiKey}`,
      },
      body: JSON.stringify({ taskId }),
    }
  );
  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 {
    status: json.data.status,
    imageUrl: json.data.result?.imageUrl,
    error: json.data.error,
  };
}

/** 完整异步工作流：提交 → 轮询 → 返回图片 URL */
async function generateImage(prompt: string): Promise<string> {
  const taskId = await submitImageGeneration(prompt);

  const POLL_INTERVAL_MS = 7000;
  const TIMEOUT_MS = 20 * 60 * 1000;
  const deadline = Date.now() + TIMEOUT_MS;

  while (Date.now() < deadline) {
    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
    const result = await queryTaskStatus(taskId);
    if (result.status === "SUCCESS") return result.imageUrl!;
    if (result.status === "FAILED") {
      throw new Error(`Task failed: ${JSON.stringify(result.error)}`);
    }
    // PENDING / PROCESSING → keep polling
  }
  throw new Error(`Task ${taskId} timed out after 20 minutes`);
}

空间位置描述（生成期 Prompt 增强）：

在提示词中加入空间位置词可显著提高构图准确性：

生成期文件下载（必须执行）：

生成接口返回的 URL 是 CDN 临时链接，在生成期（Agent 直接调用场景）获得 URL 后，必须立即使用 Bash 工具将文件下载到本地，以便用户查看结果。

curl -L -o <本地路径> "<生成的文件 URL>"

完整生成期工作流（含下载步骤）：

1. 调用生成函数获取文件 URL
2. 使用 Bash 工具执行 curl -L -o <本地路径> "<url>" 将文件下载到本地
3. 告知用户文件已保存到对应路径

注意：上游 CDN 链接有时效性，应在获得 URL 后立即下载，不要延迟。

完整参数说明（含图生图、多图合成）详见 references/image-generation-api.md。

生成后用法（应用内通过 Edge Function 调用）

应用内通过 Edge Function 代理调用，密钥不暴露给前端。

平台实现差异：

完整 Edge Function 代码和前端调用代码详见 references/image-generation-api.md。