合作伙伴图纸导入 API

接入流程

1. 合作伙伴先向像素乐园申请授权，获取 Partner API Key。
2. 用户在像素乐园历史生成记录或“我的图纸”中复制 Import Key。
3. 用户把 Import Key 填入合作伙伴客户端。
4. 合作伙伴后端使用 Partner API Key 请求像素乐园接口。
5. 像素乐园校验 Partner API Key 和 Import Key 后返回成品图纸 JSON。

Import Key 可能来自用户历史生成记录，也可能来自用户已购图纸；合作伙伴不需要区分来源，调用方式完全一致。

接口地址

正式环境

https://www.pindoux.cn/api/partner/pattern-import

本地测试

http://localhost:3000/api/partner/pattern-import

POST /api/partner/pattern-import
Content-Type: application/json
X-Partner-Key: <Partner API Key>

{
  "importKey": "PDX-AAAA-BBBB-CCCC-DDDD-EEEE"
}

Key 规范

Partner API Key

Partner API Key 需要先完成授权申请后由像素乐园生成并线下交付给合作伙伴，明文只显示一次，像素乐园服务器只保存 hash。 合作伙伴不得把 Partner API Key 写入公开文档、公开网页、开源仓库或用户可见配置。

Import Key

Import Key 格式为 PDX-XXXX-XXXX-XXXX-XXXX-XXXX。用户可以主动更新 Import Key，更新后旧 Key 立即失效。 合作伙伴客户端只应要求用户填写 Import Key，不得要求用户提供账号、密码、验证码、Cookie 或 Partner API Key。

成功响应

{
  "pattern": {
    "schemaVersion": 2,
    "grid": { "width": 24, "height": 16 },
    "palette": [
      { "index": 0, "beadCode": "G1", "hex": "#FFE2CE", "rgb": [255, 226, 206] }
    ],
    "gridData": [0, 0, 0, 1],
    "stats": [{ "colorCode": "G1", "hex": "#FFE2CE", "count": 128 }]
  },
  "meta": {
    "brand": "像素乐园",
    "catalogVersion": "mard-221",
    "patternId": "pattern_project_id",
    "contentHash": "sha256:...",
    "licenseFingerprint": "pdxlf_...",
    "website": "https://www.pindoux.cn",
    "copyright": "Copyright © 重庆晟辉欣创互联网科技有限责任公司. All rights reserved.",
    "displayPolicy": {
      "personalLibrary": {
        "sourceLabelRequired": false,
        "watermarkRequired": false
      },
      "publicLibrary": {
        "sourceLabelRequired": true,
        "sourceLabel": "来源：像素乐园",
        "watermarkRequired": true,
        "watermarkText": "www.pindoux.cn"
      }
    }
  }
}

gridData.length 必须等于 grid.width * grid.height。licenseFingerprint 是不可逆授权指纹，用于像素乐园追踪授权图纸 JSON 来源，合作伙伴应原样保留。displayPolicy 用于区分个人图库和公共图库展示要求。

接口不会返回生成算法源码、算法参数、用户原图、内部诊断信息、cells 中间单元或 palette.lab。

尺寸兼容与异常处理

合作伙伴必须在渲染或下发设备前校验图纸尺寸。接口返回的是用户授权图纸的原始grid.width 和 grid.height，不会根据合作伙伴设备、客户端画布或材料板规格自动裁剪、缩放或拆分。

如果设备画布最大只支持 54 x 54，就不能直接导入 178 x 178、239 x 162 或 104 x 78 这类超出能力或比例不兼容的图纸。否则可能出现数组越界、渲染错位、设备写入失败、固件异常或用户看到不完整图纸。

建议接入方把 grid.width、grid.height、gridData.length 与自身能力上限放在同一个校验函数里处理。 不兼容时应阻止继续导入，并向用户说明原因，例如“当前设备最大支持 54 x 54，本图纸为 178 x 178，请更换设备或选择较小图纸”。

const { width, height } = payload.pattern.grid;
const expectedCells = width * height;

if (payload.pattern.gridData.length !== expectedCells) {
  throw new Error("图纸格子数据长度不匹配");
}

if (width > device.maxGridWidth || height > device.maxGridHeight) {
  throw new Error(`当前设备最大支持 ${device.maxGridWidth} x ${device.maxGridHeight}，本图纸为 ${width} x ${height}`);
}

if (device.requiresSquareGrid && width !== height) {
  throw new Error(`当前设备只支持正方形图纸，本图纸为 ${width} x ${height}`);
}

公共图库来源展示

用户付费取得的图纸可以导入合作伙伴拼豆模式，也可以保存到用户个人图纸库。个人图纸库不强制显示水印，但必须保留响应中的meta、contentHash 和 licenseFingerprint。

当用户将通过像素乐园 Import Key 导入的图纸分享到合作伙伴公共图库、公开社区、推荐流、搜索结果、分享页或任何第三方可见区域时， 合作伙伴必须在文字信息区展示 来源：像素乐园，并在公开图纸图片本体中加入清晰可见的www.pindoux.cn 水印。

水印不得被裁剪、遮挡、模糊或缩小到不可辨认。合作伙伴不得把像素乐园图纸清洗成自有公共图库内容，不得删除、隐藏或篡改meta.website、meta.copyright、meta.displayPolicy、meta.contentHash 或meta.licenseFingerprint。

错误码

调用示例

curl

curl -X POST "https://www.pindoux.cn/api/partner/pattern-import" \
  -H "Content-Type: application/json" \
  -H "X-Partner-Key: pdx_partner_live_xxx" \
  --data '{"importKey":"PDX-AAAA-BBBB-CCCC-DDDD-EEEE"}'

Node.js fetch

const response = await fetch("https://www.pindoux.cn/api/partner/pattern-import", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Partner-Key": process.env.PINGDOU_PARTNER_API_KEY
  },
  body: JSON.stringify({ importKey: "PDX-AAAA-BBBB-CCCC-DDDD-EEEE" })
});

const payload = await response.json();
if (!response.ok) throw new Error(payload.error || `HTTP ${response.status}`);

const expectedCells = payload.pattern.grid.width * payload.pattern.grid.height;
if (payload.pattern.gridData.length !== expectedCells) {
  throw new Error("图纸格子数据长度不匹配");
}

if (payload.pattern.grid.width > device.maxGridWidth || payload.pattern.grid.height > device.maxGridHeight) {
  throw new Error("当前设备画布尺寸不足，无法导入该图纸");
}

缓存与授权

合作伙伴可为当前用户的当前授权图纸导入缓存成功响应，并使用 meta.contentHash 判断图纸内容是否一致。 缓存不得作为公共图纸库、批量分发源或转售数据源。用户更新 Import Key 或授权失效后，应停止继续使用旧 Key 对应缓存进行新导入。

安全规范

• 禁止批量枚举 Import Key。
• 禁止反编译、逆向工程、批量还原生成逻辑或算法仿制。
• 禁止使用图纸 JSON、样本或输出结果进行模型训练、二次训练、数据集构建、特征拟合或竞品算法开发。
• 未经用户授权或像素乐园书面许可，禁止缓存、复制、转售、公开传播、批量分发或向第三方提供图纸 JSON。
• 禁止删除、隐藏、篡改 meta.contentHash、meta.licenseFingerprint 或其他来源追踪字段。

联调清单

1. 已通过像素乐园授权申请，并拿到 Partner API Key。
2. 合作伙伴后端保存 Partner API Key，客户端只收集 Import Key。
3. 正常请求返回 200，且 gridData.length === width * height。
4. 已校验 grid.width 和 grid.height 不超过自身设备或客户端画布上限。
5. 已处理矩形图纸、超大图纸和只支持正方形设备的异常提示。
6. 个人图库保存时保留 meta 来源字段。
7. 公共图库展示时文字区显示 来源：像素乐园，图片本体显示 www.pindoux.cn 水印。
8. 错误 Partner API Key 返回 401。
9. 错误 Import Key 格式返回 400。
10. 不存在 Import Key 返回 404。
11. 已作废 Import Key 返回 403。