@qjp88995/provider-client 0.3.0 → 0.4.0

package/src/index.ts

@@ -9,6 +9,28 @@ export {
   ProviderClientError,
   type ProviderClientErrorCode,
 } from './errors.js';
+export {
+  createImageGenerator,
+  type CreateImageGeneratorInput,
+  fitImageSize,
+  type GeneratedImage,
+  type GenerateImageInput,
+  type GenerateImageOutcome,
+  IMAGE_ADAPTERS,
+  IMAGE_FORMATS,
+  IMAGE_KINDS,
+  type ImageAdapter,
+  type ImageConnection,
+  type ImageFormat,
+  type ImageGenerator,
+  type ImageKind,
+  type ImageSize,
+  type ImageTraits,
+  ImageUpstreamError,
+  type ImageUsage,
+  isImageKind,
+  type ReferenceImage,
+} from './image/index.js';
 export {
   classifyCode,
   createJustOne,
@@ -88,6 +110,7 @@ export {
 } from './model-handle.js';
 export {
   type FetchForOptions,
+  type ImageModelOptions,
   type JustOneClientOptions,
   type MediaOptions,
   ProviderClient,
@@ -97,6 +120,7 @@ export {
 export { toProviderClientError } from './to-error.js';
 export {
   type CatalogEndpoint,
+  type CatalogImageModel,
   type CatalogModel,
   type CatalogResponse,
   type CatalogVendor,
@@ -104,6 +128,9 @@ export {
   type CenterErrorCode,
   ENDPOINT_PROTOCOLS,
   type EndpointProtocol,
+  IMAGE_CAPABILITIES,
+  type ImageCapability,
+  type ImagePricing,
   LLM_CAPABILITIES,
   LLM_PROTOCOLS,
   type LlmCapability,

package/src/provider-client.ts

@@ -1,5 +1,11 @@
 import { type CenterFetchOptions, createCenterFetch } from './center-fetch.js';
 import { errorFromResponse, ProviderClientError } from './errors.js';
+import {
+  createImageGenerator,
+  IMAGE_ADAPTERS,
+  type ImageGenerator,
+  isImageKind,
+} from './image/index.js';
 import {
   createJustOne,
   type JustOne,
@@ -51,8 +57,7 @@ export interface MediaOptions<
 
 /** `ProviderClient.justOne` 的选项。 */
 export interface JustOneClientOptions<C = unknown>
-  extends FetchForOptions,
-    Pick<JustOneOptions<C>, 'onAttempt'> {}
+  extends FetchForOptions, Pick<JustOneOptions<C>, 'onAttempt'> {}
 
 /** `ProviderClient.fetchFor` 的选项。 */
 export interface FetchForOptions {
@@ -64,6 +69,9 @@ export interface FetchForOptions {
   onCredential?: (ref: string) => void;
 }
 
+/** `ProviderClient.imageModel` 的选项。 */
+export type ImageModelOptions = FetchForOptions;
+
 export interface ProviderClientOptions {
   /** 中心的根地址，如 `https://provider.example.com`。 */
   centerUrl: string;
@@ -229,6 +237,71 @@ export class ProviderClient implements ModelResolver {
     });
   }
 
+  /**
+   * 一个生图模型（适配器在本包，请求经中心透传、中心注入 key）。地址取自这家的对话端点（生图模型没有自己的协议，
+   * 用哪个端点由这家的生图适配器定）。**一次 `generate` 出一张**；要几张就并发几次。
+   * - 目录里没有这家 → `unknown_vendor`；这家没有这个生图模型（或停用了）→ `unknown_model`；
+   *   这个版本的 client 没有这家的生图适配器 → `unsupported_vendor_kind`；这家没有启用的对应端点 → `protocol_unavailable`。
+   * - 生成时中心自己报的错是 `ProviderClientError`，厂商的失败是 `ImageUpstreamError`（`retryable`、`contentFiltered`）。
+   * - 用量（张数、参考图数）在结果里，单价在目录里（`catalog()` 的 `imageModels[].pricing`），钱由 APP 自己算。
+   * 目录只在创建时查一次。
+   */
+  async imageModel(
+    ref: ModelRef,
+    options: ImageModelOptions = {}
+  ): Promise<ImageGenerator> {
+    const vendor = (await this.catalog()).vendors.find(
+      v => v.slug === ref.vendor
+    );
+    if (!vendor) {
+      throw new ProviderClientError(
+        'unknown_vendor',
+        `vendor "${ref.vendor}" is not in the catalog`,
+        null
+      );
+    }
+    const model = vendor.imageModels.find(m => m.modelId === ref.modelId);
+    if (!model) {
+      throw new ProviderClientError(
+        'unknown_model',
+        `image model "${ref.modelId}" is not in the catalog of vendor "${ref.vendor}"`,
+        null
+      );
+    }
+    if (!isImageKind(vendor.kind)) {
+      throw new ProviderClientError(
+        'unsupported_vendor_kind',
+        `vendor kind "${vendor.kind}" has no image generation adapter`,
+        null
+      );
+    }
+    const protocol = IMAGE_ADAPTERS[vendor.kind].endpointProtocol;
+    const endpoint = vendor.endpoints.find(e => e.protocol === protocol);
+    if (!endpoint) {
+      throw new ProviderClientError(
+        'protocol_unavailable',
+        `vendor "${ref.vendor}" has no ${protocol} endpoint (image generation uses its base URL)`,
+        null
+      );
+    }
+    const fetch = createCenterFetch({
+      centerUrl: this.center,
+      apiKey: this.options.apiKey,
+      vendor: vendor.slug,
+      baseUrls: vendor.endpoints.map(e => e.baseUrl),
+      affinity: options.affinity,
+      pin: options.pin,
+      onCredential: options.onCredential,
+      fetch: this.send,
+    });
+    return createImageGenerator({
+      kind: vendor.kind,
+      modelId: model.modelId,
+      referenceImages: model.capabilities.includes('reference-image'),
+      connection: { baseUrl: endpoint.baseUrl, fetch },
+    });
+  }
+
   /**
    * 某家厂商的媒体解析（适配器在本包，请求经中心透传、中心注入 key）：智谱的文件解析 / 语音转写（地址取自这家的
    * `media` 端点）、BibiGPT 的视频链接解析（它唯一的 `http` 端点）。
@@ -372,6 +445,8 @@ export class ProviderClient implements ModelResolver {
     }
     if (!res.ok) throw await errorFromResponse(res);
     const body = (await res.json()) as CatalogResponse;
+    // 中心 2026-11 之前没有 `imageModels`：补成空数组，后面不用到处判空。
+    for (const v of body.vendors) v.imageModels ??= [];
     this.cached = {
       etag: res.headers.get('etag'),
       body,

package/src/types.ts

@@ -33,6 +33,10 @@ export type VendorCategory = (typeof VENDOR_CATEGORIES)[number];
 export const LLM_CAPABILITIES = ['vision', 'video', 'reasoning'] as const;
 export type LlmCapability = (typeof LLM_CAPABILITIES)[number];
 
+/** 生图模型的能力。`reference-image` = 能带参考图（图生图 / 改图）。 */
+export const IMAGE_CAPABILITIES = ['reference-image'] as const;
+export type ImageCapability = (typeof IMAGE_CAPABILITIES)[number];
+
 /** 厂商类型。`llm` 类别的每一种对应一个适配器（`VENDOR_ADAPTERS`）；bibigpt / justone 没有。 */
 export const VENDOR_KINDS = [
   'openai',
@@ -91,7 +95,10 @@ export interface CatalogVendor {
   /** 非 `llm` 的厂商没有模型，接入方只拿它的端点经中心透传。 */
   category: VendorCategory;
   endpoints: CatalogEndpoint[];
+  /** 对话模型。 */
   models: CatalogModel[];
+  /** 生图模型（中心 2026-11 起有；读目录时缺了按空数组补上）。 */
+  imageModels: CatalogImageModel[];
 }
 
 export interface CatalogEndpoint {
@@ -111,6 +118,20 @@ export interface CatalogModel {
   pricing: ModelPricing | null;
 }
 
+/** 生图的单价（每张，十进制字符串）。 */
+export interface ImagePricing {
+  currency: string;
+  perImage: string;
+}
+
+export interface CatalogImageModel {
+  /** 厂商侧的模型名（请求体里的 `model`）。 */
+  modelId: string;
+  displayName: string;
+  capabilities: ImageCapability[];
+  pricing: ImagePricing | null;
+}
+
 /** 中心的错误码（响应体 `{ code, message }`）。 */
 export const CENTER_ERROR_CODES = [
   'unauthorized',