Cloud Module (Cloud Save/Restore)

The Cloud module encapsulates cloud storage for generator states, reusing the existing backend interface /ai/v5/artimind/generator and achieving data isolation across multiple applications via the category: appKey field.

API List

Method	Return Value	Description
sdk.cloud.save(options)	Promise<CloudSaveResult>	Save to cloud (automatically determines create/update)
sdk.cloud.restore(id)	Promise<CloudRecord>	Restore cloud data by ID
sdk.cloud.delete(id)	Promise<void>	Delete cloud record

Detailed Usage

Save

const result = await sdk.cloud.save({
  title: 'My Work',                    // Optional, defaults to 'Draft'
  snapshot: {                           // Required, JSON-serializable plain object
    brightness: 0.5,
    contrast: 1.2,
    dotSize: 3,
  },
  cover: canvasElement,                 // Optional, Canvas / data URL / HTTP URL
  originImage: 'https://example.com/my-image.jpg',  // Optional, HTTP URL stored directly without re-uploading
  id: 123,                             // Optional, updates if provided, creates if not
})

console.log(result.id)     // Record ID
console.log(result.isNew)  // true=Created / false=Updated

Restore

const data = await sdk.cloud.restore(123)
// data: {
//   id: 123,
//   title: 'My Work',
//   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,
// }

// Restore application state
applyState(data.snapshot)
if (data.originImageUrl) {
  loadImage(data.originImageUrl)
}

Delete

await sdk.cloud.delete(123)

CloudSaveOptions Parameters

Parameter	Type	Required	Description
title	string	No	Record title, defaults to 'Draft'
snapshot	Record<string, unknown>	Yes	Application state snapshot, must be JSON-serializable
cover	HTMLCanvasElement | string | null	No	Cover image (Canvas / data URL / HTTP URL)
originImage	HTMLCanvasElement | string | null	No	Original material image (Canvas / data URL / HTTP URL)
id	number | null	No	Record ID; updates if provided, creates if not

Cover and Original Image Upload Details

• Cover Upload:
  • HTMLCanvasElement → toDataURL → Upload to OSS
  • data URL → Convert to File → Upload to OSS
  • HTTP/HTTPS URL → Stored directly without re-uploading
  • Tainted canvases throw a SecurityError; the SDK handles this gracefully and leaves the cover field empty.
  • Update operations reuse a fixed filename (Record ID as filename) to avoid redundant files.
• Original Image Upload:
  • HTMLCanvasElement → toDataURL → Upload to OSS
  • data URL → Convert to File → Upload to OSS
  • HTTP/HTTPS URL → Stored directly without re-uploading
• OSS Bucket: xtool-aimake-generator

Typical Auto-Save Pattern

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

// Restore on page initialization
if (currentId) {
  const data = await sdk.cloud.restore(currentId)
  applyState(data.snapshot)
  if (data.originImageUrl) loadImage(data.originImageUrl)
}

// Debounced auto-save
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)
}

Backend Data Structure Mapping

The request body constructed internally by the SDK's save() method is fully compatible with the existing backend:

{
  "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
  }
}

When restore() returns, the SDK automatically extracts info.originImageUrl to the top level, and the remaining fields are returned as snapshot.