@dickpy/dsh-imagegen 1.2.2 → 1.3.0

package/src/model-catalog.ts

@@ -0,0 +1,98 @@
+/**
+ * Model catalog: protocol-family detection and capability annotation shared by
+ * the engine, the settings card, and the panel. Known id patterns map onto the
+ * OpenAI-compatible image protocol families this plugin shapes requests for;
+ * anything unrecognized falls back to the generic OpenAI protocol (best
+ * effort) and is flagged as unknown so the UI can warn without blocking.
+ *
+ * Framework-free (pure data + regex), safe for the client bundle to inline.
+ */
+
+export type ModelFamily = 'gpt-image' | 'dall-e' | 'grok' | 'nanobanana' | 'seedream' | 'unknown'
+
+/** Capability/identity annotation for one model id. */
+export interface ModelCatalogEntry {
+  /** Family the request is shaped for. */
+  family: ModelFamily
+  /** Short badge label (en). */
+  label: string
+  /** Short badge label (zh). */
+  labelZh: string
+  /** Whether the family is known (false = best-effort OpenAI protocol). */
+  known: boolean
+  /** Whether the family supports image-to-image edits. */
+  supportsEdit: boolean
+  /** Whether the family natively takes aspect-ratio dials. */
+  supportsAspectRatio: boolean
+  /** Quality tiers the family interprets natively. */
+  qualityTiers: string[]
+}
+
+const ENTRIES: Record<Exclude<ModelFamily, 'unknown'>, Omit<ModelCatalogEntry, 'family'>> = {
+  'gpt-image': {
+    label: 'gpt-image',
+    labelZh: 'GPT 图像',
+    known: true,
+    supportsEdit: true,
+    supportsAspectRatio: false,
+    qualityTiers: ['1K', '2K', '4K'],
+  },
+  'dall-e': {
+    label: 'DALL·E',
+    labelZh: 'DALL·E',
+    known: true,
+    supportsEdit: true,
+    supportsAspectRatio: false,
+    qualityTiers: ['auto'],
+  },
+  grok: {
+    label: 'grok',
+    labelZh: 'Grok',
+    known: true,
+    supportsEdit: true,
+    supportsAspectRatio: true,
+    qualityTiers: ['1K', '2K'],
+  },
+  nanobanana: {
+    label: 'nanobanana',
+    labelZh: 'Nano Banana',
+    known: true,
+    supportsEdit: true,
+    supportsAspectRatio: true,
+    qualityTiers: ['1K', '2K', '4K'],
+  },
+  seedream: {
+    label: 'seedream',
+    labelZh: 'Seedream',
+    known: true,
+    supportsEdit: true,
+    supportsAspectRatio: true,
+    qualityTiers: ['1K', '2K'],
+  },
+}
+
+/** Official Gemini image ids served by Nano Banana gateways. */
+const NANOBANANA_GEMINI_IDS = new Set([
+  'gemini-3-pro-image',
+  'gemini-3-pro-image-preview',
+  'gemini-3.1-flash-image',
+  'gemini-3.1-flash-image-preview',
+  'gemini-3.1-flash-lite-image',
+  'gemini-2.5-flash-image',
+])
+
+/** Classify one upstream model id into its request-shaping family. */
+export function describeModel(model: string): ModelCatalogEntry {
+  const id = model.trim()
+  if (/^gpt-image/i.test(id)) return { family: 'gpt-image', ...ENTRIES['gpt-image'] }
+  if (/^dall-e/i.test(id)) return { family: 'dall-e', ...ENTRIES['dall-e'] }
+  if (/^grok-imagine(?:-|$)/.test(id)) return { family: 'grok', ...ENTRIES.grok }
+  if (/^nanobanana/i.test(id) || NANOBANANA_GEMINI_IDS.has(id)) return { family: 'nanobanana', ...ENTRIES.nanobanana }
+  if (/^(?:doubao-)?seedream/i.test(id)) return { family: 'seedream', ...ENTRIES.seedream }
+  return { family: 'unknown', label: 'unknown', labelZh: '未知协议', known: false, supportsEdit: true, supportsAspectRatio: false, qualityTiers: [] }
+}
+
+/** The family a model id routes its request through. */
+export function modelFamily(model: string): ModelFamily {
+  return describeModel(model).family
+}

package/src/presets.ts

@@ -0,0 +1,63 @@
+/**
+ * Built-in provider catalog (presets). A preset is an official or well-known
+ * OpenAI-compatible endpoint with its known model list, so the user only fills
+ * in the API key. The list ships with the package and is served to the
+ * settings card through a host route, so it can later be refreshed online like
+ * the template library.
+ *
+ * Framework-free (pure data), safe for the host routes to serve directly.
+ */
+
+import type { ModelMapping } from './protocol.ts'
+
+/** One built-in provider the settings card can instantiate a channel from. */
+export interface PresetProvider {
+  /** Stable preset id stored on channels created from it ('' = custom). */
+  id: string
+  /** Display name shown in the picker (also the channel's default name). */
+  name: string
+  /** Official base URL prefilled into the channel. */
+  apiUrl: string
+  /** One-line description shown in the picker. */
+  hint: string
+  /** Known model list prefilled into the channel's model catalog. */
+  models: ModelMapping[]
+}
+
+export const IMAGE_PRESETS: PresetProvider[] = [
+  {
+    id: 'volc-ark-seedream',
+    name: '字节 · 火山方舟（Seedream）',
+    apiUrl: 'https://ark.cn-beijing.volces.com/api/v3',
+    hint: '字节跳动官方 Seedream 文生图/图生图入口',
+    models: [
+      { alias: 'seedream-5.0-pro', id: 'seedream-5.0-pro' },
+      { alias: 'seedream-5.0', id: 'seedream-5.0' },
+      { alias: 'seedream-4.0', id: 'seedream-4.0' },
+    ],
+  },
+  {
+    id: 'openai-official',
+    name: 'OpenAI 官方',
+    apiUrl: 'https://api.openai.com/v1',
+    hint: 'OpenAI 官方接口：gpt-image-2 / dall-e-3',
+    models: [
+      { alias: 'gpt-image-2', id: 'gpt-image-2' },
+      { alias: 'dall-e-3', id: 'dall-e-3' },
+    ],
+  },
+  {
+    id: 'xai-grok',
+    name: 'xAI（Grok）',
+    apiUrl: 'https://api.x.ai/v1',
+    hint: 'xAI 官方接口：Grok Imagine 系列',
+    models: [
+      { alias: 'grok-imagine-image', id: 'grok-imagine-image' },
+    ],
+  },
+]
+
+/** Look up one built-in provider by id. */
+export function presetById(id: string): PresetProvider | undefined {
+  return IMAGE_PRESETS.find(preset => preset.id === id)
+}

package/src/protocol.ts

@@ -8,7 +8,7 @@
 export const IMAGEGEN_SETTINGS_NAMESPACE = 'dsh-imagegen'
 
 /** Published package version shared by the host updater and the client UI. */
-export const PLUGIN_VERSION = '1.2.2'
+export const PLUGIN_VERSION = '1.3.0'
 
 /** Same-origin route family (loopback-only, mirroring the dsh-ssh fence). */
 export const SETTINGS_API = {
@@ -30,6 +30,19 @@ export const IMAGE_MODEL_API = {
   models: '/api/dsh-imagegen/image-models',
 } as const
 
+/** Host-served built-in provider catalog (channels the user can instantiate). */
+export const PRESETS_API = '/api/dsh-imagegen/presets' as const
+
+/** Loopback-only image reader for Agent tool-result previews. */
+export const AGENT_IMAGE_API = '/api/dsh-imagegen/agent-image' as const
+
+/**
+ * Host-computed per-channel usage counters (generation-count badges in the
+ * settings card): entries are tallied from the persisted history and gallery
+ * by channel + model alias.
+ */
+export const USAGE_API = '/api/dsh-imagegen/usage' as const
+
 /** Host-resident generation queue endpoints. */
 export const TASK_API = {
   submit: '/api/dsh-imagegen/tasks/submit',
@@ -136,20 +149,27 @@ export interface TemplateRefreshResult {
 /** Generation modes. */
 export type GenerateMode = 'text' | 'edit'
 
-/** A client 鈫?host generate request (what the panel collects). */
+/** A client → host generate request (what the panel collects). */
 export interface GenerateRequest {
   /** text-to-image (images/generations) or image-to-image (images/edits). */
   mode: GenerateMode
-  /** Upstream model name, e.g. gpt-image-2. */
+  /**
+   * User-facing model name (an alias from the channel's model catalog). The
+   * host maps it onto the configured channel and fills `upstream` with the
+   * real id before the engine sees it.
+   */
   model: string
   /** The prompt. Upstream providers may impose their own length limits. */
   prompt: string
   /** Canvas size as an aspect ratio: 'auto' or e.g. '1:1' / '16:9' / '21:9'.
-   *  The host maps it onto each model's own vocabulary (aspect_ratio for Grok,
-   *  the closest pixel size for OpenAI-compatible endpoints). */
+   *  The host maps it onto each model's own vocabulary (aspect_ratio for Grok
+   *  and Nano Banana, resolution-tier size for Seedream, the closest pixel size for
+   *  OpenAI-compatible endpoints). */
   size: string
   /** Clarity tier: 'auto' | '1k' | '2k' | '4k'. The host maps it onto the
-   *  model's own vocabulary (resolution for Grok, quality for OpenAI). */
+   *  model's own vocabulary (resolution for Grok, image_size for Nano Banana,
+   *  and size for Seedream,
+   *  Nano Banana, quality for OpenAI). */
   quality: string
   /** Number of images, 1-4. */
   n: number
@@ -163,6 +183,14 @@ export interface GenerateRequest {
   image?: string
   /** Original reference-image name, retained in the history entry. */
   refName?: string
+  /** Channel this request targets (the host falls back to the default when
+   *  absent, and re-routes by model alias when the alias lives elsewhere). */
+  channelId?: string
+  /** Channel display name snapshot, kept on the history entry (host-filled). */
+  channel?: string
+  /** Upstream model id actually sent to the gateway (host-filled from the
+   *  alias mapping; defaults to `model` when absent). */
+  upstream?: string
 }
 
 /** One generated image, normalized host-side to base64 so the browser never
@@ -185,6 +213,45 @@ export interface GenerateResult {
   historyError?: string
 }
 
+/**
+ * One model mapping in a channel's catalog: the display alias the user, the
+ * panel, and the Agent see, and the upstream model id actually sent to the
+ * gateway. The alias defaults to the upstream id but can be renamed freely.
+ */
+export interface ModelMapping {
+  /** User-facing model name (defaults to the upstream id). */
+  alias: string
+  /** Upstream model id sent to the gateway. */
+  id: string
+}
+
+/**
+ * One configured image channel (provider). Secrets never live here — the API
+ * key is stored at `channelSecrets.<channelId>` in the settings document so
+ * whole-array writes can never clobber keys the user did not re-enter.
+ */
+export interface ChannelConfig {
+  /** Stable channel id (the channelSecrets dict is keyed by it). */
+  id: string
+  /** Preset provider id this channel was created from ('' = custom). */
+  preset: string
+  /** Display name shown in the list, the panel, and Agent guidance. */
+  name: string
+  /** OpenAI-compatible base URL. */
+  apiUrl: string
+  /** The channel's model catalog (alias → upstream id). */
+  models: ModelMapping[]
+}
+
+/** One built-in provider as the settings card consumes it. */
+export interface PresetProviderView {
+  id: string
+  name: string
+  apiUrl: string
+  hint: string
+  models: ModelMapping[]
+}
+
 export type GenerationTaskStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled'
 
 export interface GenerationTask {
@@ -233,6 +300,10 @@ export interface HistoryEntry {
   refName?: string
   /** User-managed gallery labels (unused by history entries). */
   tags?: string[]
+  /** Channel id snapshot (usage counters key by it for new entries). */
+  channelId?: string
+  /** Channel display name snapshot (survives channel deletion). */
+  channel?: string
 }
 
 /** A history entry the client submits for persistence (images still carry base64). */
@@ -248,4 +319,8 @@ export interface HistoryEntryInput {
   n: number
   images: GeneratedImage[]
   refName?: string
+  /** Channel id snapshot, tallied by the usage endpoint. */
+  channelId?: string
+  /** Channel display name snapshot (survives channel deletion). */
+  channel?: string
 }

package/src/routes.ts

@@ -8,16 +8,18 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { randomUUID } from 'node:crypto'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import type { ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment'
 import { SettingsConflictError, settingsNamespace, type SettingsDescriptor } from '@deepseek-ai/dsh-settings'
 import type { UpstreamConfig } from './engine.ts'
 import { enhancePrompt, listOpenAIModels, listPromptModels, type PromptModelConfig } from './prompt-enhancer.ts'
 import { normalizeImageModels } from './image-models.ts'
-import { ImageGenerationRuntime } from './generation-runtime.ts'
+import { ImageGenerationRuntime, type ChannelsView } from './generation-runtime.ts'
 import { appendHistory, clearHistory, listHistory, readHistoryImage, removeHistory } from './history-store.ts'
 import { appendGallery, clearGallery, listGallery, readGalleryImage, removeGallery, updateGalleryTags } from './gallery-store.ts'
 import { listTemplates, readTemplateImage, refreshTemplates } from './templates-store.ts'
 import { checkForUpdate, CURRENT_VERSION, installUpdate } from './updater.ts'
-import { GALLERY_API, GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, IMAGE_MODEL_API, PROMPT_ENHANCE_API, SETTINGS_API, TASK_API, TEMPLATES_API, UPDATE_API, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput, type TemplateListResult, type TemplateRefreshResult } from './protocol.ts'
+import { IMAGE_PRESETS } from './presets.ts'
+import { AGENT_IMAGE_API, GALLERY_API, GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, IMAGE_MODEL_API, PRESETS_API, PROMPT_ENHANCE_API, SETTINGS_API, TASK_API, TEMPLATES_API, UPDATE_API, USAGE_API, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput, type ModelMapping, type PresetProviderView, type TemplateListResult, type TemplateRefreshResult } from './protocol.ts'
 
 /** Cap on JSON request bodies (settings ops and generate payloads are small). */
 const MAX_JSON_BODY_BYTES = 24 * 1024 * 1024
@@ -36,12 +38,18 @@ export interface SettingsSeam {
 export interface ImageGenRoutesDeps {
   /** The settings seam (namespace storage). */
   settings: SettingsSeam
-  /** Resolve the current upstream config (composition entry + settings). */
+  /** Resolve the current upstream config (legacy single-endpoint path). */
   resolve: () => UpstreamConfig
+  /** Resolve the current channel view (the channel-aware path). */
+  resolveChannels?: () => ChannelsView
   /** Resolve the optional chat-model configuration for prompt enhancement. */
   resolvePrompt?: () => PromptModelConfig
-  /** Models explicitly selected for this image API endpoint. */
+  /** Models explicitly selected for this image API endpoint (legacy path). */
   resolveImageModels?: () => string[]
+  /** Host attachment storage used by Agent tool-result previews. */
+  attachments?: {
+    readImage: (ref: ImageAttachmentRef) => Promise<{ ref: ImageAttachmentRef; data: Uint8Array }>
+  }
   /** Overrideable history backend, primarily for host integration tests. */
   history?: {
     list: () => Promise<HistoryEntry[]>
@@ -135,6 +143,7 @@ function parseGenerateRequest(body: Record<string, unknown>): GenerateRequest |
     detail: typeof body.detail === 'string' ? body.detail : '',
     ...typeof body.image === 'string' && body.image !== '' ? { image: body.image } : {},
     ...typeof body.refName === 'string' && body.refName !== '' ? { refName: body.refName } : {},
+    ...typeof body.channelId === 'string' && body.channelId !== '' ? { channelId: body.channelId } : {},
   }
 }
 
@@ -172,6 +181,8 @@ function parseHistoryEntryInput(body: Record<string, unknown>): HistoryEntryInpu
     n: entry.n,
     images,
     ...typeof entry.refName === 'string' ? { refName: entry.refName } : {},
+    ...typeof entry.channelId === 'string' ? { channelId: entry.channelId } : {},
+    ...typeof entry.channel === 'string' ? { channel: entry.channel } : {},
   }
 }
 
@@ -188,6 +199,38 @@ function imageFileFrom(rawUrl: string | undefined, basePath: string): string | u
   return decodeURIComponent(pathname.slice(basePath.length + 1))
 }
 
+/** Parse the durable image reference carried by an Agent tool-result view. */
+function agentImageRefFrom(rawUrl: string | undefined): ImageAttachmentRef | undefined {
+  if (rawUrl === undefined) return undefined
+  let url: URL
+  try {
+    url = new URL(rawUrl, 'http://localhost')
+  } catch {
+    return undefined
+  }
+  if (url.pathname !== AGENT_IMAGE_API) return undefined
+  const attachmentId = url.searchParams.get('attachment_id') ?? ''
+  const mediaType = url.searchParams.get('media_type') ?? ''
+  const bytes = Number(url.searchParams.get('bytes'))
+  const width = Number(url.searchParams.get('width'))
+  const height = Number(url.searchParams.get('height'))
+  if (attachmentId === '' || !isImageMediaType(mediaType)
+    || !Number.isSafeInteger(bytes) || bytes < 1
+    || !Number.isSafeInteger(width) || width < 1
+    || !Number.isSafeInteger(height) || height < 1) return undefined
+  return {
+    attachmentId: attachmentId as ImageAttachmentRef['attachmentId'],
+    mediaType,
+    bytes,
+    width,
+    height,
+  }
+}
+
+function isImageMediaType(value: string): value is ImageMediaType {
+  return value === 'image/png' || value === 'image/jpeg' || value === 'image/webp' || value === 'image/gif'
+}
+
 /** Project one settings descriptor onto the bridge wire view. */
 function toView(descriptor: SettingsDescriptor): Record<string, unknown> {
   return {
@@ -240,15 +283,51 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
   }
   const resolvePrompt = deps.resolvePrompt ?? (() => ({ apiUrl: '', apiKey: '', model: '' }))
   const resolveImageModels = deps.resolveImageModels ?? (() => normalizeImageModels(undefined))
-  const parseConfiguredRequest = (body: Record<string, unknown>): GenerateRequest | undefined => {
-    const request = parseGenerateRequest(body)
-    if (request === undefined) return undefined
-    const models = normalizeImageModels(resolveImageModels())
-    const model = request.model.trim() === '' ? models[0] : request.model.trim()
-    if (!models.includes(model)) throw new Error(`image model "${model}" is not configured; choose one of: ${models.join(', ')}`)
-    return { ...request, model }
+
+  /** The current channel view: the channel-aware resolver, or a synthesized
+   *  single default channel from the legacy flat upstream config (tests and
+   *  older hosts). */
+  const channelViewOf = (): ChannelsView => {
+    if (deps.resolveChannels !== undefined) return deps.resolveChannels()
+    const upstream = deps.resolve()
+    const models: ModelMapping[] = normalizeImageModels(resolveImageModels()).map(id => ({ alias: id, id }))
+    if (upstream.apiUrl.trim() === '' && models.length === 0) return { channels: [], defaultChannelId: '' }
+    return {
+      channels: [{ id: 'default', preset: '', name: '默认渠道', apiUrl: upstream.apiUrl, apiKey: upstream.apiKey, models }],
+      defaultChannelId: 'default',
+    }
+  }
+  const runtime = deps.runtime ?? new ImageGenerationRuntime(channelViewOf, history)
+
+  /** Resolve an alias (or the channel fallback) into a concrete generation
+   *  request: picks the channel (explicit then default), maps alias → upstream
+   *  id, and fills the channel snapshot kept on history entries. */
+  const resolveChannelRequest = (request: GenerateRequest): { ok: true; request: GenerateRequest } | { ok: false; code: string; message: string } => {
+    const view = channelViewOf()
+    if (view.channels.length === 0) {
+      return { ok: false, code: 'no-channels', message: '尚未配置任何渠道：请先在「设置 → 插件 → AI 生图」添加渠道并填写 API 地址与密钥' }
+    }
+    const explicit = view.channels.find(candidate => candidate.id === request.channelId)
+    const defaults = view.channels.find(candidate => candidate.id === view.defaultChannelId) ?? view.channels[0]
+    const target = explicit ?? defaults
+    const asked = request.model.trim()
+    if (asked === '') {
+      const alias = target?.models[0]?.alias ?? ''
+      if (alias === '') {
+        return { ok: false, code: 'no-models', message: `渠道「${target?.name ?? ''}」尚未配置模型，请先在设置中添加` }
+      }
+      const mapping = target!.models.find(model => model.alias === alias)!
+      return { ok: true, request: { ...request, model: alias, upstream: mapping.id, channelId: target!.id, channel: target!.name } }
+    }
+    const hosting = view.channels.filter(channel => channel.models.some(model => model.alias === asked))
+    if (hosting.length === 0) {
+      const available = [...new Set(view.channels.flatMap(channel => channel.models.map(model => model.alias)))]
+      return { ok: false, code: 'image-model-not-configured', message: `模型「${asked}」未在任一渠道配置；可用模型：${available.join('、') || '（无）'}` }
+    }
+    const picked = target !== undefined && target.models.some(model => model.alias === asked) ? target : hosting[0]!
+    const mapping = picked.models.find(model => model.alias === asked)!
+    return { ok: true, request: { ...request, model: asked, upstream: mapping.id, channelId: picked.id, channel: picked.name } }
   }
-  const runtime = deps.runtime ?? new ImageGenerationRuntime(deps.resolve, history)
   const guard = (req: IncomingMessage, res: ServerResponse, method: string): boolean => {
     if (!isLoopbackRequest(req)) {
       writeJson(res, 403, { error: 'forbidden: loopback-only' })
@@ -262,19 +341,104 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
   }
 
   return [
+    // ------------------------------------ Agent tool-result image (prefix)
+    ...(deps.attachments === undefined ? [] : [{
+      kind: 'prefix' as const,
+      path: AGENT_IMAGE_API,
+      handler: async (req: IncomingMessage, res: ServerResponse) => {
+        if (!isLoopbackRequest(req)) {
+          writeJson(res, 403, { error: 'forbidden: loopback-only' })
+          return
+        }
+        if (req.method !== 'GET') {
+          writeJson(res, 405, { error: `method not allowed: ${req.method}` })
+          return
+        }
+        const ref = agentImageRefFrom(req.url)
+        if (ref === undefined) {
+          writeJson(res, 400, { error: 'invalid image reference' })
+          return
+        }
+        try {
+          const stored = await deps.attachments!.readImage(ref)
+          res.writeHead(200, {
+            'content-type': stored.ref.mediaType,
+            'content-length': stored.data.byteLength,
+            'cache-control': 'private, max-age=3600',
+          })
+          res.end(Buffer.from(stored.data))
+        } catch {
+          // Do not expose attachment-store details through the browser route.
+          writeJson(res, 404, { error: 'image attachment not found' })
+        }
+      },
+    } satisfies WebRoute]),
     // -------------------------------------------- image model discovery
+    // Accepts optional temporary per-channel credentials so the settings card
+    // can probe the endpoint the user is *typing* without saving first:
+    //   { channelId?, apiUrl?, apiKey? } — the channel's stored values are the
+    //   fallback, and the body's apiUrl/apiKey override them for this call.
     {
       kind: 'exact',
       path: IMAGE_MODEL_API.models,
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const view = channelViewOf()
+        const stored = view.channels.find(candidate => candidate.id === (typeof body?.channelId === 'string' ? body.channelId : undefined))
+          ?? view.channels.find(candidate => candidate.id === view.defaultChannelId)
+          ?? view.channels[0]
+        const upstream: UpstreamConfig = {
+          apiUrl: typeof body?.apiUrl === 'string' && body.apiUrl.trim() !== '' ? body.apiUrl.trim() : (stored?.apiUrl ?? ''),
+          apiKey: typeof body?.apiKey === 'string' && body.apiKey.trim() !== '' ? body.apiKey.trim() : (stored?.apiKey ?? ''),
+        }
         try {
-          writeJson(res, 200, { ok: true, models: await listOpenAIModels(deps.resolve()) })
+          writeJson(res, 200, { ok: true, models: await listOpenAIModels(upstream) })
         } catch (error) {
           writeJson(res, 200, { ok: false, code: 'image-models-failed', message: messageOf(error) })
         }
       },
     },
+    // ---------------------------------------------------------- presets
+    {
+      kind: 'exact',
+      path: PRESETS_API,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const presets: PresetProviderView[] = IMAGE_PRESETS.map(preset => ({
+          id: preset.id,
+          name: preset.name,
+          apiUrl: preset.apiUrl,
+          hint: preset.hint,
+          models: preset.models,
+        }))
+        writeJson(res, 200, { ok: true, presets })
+      },
+    },
+    // ----------------------------------------------------------- usage
+    {
+      kind: 'exact',
+      path: USAGE_API,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        try {
+          const entries = [...await history.list(), ...await gallery.list()]
+          // byChannel[channelId | 'name:<name>' | ''] → { alias: count }.
+          const byChannel: Record<string, Record<string, number>> = {}
+          const totals: Record<string, number> = {}
+          for (const entry of entries) {
+            const channelKey = entry.channelId !== undefined ? entry.channelId : (entry.channel !== undefined ? `name:${entry.channel}` : '')
+            const alias = entry.model
+            const bucket = byChannel[channelKey] ?? (byChannel[channelKey] = {})
+            bucket[alias] = (bucket[alias] ?? 0) + 1
+            totals[alias] = (totals[alias] ?? 0) + 1
+          }
+          writeJson(res, 200, { ok: true, usage: { byChannel, totals } })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'usage-failed', message: messageOf(error) })
+        }
+      },
+    },
     // ----------------------------------------------- prompt enhancement
     {
       kind: 'exact',
@@ -362,18 +526,18 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
         const body = await readJsonBody(req)
-        if (body === undefined) {
-          writeJson(res, 200, { ok: false, code: 'bad-request', message: 'unreadable JSON body' })
+        const parsed = body === undefined ? undefined : parseGenerateRequest(body)
+        if (parsed === undefined) {
+          writeJson(res, 200, { ok: false, code: 'bad-request', message: 'prompt is required' })
           return
         }
-        let request: GenerateRequest | undefined
-        try { request = parseConfiguredRequest(body) } catch (error) { writeJson(res, 200, { ok: false, code: 'image-model-not-configured', message: messageOf(error) }); return }
-        if (request === undefined) {
-          writeJson(res, 200, { ok: false, code: 'bad-request', message: 'prompt is required' })
+        const resolved = resolveChannelRequest(parsed)
+        if (!resolved.ok) {
+          writeJson(res, 200, { ok: false, code: resolved.code, message: resolved.message })
           return
         }
         try {
-          writeJson(res, 200, { ok: true, ...await runtime.run(request) })
+          writeJson(res, 200, { ok: true, ...await runtime.run(resolved.request) })
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error)
           const code = error instanceof Error && 'code' in error && typeof (error as { code?: unknown }).code === 'string'
@@ -389,10 +553,14 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
         const body = await readJsonBody(req)
-        let request: GenerateRequest | undefined
-        try { request = body === undefined ? undefined : parseConfiguredRequest(body) } catch (error) { writeJson(res, 200, { ok: false, code: 'image-model-not-configured', message: messageOf(error) }); return }
-        if (request === undefined) { writeJson(res, 200, { ok: false, code: 'bad-request', message: 'prompt is required' }); return }
-        writeJson(res, 200, { ok: true, task: runtime.queue.submit(request) })
+        const parsed = body === undefined ? undefined : parseGenerateRequest(body)
+        if (parsed === undefined) { writeJson(res, 200, { ok: false, code: 'bad-request', message: 'prompt is required' }); return }
+        const resolved = resolveChannelRequest(parsed)
+        if (!resolved.ok) {
+          writeJson(res, 200, { ok: false, code: resolved.code, message: resolved.message })
+          return
+        }
+        writeJson(res, 200, { ok: true, task: runtime.queue.submit(resolved.request) })
       },
     },
     {