AI盒绘开放平台开发者中心
欢迎接入 AI盒绘开放平台!我们为第三方合作企业系统提供规范、安全、即插即用的 AI 包装设计集成方案。您的终端用户可凭短时 Ticket 免登直达全功能设计器,设计完成后通过 Webhook 文件流将高清成品与业务参数回传至贵司系统,实现物理强隔离的一对一业务闭环。
企业用户一对一隔离
通过 company_id 强隔离租户,外部用户与项目映射为平台内部唯一实体。
Ticket 一次性即焚免登
服务端加签申请票据,首屏自动换取 JWT 写入 Cookie,防止 URL 泄露长期 Token。
Webhook 文件流回传
点击“完成编辑”,合成图像二进制流及自定义参数 extra 原样推送至第三方系统。
★ 接入环境矩阵与沙箱凭据 (Environment Matrix)
提供完备的双环境隔离机制。开发者在沙箱联调通过后,只需替换 Base URL 与正式凭据即可平滑无缝上线。
测试联调环境 (Staging / Sandbox)
供第三方开发者进行接口签名加签与完整链路联调
正式生产环境 (Production)
面向第三方企业正式上线业务流量,强租户物理隔离
company_id 与绝密凭据。
02 第三方企业用户免登认证 (Ticket 换票)
避免在前端 URL 暴露长期有效的主站 JWT。合作方服务端通过凭据预先申请 Ticket,用户带 Ticket 访问编辑器完成自动认证。
向 AI盒绘开放平台申请接入资质,平台为贵司分配唯一的 company_id、app_key 与 app_secret。注意:AppSecret 属于绝密凭据,严格保存在贵司服务器,绝不通过前端网络传输!
在引导用户打开设计器之前,贵司服务端基于参数字典序与 AppSecret 计算 HMAC-SHA256 签名,携带时间戳与随机防重放串请求接口,换取 5 分钟有效的一次性 ticket。
将参与签名的键值对按照 Key 字典序升序排列,过滤掉值为空的字段,用 & 连接成形如 appKey=xxx&externalUserId=xxx&nickname=xxx&nonce=xxx×tamp=xxx 的待签名串;使用 app_secret 作为密钥进行 HMAC-SHA256 加密,输出 64 位小写十六进制字符串放入请求头 X-Open-Signature。
| 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 计算出的十六进制摘要签名 |
{
"externalUserId": "corp_u_10086", // 【必填】贵司系统的用户唯一标识 (物理隔离映射凭据)
"nickname": "张经理·高级包装师" // 【可选】用户展示昵称
}
{
"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,在浏览器新标签页或窗口中打开即可进入全功能纯编辑器画布。
| 参数名 (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)。
|
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 回调接口。
multipart/form-data
| 表单字段名 (Key) | 类型 | 说明 |
|---|---|---|
| file | Binary File (Blob) | 导出生成的合成图像二进制文件流 (PNG/JPEG 高清原图) |
| externalProjectId | String | 原样透传第三方传入的工程/订单 ID,用于精准入库归档 |
| externalUserId | String | 原样透传第三方传入的用户 ID |
| extra | String | 原样透传第三方传入的自定义透传数据(批次、审批号等) |
| title | String | 用户保存时的设计标题 |
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,并可一键进入设计器进行真实联调体验。
08 接入演进与后续支持 (Roadmap)
我们正在持续扩充开放平台的生态连接能力,后续将陆续上线以下高阶特性:
双环境隔离、Ticket免登与脱敏 Webhook 直推
支持测试沙箱与正式生产双环境隔离,通过 Ticket 方式进行无感静默认证,自动拉取底图并在完成编辑后触发 Webhook 文件流与 extra 透传参数回传。
Iframe 嵌入式工作台与 PostMessage 双向通信
支持第三方系统直接以全屏或弹窗 Iframe 形式内嵌设计器,并通过 window.postMessage 实现前端跨窗口事件与状态实时联动。