Browser Agent 指南

Browser Agent 接入指南

FastAiZip 的 /ai/image/compress 是一个供 Browser agent 调用的浏览器页面，不是传统上传 API。它适合能打开页面、执行 JavaScript 并读取 DOM 结果的智能体工作流。

Overview

这页真正想解决什么

这页的重点不是把 FastAiZip 描述成一个通用 API 平台，而是明确说明当前能力更适合 Browser agent。也就是说，调用方需要能打开网页、执行 JavaScript、等待 DOM 状态变化，并读取结构化结果。只要调用方符合这个前提，就可以在不额外搭建上传后端的情况下，把浏览器本地压缩能力接进自动化流程。

如果调用方只能发 HTTP 请求、拿 JSON 响应，而不能真正驱动浏览器页面，那么这条接入路线就不匹配。把这一点单独说清楚，既能避免错误预期，也能让真正适合的 Browser agent 更快落地接入。

推荐调用步骤

01
打开 /ai/image/compress。
02
如果只想做最小验收，可以先用 /ai/image/compress?sample=tiny-png&quality=80&output=webp。
03
如果想看更直观的内置样例，也可以用 /ai/image/compress?sample=tiny-emoji&quality=80&output=webp。
04
小图把 image 放进 query；大图把 image 放进 hash，避免 URL 长度限制。
05
如果需要手动填写，把 data URL 或纯 base64 写进 image 输入框，再设置 quality 和 output。
06
等待 data-ai-compress-status 变为 done 或 error。
07
完成后读取 data-ai-compress-result-json 或 data-ai-compress-output。

复制即用验收脚本

打开 /ai/image/compress?sample=tiny-png&quality=80&output=webp 后，把下面这段脚本粘贴进浏览器控制台，就能拿到通过/失败报告。

(() => {
  const selectors = {
    status: "[data-ai-compress-status]",
    error: "[data-ai-compress-error]",
    sample: "[data-ai-compress-sample]",
    resultJson: "[data-ai-compress-result-json]",
    output: "[data-ai-compress-output]",
  };

  const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  const readText = (selector) => document.querySelector(selector)?.textContent?.trim() ?? "";
  const readValue = (selector) =>
    document.querySelector(selector) instanceof HTMLTextAreaElement
      ? document.querySelector(selector).value
      : "";
  const readStatus = () =>
    document.querySelector(selectors.status)?.getAttribute("data-ai-compress-status") ?? "";
  const readSample = () =>
    document.querySelector(selectors.sample)?.getAttribute("data-ai-compress-sample") ?? "none";

  async function run() {
    const startedAt = Date.now();
    let status = readStatus();

    while (status !== "done" && status !== "error" && Date.now() - startedAt < 20000) {
      await wait(250);
      status = readStatus();
    }

    const resultJson = readValue(selectors.resultJson);
    const output = readValue(selectors.output);
    const error = readText(selectors.error);
    const sample = readSample();

    let parsedResult = null;
    try {
      parsedResult = resultJson ? JSON.parse(resultJson) : null;
    } catch {
      parsedResult = null;
    }

    const report = {
      ok:
        status === "done" &&
        Boolean(resultJson) &&
        Boolean(output) &&
        output.startsWith("data:image/"),
      status,
      sample,
      hasResultJson: Boolean(resultJson),
      hasOutputDataUrl: Boolean(output),
      outputLooksLikeImageDataUrl: output.startsWith("data:image/"),
      savedPercent: parsedResult?.savedPercent ?? null,
      outputFormat: parsedResult?.outputFormat ?? null,
      error,
    };

    console.table(report);
    console.log("FastAiZip Browser agent acceptance report:", report);
    return report;
  }

  return run();
})();

稳定选择器

输入图片

[data-ai-compress-image-input]

质量滑块

[data-ai-compress-quality-input]

输出格式

[data-ai-compress-output-format-input]

MIME 输入

[data-ai-compress-mime-input]

文件名输入

[data-ai-compress-filename-input]

开始按钮

[data-ai-compress-submit]

状态

[data-ai-compress-status]

样例来源

[data-ai-compress-sample]

错误文本

[data-ai-compress-error]

结构化结果

[data-ai-compress-result-json]

输出 data URL

[data-ai-compress-output]

协议 JSON

[data-ai-compress-agent-protocol-json]

这页真正想解决什么

推荐调用步骤

打开 /ai/image/compress。

如果只想做最小验收，可以先用 /ai/image/compress?sample=tiny-png&quality=80&output=webp。

如果想看更直观的内置样例，也可以用 /ai/image/compress?sample=tiny-emoji&quality=80&output=webp。

小图把 image 放进 query；大图把 image 放进 hash，避免 URL 长度限制。

如果需要手动填写，把 data URL 或纯 base64 写进 image 输入框，再设置 quality 和 output。

等待 data-ai-compress-status 变为 done 或 error。

完成后读取 data-ai-compress-result-json 或 data-ai-compress-output。

(() => { const selectors = { status: "[data-ai-compress-status]", error: "[data-ai-compress-error]", sample: "[data-ai-compress-sample]", resultJson: "[data-ai-compress-result-json]", output: "[data-ai-compress-output]", }; const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const readText = (selector) => document.querySelector(selector)?.textContent?.trim() ?? ""; const readValue = (selector) => document.querySelector(selector) instanceof HTMLTextAreaElement ? document.querySelector(selector).value : ""; const readStatus = () => document.querySelector(selectors.status)?.getAttribute("data-ai-compress-status") ?? ""; const readSample = () => document.querySelector(selectors.sample)?.getAttribute("data-ai-compress-sample") ?? "none"; async function run() { const startedAt = Date.now(); let status = readStatus(); while (status !== "done" && status !== "error" && Date.now() - startedAt < 20000) { await wait(250); status = readStatus(); } const resultJson = readValue(selectors.resultJson); const output = readValue(selectors.output); const error = readText(selectors.error); const sample = readSample(); let parsedResult = null; try { parsedResult = resultJson ? JSON.parse(resultJson) : null; } catch { parsedResult = null; } const report = { ok: status === "done" && Boolean(resultJson) && Boolean(output) && output.startsWith("data:image/"), status, sample, hasResultJson: Boolean(resultJson), hasOutputDataUrl: Boolean(output), outputLooksLikeImageDataUrl: output.startsWith("data:image/"), savedPercent: parsedResult?.savedPercent ?? null, outputFormat: parsedResult?.outputFormat ?? null, error, }; console.table(report); console.log("FastAiZip Browser agent acceptance report:", report); return report; } return run(); })();