Images¶

// List all assets visible to the user
const { data, total } = await spindle.images.list({ limit: 20, offset: 0 })

// List only assets created by this extension, but return small thumbnail URLs
const ownedThumbs = await spindle.images.list({
  onlyOwned: true,
  specificity: 'sm',
})

// Further narrow to a single character or chat
const characterImages = await spindle.images.list({
  onlyOwned: true,
  characterId: 'char-id',
  specificity: 'lg',
})

const chatImages = await spindle.images.list({
  onlyOwned: true,
  chatId: 'chat-id',
})

// Get a single asset DTO
const image = await spindle.images.get('image-id', {
  onlyOwned: true,
  specificity: 'sm',
})

// Upload raw bytes; the current extension is recorded automatically.
const uploaded = await spindle.images.upload({
  data: pngBytes,
  filename: 'cover.png',
  mime_type: 'image/png',
  owner_character_id: 'char-id',
  owner_chat_id: 'chat-id',
})

// Persist raw video bytes, including output from spindle.media.*, back into
// the shared asset store.
const storedVideo = await spindle.images.upload({
  data: videoBytes,
  filename: 'clip.mp4',
  mime_type: 'video/mp4',
  transcode_video_codec: 'h264',
  sidecar_video_codecs: ['hevc'],
})

// Batch upload — one IPC + host-side concurrency pool replaces N round-trips
const results = await spindle.images.uploadMany([
  { data: bytes1, filename: 'a.png', mime_type: 'image/png' },
  { data: bytes2, filename: 'b.png', mime_type: 'image/png' },
])
// Returns Array<{ id?: string; error?: string }> — per-item failures don't throw the batch

// Upload a data URL with ownership tags
const generated = await spindle.images.uploadFromDataUrl(dataUrl, {
  originalFilename: 'generated.png',
  owner_character_id: 'char-id',
  owner_chat_id: 'chat-id',
})

// Delete an asset
await spindle.images.delete(uploaded.id)

// Bulk delete by ID
const deletedCount = await spindle.images.deleteMany(imageIds)

{
  id: string
  original_filename: string
  mime_type: string                  // image/* or video/*
  width: number | null
  height: number | null
  has_thumbnail: boolean
  url: string                         // authenticated relative URL for this specificity
  specificity: 'full' | 'sm' | 'lg'   // size encoded into url
  owner_extension_identifier: string | null
  owner_character_id: string | null
  owner_chat_id: string | null
  created_at: number                  // unix epoch seconds
}