图片翻译编辑器协议

2.2.1图片处理逻辑

• 上传图片

  • 单次可传一张或多张，单次最多25张，

  • 多次总和25张

• 图片处理，处理按钮（立即翻译/消除/抠图）会对已上传的所有图片生效

  • 如您仅想要对单张图进行处理请上传一张图

  • 如您想对多张图进行处理请上传多张图

2.2.2图片继承逻辑

• 继承关系，满足图片像素和大小要求即可被继承

  • 图片翻译

    • 格式：JPG、JPEG、PNG、BMP、WEBP

    • 像素宽高均：≤4000

    • 大小：≤10MB

  • 智能消除标准版&智能抠图

    • 格式：JPG、JPEG、PNG、BMP、WEBP

    • 像素：100×100 至 3000×3000

    • 大小：≤10MB

  • 智能消除Pro版

    • 格式：JPG、JPEG、PNG、BMP、WEBP

    • 像素 256×256 至 3000×3000，

    • 大小 ≤ 10MB

• 继承的触发规则

  • 上传图片成功后，继承已上传成功的图片，不继承对该图片的处理结果

• 继承的校验规则

  • 以目标能力（翻译/消除/抠图）的图片要求（像素及文件大小）作为校验条件

    • 符合条件则允许继承

    • 不符合条件则提示“暂不符合要求，请您重新上传符合要求的图片”

2.2.3二次编辑的规则

• 仅支持对单张图进行二次编辑，不支持对多张图二次编辑

• 图片翻译

  • 当用户点击翻译后，处理成功后则右侧展示完整编辑面板

• 智能消除&智能抠图

  • 当用户点击抠图/消除后，右侧没有编辑面板

  • 当用户点击抠图/消除后，启动了顶栏的文字/贴纸/素材时，右侧展示对应的编辑项

2.2.1翻译/消除/抠图处理

2.2.1二次编辑能力

3.2.1、创建 RAM 子用户并授权

如子账号已存在，可跳过此步骤。

3.2.2、为 RAM 用户授权 AliyunSTSAssumeRoleAccess

3.2.3、创建 RAM 角色

使用 RAM 主账号登录控制台并创建 RAM 角色，也可通过 RAM API CreateRole 创建。

3.2.4、为角色授权

搜索“Aidge”，并选择对应的权限策略。

3.2.5、获取 roleArn、accessKeyId、accessKeySecret 参数

3.2.6、Java 示例代码

<dependencies>
      <dependency>
          <groupId>com.aliyun</groupId>
          <artifactId>aliyun-java-sdk-sts</artifactId>
          <version>3.0.0</version>
      </dependency>
      <dependency>
          <groupId>com.aliyun</groupId>
          <artifactId>aliyun-java-sdk-core</artifactId>
          <version>3.5.0</version>
      </dependency>
      <dependency>
          <groupId>org.apache.httpcomponents</groupId>
          <artifactId>httpclient</artifactId>
          <version>4.5.5</version>
      </dependency>
      <dependency>
          <groupId>com.alibaba</groupId>
          <artifactId>fastjson</artifactId>
          <version>1.2.47</version>
      </dependency>
</dependencies>

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.auth.sts.AssumeRoleRequest;
import com.aliyuncs.auth.sts.AssumeRoleResponse;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.profile.IClientProfile;
import org.apache.http.HttpStatus;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

import java.io.IOException;
import java.net.URISyntaxException;

/**
 * Aidge 虚商控制台免登接入示例。
 * <p>
 * 流程：AssumeRole 获取临时凭证 → GetSigninToken → 构造 federation 免登链接。
 */
public class Test {

    private static final String SIGN_IN_DOMAIN = "https://signin.aliyun.com/federation";

    /**
     * 使用安全令牌获取登录令牌
     * https://help.aliyun.com/document_detail/91913.html
     *
     * @param accesskeyId
     * @param accessKeySecret
     * @param securityToken
     * @return
     * @throws IOException
     * @throws URISyntaxException
     */
    private static String getSignInToken(String accesskeyId, String accessKeySecret, String securityToken)
            throws IOException, URISyntaxException {
        URIBuilder builder = new URIBuilder(SIGN_IN_DOMAIN);

        builder.setParameter("Action", "GetSigninToken")
                .setParameter("AccessKeyId", accesskeyId)
                .setParameter("AccessKeySecret", accessKeySecret)
                .setParameter("SecurityToken", securityToken)
                .setParameter("TicketType", "mini");

        HttpGet request = new HttpGet(builder.build());
        CloseableHttpClient httpclient = HttpClients.createDefault();

        try (CloseableHttpResponse response = httpclient.execute(request)) {
            if (response.getStatusLine().getStatusCode() == HttpStatus.SC_OK) {
                String context = EntityUtils.toString(response.getEntity());
                JSONObject jsonObject = JSON.parseObject(context);
                return jsonObject.getString("SigninToken");
            } else {
                System.out.println(response.getStatusLine());
            }
        }
        return null;
    }

    private static String getChatbotLoginUrl(String pageUrl, String signInToken) throws URISyntaxException {
        URIBuilder builder = new URIBuilder(SIGN_IN_DOMAIN);
        builder.setParameter("Action", "Login");
        // 登录失效后的跳转地址，一般配置为自建 Web 服务中用于 302 跳转的 URL
        builder.setParameter("LoginUrl", "https://signin.aliyun.com/login.htm");
        // 实际访问的 Aidge 控制台页面，例如首页或编辑器页面
        builder.setParameter("Destination", pageUrl);
        builder.setParameter("SigninToken", signInToken);
        HttpGet request = new HttpGet(builder.build());
        return request.getURI().toString();
    }

    /**
     * 通过 AssumeRole 接口获取用户临时身份
     * 参考 https://help.aliyun.com/document_detail/28763.html
     *
     * @param roleArn         RAM 角色 ARN，格式：acs:ram::&lt;主账号UID&gt;:role/&lt;角色名&gt;
     * @param accessKeyId     调用方 AK
     * @param accessKeySecret 调用方 SK
     * @param roleSessionName 用户自定义会话名，可用于用户级别的访问审计。格式：^[a-zA-Z0-9\.@\-_]+$
     * @return
     * @throws ClientException
     */
    private static AssumeRoleResponse.Credentials assumeRole(String roleArn, String accessKeyId,
                                                             String accessKeySecret, String roleSessionName)
            throws ClientException {
        String defaultRegion = "cn-hangzhou";
        IClientProfile profile = DefaultProfile.getProfile(defaultRegion, accessKeyId, accessKeySecret);
        DefaultAcsClient client = new DefaultAcsClient(profile);
        AssumeRoleRequest request = new AssumeRoleRequest();
        // 直接使用拼接好的角色 ARN
        request.setRoleArn(roleArn);
        // 用户自定义参数。此参数用来区分不同的令牌，可用于用户级别的访问审计。格式：^[a-zA-Z0-9\.@\-_]+$
        request.setRoleSessionName(roleSessionName);
        // 指定过期时间，单位为秒。可设置为 900～3600，默认值为 3600
        request.setDurationSeconds(3600L);
        AssumeRoleResponse response = client.getAcsResponse(request);
        return response.getCredentials();
    }

    public static void main(String[] args) throws IOException, URISyntaxException {
        try {
            /*
             * Step 0：准备子账号并完成权限授权
             */
            // 要扮演的 RAM 角色 ARN（由主账号 UID 和角色名拼接），请替换为真实值 acs:ram::${accountId}:role/${roleName}
            String roleArn = "按需替换";
            // 子账号的 AK 和 SK，需具备 AliyunSTSAssumeRoleAccess 权限，请替换为真实值
            String accessKeyId = "按需替换";
            String accessKeySecret = "按需替换";

            // 业务侧用户 ID：用于同一 RAM 角色下区分真实业务用户，便于访问审计。
            // 建议填写业务系统中的用户唯一标识（如 userId），格式需满足：^[a-zA-Z0-9.@-_]+$，长度为 2～64 个字符
            String userId = "按需替换";

            /*
             * Step 1：通过 AssumeRole 接口获取临时 AK、SK 和 SecurityToken
             */
            AssumeRoleResponse.Credentials credentials =
                    assumeRole(roleArn, accessKeyId, accessKeySecret, userId);

            System.out.println("Expiration: " + credentials.getExpiration());
            System.out.println("Access Key Id: " + credentials.getAccessKeyId());
            System.out.println("Access Key Secret: " + credentials.getAccessKeySecret());
            System.out.println("Security Token: " + credentials.getSecurityToken());
            System.out.println("RoleSessionName: " + userId);

            /*
             * Step 2：获取 SigninToken
             */
            String signInToken = getSignInToken(credentials.getAccessKeyId(),
                    credentials.getAccessKeySecret(),
                    credentials.getSecurityToken());

            System.out.println("Your SigninToken is: " + signInToken);

            // 集成 Aidge 编辑器页
            String pageUrl = "https://ecoa4service.console.aliyun.com/editor";

            String accessUrl = getChatbotLoginUrl(pageUrl, signInToken);
            System.out.println("Your PageUrl is : " + accessUrl);
        } catch (ClientException e) {
            System.out.println("Failed：");
            System.out.println("Error code: " + e.getErrCode());
            System.out.println("Error message: " + e.getErrMsg());
            System.out.println("RequestId: " + e.getRequestId());
        }
    }
}

3.2.7、生成 Key 的服务端要求

• Key 生成逻辑必须部署在服务端。服务端应妥善保管 AK、SK、RoleArn 和 Secret 等敏感信息。

• 每次打开编辑器页面时，都应生成新的 Key。

• 不得将 Key 作为长期凭证持久化存储。如需记录，应仅保留必要的审计信息，并避免将其明文输出至前端日志、Nginx 访问日志或监控系统。

• Key 生成后应立即使用。一次性 Key 的有效期为 30 秒，且仅可使用一次。

• 刷新或重新打开页面，以及复制链接后再次访问时，都应重新执行服务端 Key 生成流程。

3.3.1、编辑器初始化配置项

3.3.2、editorConfig 配置项

以下配置项均为选填。按能力分组，未开通的能力对应的配置项不生效。空串 '' 是有意义的值：各 Tip 字段设为 '' 表示不展示对应 tooltip；单档入口下档位标签设为 '' 表示不展示标签。

通用配置

图片翻译（标准版&Pro版）

智能消除-标准版

智能抠图

3.3.3、编辑器消息体

编辑器通过 postMessage 发送的消息体结构如下：

{
  biz: "translate",
  action: "generate",
  data: {
    imageNum: 1,
  },
}

字段说明：

3.3.4、编辑器报错消息体

编辑器通过 postMessage 发送的报错消息体结构如下：

{
  biz: "translate",
  action: "error",
  errCode: "translate-taskError",
  errMessage: errMsg,
}

字段说明：

接入方可根据 errCode 自定义面向用户的错误提示。

3.3.5、编辑器发送的消息

通信方向：编辑器 iframe → 客户前端

3.3.6、编辑器可接收的消息

通信方向：客户前端 → 编辑器 iframe

3.3.7、示例前端代码

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Aidge 编辑器接入示例</title>

    <style>
      html,
      body {
        width: 100%;
        height: 100%;
        margin: 0;
      }

      #editorIframe {
        display: block;
        width: 100%;
        height: 100%;
        border: 0;
      }
    </style>
  </head>

  <body>
    <iframe
      id="editorIframe"
      title="Aidge 在线编辑器"
      allow="clipboard-read; clipboard-write"
      ></iframe>

    <script>
      const editorIframe = document.getElementById("editorIframe");

      // 编辑器页面的 Origin，用于校验和发送 postMessage。
      const editorOrigin = "https://ecoa4service.console.aliyun.com";

      // 编辑器初始化参数。请根据实际业务替换示例值。
      const editorInitData = {
        // translate：图片翻译标准版
        // translatePro：图片翻译 Pro 版
        // translateBoth：标准版 + Pro 版，可在编辑器中切换
        tool: "translateBoth",

        // 以下三项为选填项。不传 imageUrl 时，可在编辑器中手动上传图片。
        imageUrl: "https://example.com/source.jpg",
        sourceLanguage: "zh",
        targetLanguage: "en",

        // 开启生产拦截。编辑器发送 generate 后，会等待父页面返回 respond。
        charge: true,

        // editorConfig 及其所有子配置项均为选填项。
        editorConfig: {
          editorTitle: "图片编辑器",
          showHistory: true,
          historyButtonText: "历史",
          imageTransPanelTitle: "图片翻译",
          historyPanelTitle: "历史任务",
          imageUploaderButtonText: "点击上传图片",
          imageTransLabel: "标准版",
          imageTransProLabel: "Pro 版",
          imageTransTip: "高性价比",
          imageTransProTip: "翻译更精准",
          imageTransOptionsTitle: "语言",
          sourceLanguageLabel: "原始语向",
          sourceLanguageTip: "被翻译内容的语向",
          targetLanguageLabel: "目标语向",
          targetLanguageTip: "想要翻译成的语向",
          includingProductAreaLabel: "原文保留（品牌名）",
          includingProductAreaTip: "开启后主流品牌将不会被翻译",
          includingProductAreaDefaultValue: true,
          imageTransButtonText: "开始翻译",
          showAddText: true,
          showAddSticker: true,
          showAddImage: true
        }
      };

      /**
     * 判断是否允许本次付费 API 调用。
     * 实际接入时，请在此处调用客户服务端，校验用户余额或权限。
     */
      async function checkGenerationPermission({ biz, imageNum, data }) {
        console.log("待确认的生产请求：", {
          biz,
          imageNum,
          data
        });

        // TODO：根据实际业务返回校验结果。
        return true;
      }

      /**
     * 处理生产拦截请求。
     */
      async function handleGenerate(message) {
        const { biz, data } = message;
        const { imageNum } = data ?? {};
        let success = false;

        try {
          success = await checkGenerationPermission({
            biz,
            imageNum,
            data
          });
        } catch (error) {
          console.error("生产请求校验失败：", error);
        }

        // biz 必须与编辑器发送的 generate 消息保持一致。
        editorIframe.contentWindow.postMessage(
          {
            biz,
            action: "respond",
            success
          },
          editorOrigin
        );
      }

      /**
     * 处理编辑器报错。
     */
      function handleEditorError(message) {
        const { biz, errCode, errMessage } = message;

        console.error("编辑器报错：", {
          biz,
          errCode,
          errMessage
        });

        // TODO：可根据 errCode 自定义面向用户的错误提示。
      }

      /**
     * 处理算法生成结果。
     * 该结果不包含用户在编辑器中的后续编辑操作。
     */
      function handleTaskSuccess(message) {
        const { biz, data } = message;
        const results = Array.isArray(data) ? data : [];

        console.log("生成任务完成：", {
          biz,
          results
        });

        // TODO：根据实际业务处理算法生成结果。
      }

      /**
     * 处理用户点击“保存”或“下载”后返回的最终结果。
     */
      function handleSubmitAll(message) {
        const results = Array.isArray(message.data) ? message.data : [];

        console.log("收到编辑器最终结果：", results);

        // TODO：将 schema 原样保存，不得修改其内容。
        // TODO：及时转存结果图片，返回的图片 URL 默认有效期为 7 天。
      }

      /**
     * 监听编辑器 iframe 发送的消息。
     */
      window.addEventListener("message", function (event) {
        // 只接收当前编辑器 iframe 发送的消息。
        if (event.source !== editorIframe.contentWindow) {
          return;
        }

        // 校验消息来源，避免处理其他网站发送的消息。
        if (event.origin !== editorOrigin) {
          console.warn("忽略未知来源的消息：", event.origin);
          return;
        }

        const message = event.data;

        if (!message || typeof message !== "object") {
          return;
        }

        switch (message.action) {
          case "pageReady":
            console.log("编辑器页面已准备就绪");

            // 收到 pageReady 后发送初始化参数。
            editorIframe.contentWindow.postMessage(
              {
                action: "init",
                data: editorInitData
              },
              editorOrigin
            );
            break;

          case "generate":
            // 生产拦截为异步流程，处理结果将通过 respond 返回编辑器。
            void handleGenerate(message);
            break;

          case "error":
            handleEditorError(message);
            break;

          case "taskSuccess":
            handleTaskSuccess(message);
            break;

          case "submitAll":
            handleSubmitAll(message);
            break;

          default:
            console.warn("收到未识别的编辑器消息：", message);
        }
      });

      /**
     * 从客户服务端获取编辑器地址，并设置 iframe src。
     */
      async function loadEditor() {
        try {
          const response = await fetch("/api/aidge-editor/access-url", {
            method: "POST",
            cache: "no-store"
          });

          if (!response.ok) {
            throw new Error(`获取编辑器地址失败：HTTP ${response.status}`);
          }

          const result = await response.json();

          if (!result.src) {
            throw new Error("服务端未返回编辑器 src");
          }

          const editorUrl = new URL(result.src);

          if (editorUrl.protocol !== "https:") {
            throw new Error("编辑器地址必须使用 HTTPS");
          }

          // 消息监听器注册完成后再加载 iframe，避免错过 pageReady。
          // 一次性 Key 生成后应立即使用。
          editorIframe.src = editorUrl.href;
        } catch (error) {
          console.error("编辑器加载失败：", error);
        }
      }

      loadEditor();
    </script>
  </body>
</html>

4.3、接入方自行调用 API

仅当 enableToolExecution=false 时生效。用户触发能力后，编辑器不直接调 API，而是发一个 generate 把整批调用信息交给宿主；宿主一次性完成整批调用后，通过一个 applyToolResult 回传整批结果，由编辑器渲染成任务列表。图片翻译、智能消除、智能抠图三档统一此流程，单张视为长度 1 的整批。

window.addEventListener("message", async (event) => {
  const { action, biz, data } = event.data ?? {};
  if (action === "generate") {
    try {
      // data = { imageNum, apiType, items: [{ name, params, detail }] }
      // 按 biz 路由到对应能力，遍历 items 整批调用（invokeToolApi 为示例）。
      const results = await Promise.all(
        data.items.map((item) => invokeToolApi({ biz, params: item.params })),
      );
      // 回传数组，长度 = data.imageNum，顺序与 items 对应；每份结构与 reEditData
      // 的单个元素一致（图片翻译可直接用后端 genFiles；消除/抠图见下方结构）。
      const resultData = results.map((r) => r.genFilesItem);
      iframeEle.contentWindow.postMessage(
        { biz, action: "applyToolResult", data: resultData }, editorOrigin);
    } catch (error) {
      console.error("能力 API 调用失败：", error);
      // 整批调用失败：data 传空字符串，并由接入方自行 Toast 提示。
      iframeEle.contentWindow.postMessage(
        { biz, action: "applyToolResult", data: "" }, editorOrigin);
    }
  }
});

消除/抠图每份 GenFilesItem 的最小结构（无文字，textAreas 为空数组）：

{
  editInfo: {
    repairedUrl: "https://.../result.png", // 消除/抠图结果图

    textAreas: [],


    resultImageIds: [],


    languages: [],


    font: [],

  },
  srcImage: "https://.../origin.png",       // 原图
  resultList: [{ language: "", fileUrl: "https://.../result.png" }],
}

• biz 须与 generate.biz 一致（见 §3.3.8）；data 为数组 GenFilesItem[]，长度 = generate.data.imageNum，按 items 顺序对应；每份结构与 reEditData 的单个元素一致。整批调用失败传 ""。

• 返回份数少于提交张数时，缺失的图按失败处理；非数组/无法解析时整批按失败处理。

• 智能抠图：结果尺寸可能与原图不同，建议结果图 URL 携带 tps-{宽}-{高} 命名（或允许编辑器域跨域读取图片像素），否则画布可能回退到默认尺寸导致渲染错位。

方式1：事件监听

用户执行以下操作时，编辑器会向接入方返回结果数据：

1. 点击“保存”按钮：返回当前画布的结果图片和协议。

2. 点击“下载”按钮：将结果图片下载到本地，同时返回结果图片和协议。

window.addEventListener("message", (ev: MessageEvent) => {
  const { data, action } = ev.data ?? {};

  if (action === "submitAll") {
    // TODO：在这里处理最终任务结果
    console.log("收到任务结果：", data);
  }
});

方式2：主动获取

接入方可发送 action 为 requestResult 的消息，主动获取编辑器中的结果数据。

iframe.contentWindow?.postMessage(
  {
    action: "requestResult",
  },
  editorOrigin,
);

编辑器收到上述消息后，会按以下方式返回完整的结果数据。

window.addEventListener("message", (ev: MessageEvent) => {
  const { data, action } = ev.data ?? {};
 

  if (action === "submitAll") {
    // TODO：在这里处理最终任务结果
    console.log("收到任务结果：", data);
  }
});