Cloud 模块（云保存/恢复）

Cloud 模块封装了生成器状态的云端存储，复用现有后端接口 /ai/v5/artimind/generator，通过 category: appKey 字段实现多应用数据隔离。

API 列表

方法	返回值	说明
sdk.cloud.save(options)	Promise<CloudSaveResult>	保存到云端（自动判断新建/更新）
sdk.cloud.restore(id)	Promise<CloudRecord>	根据 ID 恢复云端数据
sdk.cloud.delete(id)	Promise<void>	删除云端记录

详细用法

保存

const result = await sdk.cloud.save({
  title: '我的作品',                    // 可选，默认 'Draft'
  snapshot: {                           // 必填，可 JSON 序列化的纯对象
    brightness: 0.5,
    contrast: 1.2,
    dotSize: 3,
  },
  cover: canvasElement,                 // 可选，Canvas / data URL / HTTP URL
  originImage: 'https://example.com/my-image.jpg',  // 可选，HTTP URL 直接存储不重复上传
  id: 123,                             // 可选，传入则更新，不传则新建
})

console.log(result.id)     // 记录 ID
console.log(result.isNew)  // true=新建 / false=更新

恢复

const data = await sdk.cloud.restore(123)
// data: {
//   id: 123,
//   title: '我的作品',
//   cover: 'https://oss.../cover.png',
//   snapshot: { brightness: 0.5, contrast: 1.2, dotSize: 3 },
//   originImageUrl: 'https://example.com/my-image.jpg',
//   createdAt: 1700000000,
//   updatedAt: 1700000100,
// }

// 恢复应用状态
applyState(data.snapshot)
if (data.originImageUrl) {
  loadImage(data.originImageUrl)
}

删除

await sdk.cloud.delete(123)

CloudSaveOptions 参数详解

参数	类型	必填	说明
title	string	否	记录标题，默认 'Draft'
snapshot	Record<string, unknown>	是	应用状态快照，必须可 JSON 序列化
cover	HTMLCanvasElement | string | null	否	封面图片（Canvas / data URL / HTTP URL）
originImage	HTMLCanvasElement | string | null	否	原始素材图片（Canvas / data URL / HTTP URL）
id	number | null	否	记录 ID，传入时更新，不传时新建

封面与原图上传细节

• 封面上传：
  • HTMLCanvasElement → toDataURL → 上传 OSS
  • data URL → 转 File → 上传 OSS
  • HTTP/HTTPS URL → 直接存储，不重复上传
  • 跨域画布（tainted canvas）会抛出 SecurityError，SDK 降级处理，封面字段留空
  • 更新操作复用固定文件名（记录 ID 作为文件名），避免产生冗余文件
• 原图上传：
  • HTMLCanvasElement → toDataURL → 上传 OSS
  • data URL → 转 File → 上传 OSS
  • HTTP/HTTPS URL → 直接存储，不重复上传
• OSS Bucket：xtool-aimake-generator

典型自动保存模式

const urlParams = new URLSearchParams(location.search)
let currentId = urlParams.get('id') ? Number(urlParams.get('id')) : null

// 页面初始化时恢复
if (currentId) {
  const data = await sdk.cloud.restore(currentId)
  applyState(data.snapshot)
  if (data.originImageUrl) loadImage(data.originImageUrl)
}

// 防抖自动保存
let saveTimer
function onStateChange(state) {
  clearTimeout(saveTimer)
  saveTimer = setTimeout(async () => {
    const result = await sdk.cloud.save({
      snapshot: state,
      cover: canvas,
      id: currentId || undefined,
    })
    if (result.isNew) {
      currentId = result.id
      history.replaceState(null, '', `?id=${result.id}`)
    }
  }, 1500)
}

后端数据结构对照

SDK 的 save() 方法内部构造的请求体与现有后端完全兼容：

{
  "title": "Draft",
  "category": "app_xxx",
  "cover": "https://oss.../cover.png",
  "info": {
    "version": "1.0.0",
    "originImageUrl": "https://oss.../origin.png",
    "brightness": 0.5,
    "contrast": 1.2
  }
}

restore() 返回时，SDK 自动将 info.originImageUrl 提取到顶层，其余字段作为 snapshot 返回。