Kling Image Expand

能力概述

本 skill 基于可灵 AI 的图像扩展能力，对原始图片在上、下、左、右四个方向按比例扩充画布，并自动填充生成新的图像内容。

Auth Header 为 X-Gateway-Authorization: Bearer ${INTEGRATIONS_API_KEY}（注意不是标准的 Authorization）。

API 端点

关键约束

• 原图格式：.jpg / .jpeg / .png，文件大小 ≤ 10 MB，宽高 ≥ 300 px，宽高比在 1:2.5 ~ 2.5:1 之间
• 四个方向的扩充倍数均在 [0, 2] 范围内，且扩充后总面积不超过原图的 3 倍
• Base64 传参时，不要添加 data:image/png;base64, 等前缀，直接传裸 Base64 字符串
• 生成图片 URL 30 天后失效，务必及时转存至 Supabase Storage

生成期用法（Agent 直接调用）

详见 references/kling-image-expand-api.md 的"生成期代码"章节。

异步完整工作流（提交 → 轮询 → 获取结果）：

// 完整异步工作流：提交任务 → 轮询 → 超时保护
async function expandImageAndWait(
  image: string,
  upRatio: number,
  downRatio: number,
  leftRatio: number,
  rightRatio: number,
  prompt = "",
  n = 1,
): Promise<{ index: number; url: string }[]> {
  const { taskId } = await createExpandTask(image, upRatio, downRatio, leftRatio, rightRatio, prompt, n);

  const POLL_INTERVAL_MS = 7000;
  const TIMEOUT_MS = 10 * 60 * 1000; // 10 分钟
  const deadline = Date.now() + TIMEOUT_MS;

  while (Date.now() < deadline) {
    await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
    const result = await queryExpandTask(taskId);
    if (result.task_status === "succeed") {
      return result.task_result.images;
    }
    if (result.task_status === "failed") {
      throw new Error(`扩图任务失败: ${result.task_status_msg ?? "未知错误"}`);
    }
    // submitted / processing → 继续轮询
  }
  throw new Error(`任务 ${taskId} 超时（10 分钟）`);
}

完整函数实现（createExpandTask、queryExpandTask）及参数说明详见 references/kling-image-expand-api.md。

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

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

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

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

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

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

使用示例

将一张竖版图片向左右两侧各扩展约 65%，生成 16:9 横版图：

// 原图 100×100，目标宽高比 16:9，扩充后总面积约 3 倍
// 向上/下各扩 0.15，向左/右各扩 0.65
const images = await expandImageAndWait(
  "https://example.com/photo.png", // 图片 URL 或裸 Base64
  0.15,   // up_expansion_ratio
  0.15,   // down_expansion_ratio
  0.65,   // left_expansion_ratio
  0.65,   // right_expansion_ratio
  "蓝天白云，自然延伸", // 可选提示词
  1,      // 生成数量
);

console.log(images[0].url); // 转存后的持久化图片 URL

详细参数约束（原图格式、面积上限等）见 references/kling-image-expand-api.md。

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

详见 references/kling-image-expand-api.md 的"Edge Function 代码"和"前端调用代码"章节。

平台差异对比

Edge Function 将在内部完成"提交 → 轮询 → 转存"全流程，前端只需发起一次请求并等待最终图片 URL。