已复制到剪贴板
AI盒绘开放平台 Developer Docs v2.2
沙箱体验 Demo 立即对接
企业级 OpenAPI 规范标准

AI盒绘开放平台开发者中心

欢迎接入 AI盒绘开放平台!我们为第三方合作企业系统提供规范、安全、即插即用的 AI 包装设计集成方案。您的终端用户可凭短时 Ticket 免登直达全功能设计器,设计完成后通过 Webhook 文件流将高清成品与业务参数回传至贵司系统,实现物理强隔离的一对一业务闭环。

企业用户一对一隔离

通过 company_id 强隔离租户,外部用户与项目映射为平台内部唯一实体。

Ticket 一次性即焚免登

服务端加签申请票据,首屏自动换取 JWT 写入 Cookie,防止 URL 泄露长期 Token。

Webhook 文件流回传

点击“完成编辑”,合成图像二进制流及自定义参数 extra 原样推送至第三方系统。

接入环境矩阵与沙箱凭据 (Environment Matrix)

提供完备的双环境隔离机制。开发者在沙箱联调通过后,只需替换 Base URL 与正式凭据即可平滑无缝上线。

公开沙箱·即刻调通

测试联调环境 (Staging / Sandbox)

供第三方开发者进行接口签名加签与完整链路联调

API 接口基准地址 (Open API Base URL)
https://test-open.1packify.com/api
编辑器跳转基准地址 (Editor Base URL)
https://test-editor.1packify.com/aidesign/editor
测试 AppKey
partner_demo_key
测试 AppSecret
partner_demo_secret_2026
官方配套联调体验中心: open-demo.1packify.com
企业隔离·生产合规

正式生产环境 (Production)

面向第三方企业正式上线业务流量,强租户物理隔离

API 接口基准地址 (Open API Base URL)
https://open.heyijiapack.com/api
编辑器跳转基准地址 (Editor Base URL)
https://editor.1packify.com/aidesign/editor
正式企业接入凭据 (AppKey & AppSecret)
通过商务合作与企业入驻资质审核后,由平台独立分配独占 company_id 与绝密凭据。
资质入驻与凭据审批: support@1packify.com

02 第三方企业用户免登认证 (Ticket 换票)

避免在前端 URL 暴露长期有效的主站 JWT。合作方服务端通过凭据预先申请 Ticket,用户带 Ticket 访问编辑器完成自动认证。

1 获取接入凭证与离线密钥 (AppKey & AppSecret)

向 AI盒绘开放平台申请接入资质,平台为贵司分配唯一的 company_idapp_keyapp_secret注意:AppSecret 属于绝密凭据,严格保存在贵司服务器,绝不通过前端网络传输!

2 服务端安全加签申请换票凭证 (Ticket)

在引导用户打开设计器之前,贵司服务端基于参数字典序与 AppSecret 计算 HMAC-SHA256 签名,携带时间戳与随机防重放串请求接口,换取 5 分钟有效的一次性 ticket

POST {OPEN_API_BASE_URL}/open/auth/ticket
调用方:第三方服务端 (Server-to-Server)
端点完整 URL 对照:
[测试环境] https://test-open.1packify.com/api/open/auth/ticket
[正式生产] https://open.heyijiapack.com/api/open/auth/ticket
API 签名规范 (HMAC-SHA256 字典序签名)

将参与签名的键值对按照 Key 字典序升序排列,过滤掉值为空的字段,用 & 连接成形如 appKey=xxx&externalUserId=xxx&nickname=xxx&nonce=xxx×tamp=xxx 的待签名串;使用 app_secret 作为密钥进行 HMAC-SHA256 加密,输出 64 位小写十六进制字符串放入请求头 X-Open-Signature

HTTP 请求头 (Headers)
Header Name 示例值 说明
Content-Type application/json JSON 报文格式
X-Open-App-Key partner_demo_key 企业接入唯一应用标识
X-Open-Timestamp 1789718400 当前 UNIX 秒级时间戳 (防过期,容差 ±300s)
X-Open-Nonce a8f9c2d1e0b34567 至少 16 位高强度随机字符串 (防重放)
X-Open-Signature e3b0c44298fc1c149afbf4c8996... HMAC-SHA256 计算出的十六进制摘要签名
请求 Body (JSON)
{
  "externalUserId": "corp_u_10086",    // 【必填】贵司系统的用户唯一标识 (物理隔离映射凭据)
  "nickname": "张经理·高级包装师"         // 【可选】用户展示昵称
}
成功响应 (JSON 200 OK)
{
  "code": 200,
  "message": "success",
  "data": {
    "ticket": "8c3b7f1e4a9d4e5f8a1c2b3d4e5f6a7b",  // 5分钟有效一次性免登 Ticket
    "expiresIn": 300
  }
}

03 端到端完整时序交互图

清晰展现“第三方服务端 -> 开放平台API -> 终端用户浏览器 -> Webhook 回调接收”的全链路数据流转。

   [第三方服务端]              [AI盒绘开放平台]              [终端用户浏览器]            [三方系统Webhook]
        │                          │                           │                          │
        │ 1. 签名计算 (HMAC-SHA256) │                           │                          │
        │ 2. POST /open/auth/ticket│                           │                          │
        ├─────────────────────────►│                           │                          │
        │                          │ 3. 校验签名与时间戳       │                          │
        │                          │ 4. 生成 5min 即焚 Ticket │                          │
        │ 5. 返回 Ticket            │                           │                          │
        │◄─────────────────────────┤                           │                          │
        │                          │                           │                          │
        │ 6. 拼装编辑器跳转 URL (携带 ticket, image_url, extra) │                          │
        ├──────────────────────────────────────────────────────►│                          │
        │                          │                           │                          │
        │                          │                           │ 7. 打开专用编辑器 URL    │
        │                          │                           │ (editor.1packify.com)    │
        │                          │ 8. 前端首屏静默换票       │                          │
        │                          │◄──────────────────────────┤                          │
        │                          │ 9. 校验 Ticket 并即时作废 │                          │
        │                          │ 10. 写入 Cookie (hyj-Token)│                          │
        │                          ├──────────────────────────►│                          │
        │                          │                           │ 11. 自动载入底图开始设计 │
        │                          │                           │                          │
        │                          │                           │ 12. 用户点击“完成编辑”   │
        │                          │                           │ (触发合成与直推)         │
        │                          │ 13. POST multipart/form-data 直推 Webhook 接收端     │
        │                          ├─────────────────────────────────────────────────────►│
        │                          │                           │                          │ 14. 持久化图像
        │                          │                           │                          │ 15. 关联 extra
        │                          │ 16. 返回 HTTP 200 OK 确认接收                        │
        │                          │◄─────────────────────────────────────────────────────┤
        │                          │                           │                          │
        │                          │                           │ 17. 提示成功并关闭设计器 │

04 跳转编辑器对接规范 (URL Parameters)

获得换票凭据后,拼接对应环境的编辑器 Base URL,在浏览器新标签页或窗口中打开即可进入全功能纯编辑器画布。

[测试联调] 编辑器基础路径 Sandbox
https://test-editor.1packify.com/aidesign/editor
[正式生产] 编辑器基础路径 Production
https://editor.1packify.com/aidesign/editor
参数名 (Key) 类型 是否必填 说明与示例
ticket String 必填 由贵司服务端提前调接口获取的一次性免登换票凭据。首屏自动换取 JWT 写入 Cookie,并自动清洗地址栏抹除 ticket,防止 URL 泄露。
image_url String (URL) 推荐 待编辑的原素材底图远程 HTTP/HTTPS 地址。必须进行标准 encodeURIComponent 编码,编辑器进入后将自动拉取并铺设至画布。
external_project_id String 推荐 贵司业务系统的设计任务/订单/素材唯一标识(如 order_item_9988)。Webhook 回传保存时原样携带,便于贵司精准关联成果。
external_user_id String 推荐 贵司系统内部的用户唯一标识(如 corp_u_10086)。
webhook_url String (URL) 可选 本次编辑保存时动态接收成果直推的 Webhook 回调地址(优先于平台后台配置的默认地址)。需 encodeURIComponent
extra String 可选 第三方自定义业务透传参数(如生产批次号、审批单号或序列化 JSON,需 encodeURIComponent)。全程保持在 URL 上(无 Storage 跨会话残留风险),Webhook 回调时原样回传。
title String 可选 设计项目的初始标题(如“2026月饼礼盒包装正面”)。
source String 可选 来源渠道标识(如 open_platform)。
标准跳转 URL 范例
[测试联调环境示例]
https://test-editor.1packify.com/aidesign/editor?ticket=8c3b7f1e4a9d4e5f8a1c2b3d4e5f6a7b&external_user_id=u_10086&external_project_id=proj_box_01&extra=batch_2026_09&image_url=https%3A%2F%2Fopen-demo.1packify.com%2Fmaterials%2Fbox.jpg&title=%E6%96%B0%E5%8C%85%E8%A3%85%E8%AE%BE%E8%AE%A1
[正式生产环境示例]
https://editor.1packify.com/aidesign/editor?ticket=8c3b7f1e4a9d4e5f8a1c2b3d4e5f6a7b&external_user_id=corp_user_99&external_project_id=order_item_88&extra=dept_VIP&image_url=https%3A%2F%2Fcdn.your-company.com%2Fpack_front.png&title=%E9%AB%98%E6%A1%A3%E7%A4%BC%E7%9B%92%E5%AE%9A%E5%88%B6

05 完成编辑 Webhook 接收规范 (Webhook Contract)

用户在设计器中完成创作后,点击右上角“导出”->“完成编辑”。系统将直接合成高分辨率图像二进制文件流,POST 推送到指定的 Webhook 回调接口。

POST 请求格式:multipart/form-data
表单字段名 (Key) 类型 说明
file Binary File (Blob) 导出生成的合成图像二进制文件流 (PNG/JPEG 高清原图)
externalProjectId String 原样透传第三方传入的工程/订单 ID,用于精准入库归档
externalUserId String 原样透传第三方传入的用户 ID
extra String 原样透传第三方传入的自定义透传数据(批次、审批号等)
title String 用户保存时的设计标题
第三方接收端要求:接收并落盘保存文件后,请返回 HTTP 状态码 200 OK 并在 Body 中返回形如 {"code":200,"message":"success"} 的响应报文。

06 多语言实战示例代码 (SDK & Code Examples)

默认引用测试沙箱环境与公开凭证。复制代码至本地项目,无需修改即可 1 秒调通换票与 Webhook 接收。

// 1. 服务端 HMAC-SHA256 安全签名并申请免登 Ticket
public String getOpenEditorTicket(String externalUserId, String nickname) throws Exception {
    // 【环境配置】测试沙箱环境配置(上线生产只需替换为生产 Base URL 与正式凭据)
    final String API_BASE_URL = "https://test-open.1packify.com/api";
    final String APP_KEY = "partner_demo_key";
    final String APP_SECRET = "partner_demo_secret_2026"; // 绝密存储,严禁前端暴露

    long timestamp = System.currentTimeMillis() / 1000;
    String nonce = UUID.randomUUID().toString().replace("-", "").substring(0, 16);

    // 1.1 参数按 Key 升序字典序拼接
    Map<String, String> params = new TreeMap<>();
    params.put("appKey", APP_KEY);
    params.put("timestamp", String.valueOf(timestamp));
    params.put("nonce", nonce);
    params.put("externalUserId", externalUserId);
    params.put("nickname", nickname);

    StringBuilder sb = new StringBuilder();
    for (Map.Entry<String, String> entry : params.entrySet()) {
        if (entry.getValue() != null && !entry.getValue().isEmpty()) {
            if (sb.length() > 0) sb.append("&");
            sb.append(entry.getKey()).append("=").append(entry.getValue());
        }
    }
    String stringToSign = sb.toString();
    String signature = hmacSha256Hex(stringToSign, APP_SECRET);

    // 1.2 携带签名请求头申请 Ticket
    RestTemplate restTemplate = new RestTemplate();
    HttpHeaders headers = new HttpHeaders();
    headers.set("X-Open-App-Key", APP_KEY);
    headers.set("X-Open-Timestamp", String.valueOf(timestamp));
    headers.set("X-Open-Nonce", nonce);
    headers.set("X-Open-Signature", signature);
    headers.setContentType(MediaType.APPLICATION_JSON);

    Map<String, Object> body = new HashMap<>();
    body.put("externalUserId", externalUserId);
    body.put("nickname", nickname);

    HttpEntity<Map<String, Object>> entity = new HttpEntity<>(body, headers);
    ResponseEntity<Map> resp = restTemplate.postForEntity(
        API_BASE_URL + "/open/auth/ticket", entity, Map.class);
    
    Map data = (Map) resp.getBody().get("data");
    return (String) data.get("ticket");
}

// 2. 接收完成编辑 Webhook 文件流
@PostMapping("/api/webhook/aidesign/handleSave")
public ResponseEntity<Map<String, Object>> handleSave(
        @RequestParam("file") MultipartFile file,
        @RequestParam("externalProjectId") String externalProjectId,
        @RequestParam(value = "externalUserId", required = false) String externalUserId,
        @RequestParam(value = "extra", required = false) String extra,
        @RequestParam(value = "title", required = false) String title) throws IOException {
    
    String filename = file.getOriginalFilename();
    // 依据外部工程 ID 精准归档落盘,并获取 extra 自定义透传数据
    File dest = new File("/data/designs/" + externalProjectId + "_" + filename);
    file.transferTo(dest);
    
    return ResponseEntity.ok(Collections.singletonMap("code", 200));
}

07 在线参数生成调试台 (Interactive Playground)

选择目标环境并输入联调参数,即时生成符合编码标准的完整跳转 URL,并可一键进入设计器进行真实联调体验。

选择目标运行环境:
https://test-editor.1packify.com/aidesign/editor...
新窗口打开设计器

08 接入演进与后续支持 (Roadmap)

我们正在持续扩充开放平台的生态连接能力,后续将陆续上线以下高阶特性:

已上线 (Current)

双环境隔离、Ticket免登与脱敏 Webhook 直推

支持测试沙箱与正式生产双环境隔离,通过 Ticket 方式进行无感静默认证,自动拉取底图并在完成编辑后触发 Webhook 文件流与 extra 透传参数回传。

演进中 (Next)

Iframe 嵌入式工作台与 PostMessage 双向通信

支持第三方系统直接以全屏或弹窗 Iframe 形式内嵌设计器,并通过 window.postMessage 实现前端跨窗口事件与状态实时联动。