@cloudbase/ai 3.9.2 → 3.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/ai",
-  "version": "3.9.2",
+  "version": "3.10.0",
   "description": "cloudbase js sdk ai module",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -39,5 +39,5 @@
   "devDependencies": {
     "@cloudbase/adapter-interface": "~0.7.1"
   },
-  "gitHead": "518cce4fe49bb6af9f23d092cd5e350449220b08"
+  "gitHead": "adfb119f5756f8574c2042a6ad6e883d6468e689"
 }

package/src/AI.ts

@@ -42,11 +42,12 @@ class AI {
   }
 
   async handleResponseData(responseData: Promise<unknown> | ReadableStream<Uint8Array>, header?: Headers) {
-    const GO_TO_AI_TEXT = `${this.i18n.t('请检查调用方式，或前往云开发 AI+ 首页查看文档')}：https://tcb.cloud.tencent.com/dev#/ai`
+    const t = (key: string) => this.i18n?.t?.(key) ?? key
+    const GO_TO_AI_TEXT = `${t('请检查调用方式，或前往云开发 AI+ 首页查看文档')}：https://tcb.cloud.tencent.com/dev#/ai`
 
     const throwIfError = (json: unknown) => {
       if (typeof json === 'object' && json && 'code' in json && (json as any).code !== 'NORMAL') {
-        throw new Error(`${this.i18n.t('AI+ 请求出错，错误码')}：${(json as any).code}，${this.i18n.t('错误信息')}：${
+        throw new Error(`${t('AI+ 请求出错，错误码')}：${(json as any).code}，${t('错误信息')}：${
           (json as any).message
         }\n${GO_TO_AI_TEXT}\n${JSON.stringify(json, null, 2)}`,)
       }
@@ -69,7 +70,7 @@ class AI {
       // responseData 已经是解析后的 JSON 对象（如 Node.js 适配器非流式返回），直接检查错误码
       const json = responseData as unknown as Record<string, unknown>
       if (typeof json === 'object' && json && 'code' in json && json.code !== 'NORMAL') {
-        throw new Error(`${this.i18n.t('AI+ 请求出错，错误码')}：${json.code}，${this.i18n.t('错误信息')}：${
+        throw new Error(`${t('AI+ 请求出错，错误码')}：${json.code}，${t('错误信息')}：${
           json.message
         }\n${GO_TO_AI_TEXT}\n${JSON.stringify(json, null, 2)}`,)
       }
@@ -113,7 +114,7 @@ class AI {
     MODELS[name] = model
   }
 
-  createImageModel<T extends 'hunyuan-image' | (string & {})>(provider: T) {
+  createImageModel<T extends 'hunyuan-image' | 'cloudbase' | (string & {})>(provider: T) {
     return new models.DefaultImageModel<T>(this.modelRequest, this.aiBaseUrl, provider)
   }
 

package/src/models/image-model.ts

@@ -5,6 +5,8 @@ import type {
   HunyuanGenerateImageOutput,
   HunyuanARGenerateImageInput,
   HunyuanARGenerateImageOutput,
+  CloudbaseGenerateImageInput,
+  CloudbaseGenerateImageOutput,
   // HunyuanEditImageInput,
   // HunyuanEditImageOutput,
 } from '../type'
@@ -15,17 +17,35 @@ interface HunyuanImageGenerateFn {
   (input: HunyuanGenerateImageInput): Promise<HunyuanGenerateImageOutput>
 }
 
+type CloudbaseImageGenerateFn = (input: CloudbaseGenerateImageInput) => Promise<CloudbaseGenerateImageOutput>
+
+type GenerateImageInput =
+  | HunyuanARGenerateImageInput
+  | HunyuanGenerateImageInput
+  | CloudbaseGenerateImageInput
+
+type GenerateImageOutput =
+  | HunyuanARGenerateImageOutput
+  | HunyuanGenerateImageOutput
+  | CloudbaseGenerateImageOutput
+
 type GenerateImageFn<TProvider> = TProvider extends 'hunyuan-image'
   ? HunyuanImageGenerateFn
-  : (input: unknown) => Promise<unknown>
+  : TProvider extends 'cloudbase'
+    ? CloudbaseImageGenerateFn
+    : (input: unknown) => Promise<unknown>
 
 export class DefaultImageModel<TProvider extends string> {
+  /** 默认子路径，仅作为老 provider（''/hunyuan-image）的兜底，cloudbase 等新 provider 不支持兜底 */
   public defaultGenerateImageSubUrl = 'images/ar/generations'
 
   public generateImageSubUrlConfig: Record<string, Array<[RegExp, string]>> = {
     'hunyuan-image': [
       [/^hunyuan-image(-v[12](\..*)?)?$/, 'images/generations'],
     ],
+    cloudbase: [
+      [/^hy-image-v3\.5-preview$/, 'wand/hunyuan-image/v35-generation'],
+    ],
   }
 
   /** 生成图片 */
@@ -40,45 +60,68 @@ export class DefaultImageModel<TProvider extends string> {
   }
 
   /** generateImage 的实际实现 */
-  private async generateImageImpl(input: HunyuanARGenerateImageInput | HunyuanGenerateImageInput,): Promise<HunyuanARGenerateImageOutput | HunyuanGenerateImageOutput> {
-    // 当模型为 HY-Image-v3.0-I2I-ToB-v1.0.1 且 provider 为空或为 hunyuan-image 时校验参数
-    if (
-      typeof input === 'object' && input && 'model' in input && input.model === 'HY-Image-v3.0-I2I-ToB-v1.0.1' && (this.provider === '' || this.provider === 'hunyuan-image')
-    ) {
-      const typedInput = input
-      const imageUrls = typedInput.image_urls as string[] | undefined
-      const images = typedInput.images as string[] | undefined
-
-      if (imageUrls && imageUrls.length > 1) {
-        throw new InvalidParamsError(
-          '当模型为 HY-Image-v3.0-I2I-ToB-v1.0.1 时，image_urls 最多只能有 1 个元素',
-          'image_urls',
-        )
-      }
-      if (images && images.length > 1) {
-        throw new InvalidParamsError(
-          '当模型为 HY-Image-v3.0-I2I-ToB-v1.0.1 时，images 最多只能有 1 个元素',
-          'images',
-        )
-      }
-    }
-
-    let subUrl = this.defaultGenerateImageSubUrl
+  private async generateImageImpl(input: GenerateImageInput): Promise<GenerateImageOutput> {
+    this.validateInput(input)
 
-    if (typeof input === 'object' && input && 'model' in input && typeof input.model === 'string') {
-      const newSubUrl = this.getGenerateImageSubUrl(this.provider, input.model)
-      if (newSubUrl) subUrl = newSubUrl
-    }
+    const subUrl = this.resolveSubUrl(input)
 
     const res = (await this.req({
       url: this.getGenerateUrl(subUrl),
       data: input,
       stream: false,
-    })) as HunyuanARGenerateImageOutput | HunyuanGenerateImageOutput
+    })) as GenerateImageOutput
 
     return res
   }
 
+  /** 按 provider 执行各自的参数校验 */
+  private validateInput(input: GenerateImageInput) {
+    if (this.provider === '' || this.provider === 'hunyuan-image') {
+      this.assertHunyuanInput(input)
+    }
+  }
+
+  /** 当模型为 HY-Image-v3.0-I2I-ToB-v1.0.1 时，image_urls / images 最多只能有 1 个元素 */
+  private assertHunyuanInput(input: GenerateImageInput) {
+    if (!input || input.model !== 'HY-Image-v3.0-I2I-ToB-v1.0.1') return
+
+    const { image_urls: imageUrls, images } = input
+
+    if (imageUrls && imageUrls.length > 1) {
+      throw new InvalidParamsError(
+        '当模型为 HY-Image-v3.0-I2I-ToB-v1.0.1 时，image_urls 最多只能有 1 个元素',
+        'image_urls',
+      )
+    }
+    if (images && images.length > 1) {
+      throw new InvalidParamsError(
+        '当模型为 HY-Image-v3.0-I2I-ToB-v1.0.1 时，images 最多只能有 1 个元素',
+        'images',
+      )
+    }
+  }
+
+  /**
+   * 解析生成图片的子路径。
+   * 老 provider（''/hunyuan-image）未命中路由时兜底到默认子路径；
+   * cloudbase 等新 provider 不支持默认子路径，模型未配置路由时直接报错。
+   */
+  private resolveSubUrl(input: GenerateImageInput): string {
+    const model = input && typeof input.model === 'string' ? input.model : undefined
+    const subUrl = model ? this.getGenerateImageSubUrl(this.provider, model) : undefined
+
+    if (subUrl) return subUrl
+
+    if (this.provider === 'cloudbase') {
+      throw new InvalidParamsError(
+        `cloudbase provider 不支持的模型：${model ?? '(未指定)'}`,
+        'model',
+      )
+    }
+
+    return this.defaultGenerateImageSubUrl
+  }
+
   private getGenerateUrl(subUrl: string) {
     return `${this.baseUrl}/${this.provider}/${subUrl}`
   }

package/src/type.ts

@@ -277,6 +277,117 @@ export interface HunyuanARGenerateImageOutput {
   }>
 }
 
+// #region Image Chat Types (OpenAI Chat Completions 风格 messages)
+// 用于 Hy-Image-3.5-preview 等以 Chat/Messages 协议提交的生图模型。
+// 注意：这是 OpenAI Chat Completions 风格的协议，并非 OpenAI 完整标准，
+// 其中 reasoning、is_generate 为服务端扩展字段。
+
+/** Chat messages 中的文本内容块 */
+export interface ChatContentPartText {
+  type: 'text'
+  /** 具体文本内容 */
+  text: string
+}
+
+/** Chat messages 中的图片内容块 */
+export interface ChatContentPartImageUrl {
+  type: 'image_url'
+  /** 支持 http(s) 公网 URL 或 data:image/...;base64,... */
+  image_url: {
+    url: string
+  }
+  /** 仅 role=tool 回灌上一轮生图结果时为 true */
+  is_generate?: boolean
+}
+
+export type ChatContentPart = ChatContentPartText | ChatContentPartImageUrl
+
+/** OpenAI Chat Completions 风格的会话消息 */
+export interface ChatMessage {
+  /** 角色。tool 仅在把上一轮生图结果回灌作为下一轮上下文时出现 */
+  role: 'user' | 'assistant' | 'tool'
+  /** 该轮的具体内容，assistant 仅触发工具调用、不发文本时可省略 */
+  content?: ChatContentPart[]
+  /** 仅 role=assistant 多轮回灌时使用，透传上一轮响应中的思维链原文 */
+  reasoning?: string
+  /** 仅 role=assistant 多轮回灌时使用，元素结构见 ToolCall */
+  tool_calls?: ToolCall[]
+  /** 仅 role=tool 多轮回灌时使用，须与上一条 assistant.tool_calls[i].id 一致 */
+  tool_call_id?: string
+}
+
+export interface CloudbaseGenerateImageInput {
+  /** 模型名称：Hy-Image-3.5-preview，协议取值为 hy-image-v3.5-preview */
+  model: 'hy-image-v3.5-preview'
+  /** 多轮会话内容，时间从旧到新排列。最后一个 role=user 的消息作为本轮生图指令 */
+  messages: ChatMessage[]
+  /**
+   * 生成尺寸，格式 "${宽}x${高}"
+   * 宽高均为 [256, 8192]，面积不超过 16777216（最高 4096x4096）
+   * 不传或传空串时由模型基于 prompt 语义与 generate_max_pixels 自主决定
+   */
+  size?: string
+  /** 生成种子，int64 范围 [0, 2^63-1]；为 0 或不传时服务端随机分配 */
+  seed?: number
+  /**
+   * 生成图片的目标面积（像素数），仅在未传 size 时生效
+   * 支持 1048576（1K）、2359296（1.5K，默认）、4194304（2K）
+   */
+  generate_max_pixels?: number
+  /** 输入参考图面积上限（像素数），默认 1048576 */
+  resize_max_pixels?: number
+  /** 会话 ID，用于推理服务一致性哈希调度 */
+  session?: string
+  /** 业务自定义水印内容，最长 16 字符，生成在图片右下角 */
+  footnote?: string
+  /** 外部搜索增强开关，默认关闭 */
+  use_search_tool?: { value: boolean }
+}
+
+export interface CloudbaseGenerateImageOutput {
+  /** 此次请求的 traceID */
+  id: string
+  /** 固定 image.chat.completion.chunk */
+  object: string
+  /** Unix 秒级时间戳 */
+  created: number
+  /** 原厂实际服务返回的内部版本标识，不建议用于业务分支判断 */
+  model: string
+  /** 本帧所属 LLM 轮次，从 0 起算 */
+  round: number
+  choices: Array<{
+    index: number
+    /** 主图载体，成功时优先读取 delta.image.url 作为最终交付 URL */
+    delta: {
+      type?: string
+      image?: {
+        /** 本次生图的最终交付 URL，有效期 12 小时 */
+        url: string
+        width: number
+        height: number
+        source: string
+        tool_call_id: string
+      }
+    }
+    /** 成功终态下往往为 null；内容安全拦截/业务错误时为 error 等非空值 */
+    finish_reason?: string | null
+  }>
+  usage?: { total_tokens: number }
+  tokenhub_usage?: { total_tokens: number }
+  request_id?: string
+  /** 服务端拼好的「下一轮回灌消息序列」，多轮编辑时原样追加到下一轮 messages */
+  assembled_history?: ChatMessage[]
+  /** 仅失败终态帧才带 */
+  error?: {
+    type: string
+    code: string
+    message: string
+    request_id?: string
+  }
+}
+
+// #endregion
+
 export type HunyuanEditImageInput = {
   /** 模型名称，本期为 hunyuan-image，即为商品图编辑场景 */
   model: 'hunyuan-image' | (string & {})