@henjicc/ai-sdk 0.8.0 → 0.10.0

package/dist/providers/volcengine.d.ts

@@ -1,3 +1,3 @@
 import type { ProviderContinuePollingInput, ProviderExecutionInput, ProviderExecutionResult } from '../types/runtime.js';
 export declare function execute(input: ProviderExecutionInput): Promise<ProviderExecutionResult>;
-export declare function continuePolling(_input: ProviderContinuePollingInput): Promise<ProviderExecutionResult>;
+export declare function continuePolling(input: ProviderContinuePollingInput): Promise<ProviderExecutionResult>;

package/dist/providers/volcengine.js

@@ -1,24 +1,33 @@
 import { AiRuntimeError } from '../runtime/AiRuntimeError.js';
-import { collectDeepUrls, normalizeEndpoint, readJsonResponse, stringAt } from './helpers.js';
+import { POLL_QUERY_FAILED, pollUntilResult } from '../protocols/polling.js';
+import { collectDeepUrls, getPointer, isJsonObject, normalizeEndpoint, pushUniqueUrl, readJsonResponse, stringAt } from './helpers.js';
 import { fetchProvider } from './provider-fetch.js';
 const VOLCENGINE_BASE_URL = 'https://ark.cn-beijing.volces.com';
+/** 方舟视频生成是异步任务：提交返回任务 ID，再按 `GET {route}/{id}` 查询；图片生成走同步端点。 */
+const VIDEO_TASK_ROUTE = '/api/v3/contents/generations/tasks';
+function isVideoTaskRoute(route) {
+    return route.replace(/\/+$/, '') === VIDEO_TASK_ROUTE;
+}
+function authHeaders(apiKey) {
+    return { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' };
+}
 export async function execute(input) {
     const response = await fetchProvider('Volcengine Ark', normalizeEndpoint(VOLCENGINE_BASE_URL, input.route), {
         method: input.method,
-        headers: {
-            Authorization: `Bearer ${input.apiKey}`,
-            'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(input.body),
+        headers: authHeaders(input.apiKey),
+        body: JSON.stringify(isVideoTaskRoute(input.route) ? normalizeAudioDataUris(input.body) : input.body),
         signal: input.signal,
     }, {
         transport: input.runtime.transport,
         retryPreconnectOnce: true,
     });
     const payload = await readJsonResponse(response, 'Volcengine Ark');
-    const errorMessage = stringAt(payload, '/error/message') ?? stringAt(payload, '/message');
-    if (stringAt(payload, '/error/code') || stringAt(payload, '/code')) {
-        throw new AiRuntimeError('provider_task_failed', errorMessage ?? 'Volcengine Ark generation failed');
+    assertNoArkError(payload, 'Volcengine Ark generation failed');
+    if (isVideoTaskRoute(input.route)) {
+        const taskId = stringAt(payload, '/id')?.trim();
+        if (!taskId)
+            throw new AiRuntimeError('invalid_response', 'Volcengine Ark video task response has no id');
+        return { status: 'pending', url: '', taskId, metadata: payload };
     }
     const urls = [];
     collectDeepUrls(payload, urls);
@@ -27,6 +36,75 @@ export async function execute(input) {
     }
     return { status: 'completed', url: urls.join('|||'), metadata: payload };
 }
-export async function continuePolling(_input) {
-    throw new AiRuntimeError('unsupported_provider', 'Volcengine Ark image models use synchronous generation');
+export async function continuePolling(input) {
+    if (!isVideoTaskRoute(input.route)) {
+        throw new AiRuntimeError('unsupported_provider', 'Volcengine Ark image models use synchronous generation');
+    }
+    const payload = await pollUntilResult(input, async () => {
+        const endpoint = `${VOLCENGINE_BASE_URL}${VIDEO_TASK_ROUTE}/${encodeURIComponent(input.taskId)}`;
+        const response = await fetchProvider('Volcengine Ark', endpoint, {
+            headers: authHeaders(input.apiKey),
+            signal: input.signal,
+        }, {
+            transport: input.runtime.transport,
+            retryPreconnectOnce: true,
+        });
+        const result = await readJsonResponse(response, 'Volcengine Ark');
+        const status = (stringAt(result, '/status') ?? '').trim().toLowerCase();
+        if (status === 'succeeded')
+            return result;
+        if (status === 'queued' || status === 'running')
+            return undefined;
+        if (status === 'failed' || status === 'cancelled' || status === 'expired') {
+            const code = stringAt(result, '/error/code');
+            const message = stringAt(result, '/error/message')
+                ?? (status === 'expired' ? '任务超过方舟任务超时阈值未完成' : status === 'cancelled' ? '任务已被取消' : 'Volcengine Ark video task failed');
+            throw new AiRuntimeError('provider_task_failed', code ? `${code}: ${message}` : message, {
+                providerCode: code, providerMessage: message,
+            });
+        }
+        return POLL_QUERY_FAILED;
+    });
+    const urls = [];
+    // 视频在前、尾帧在后：消费方按顺序把第一项当作主产物。
+    for (const pointer of ['/content/video_url', '/content/last_frame_url']) {
+        const url = stringAt(payload, pointer);
+        if (url && /^https?:\/\//i.test(url))
+            pushUniqueUrl(urls, url);
+    }
+    const videoUrl = stringAt(payload, '/content/video_url');
+    if (!videoUrl || !/^https?:\/\//i.test(videoUrl)) {
+        throw new AiRuntimeError('empty_result', `Volcengine Ark video task has no video_url (task_id=${input.taskId})`);
+    }
+    return { status: 'completed', url: urls.join('|||'), taskId: input.taskId, metadata: payload };
+}
+function assertNoArkError(payload, fallback) {
+    const errorMessage = stringAt(payload, '/error/message') ?? stringAt(payload, '/message');
+    if (stringAt(payload, '/error/code') || stringAt(payload, '/code')) {
+        throw new AiRuntimeError('provider_task_failed', errorMessage ?? fallback);
+    }
+}
+/**
+ * 方舟音频 Base64 要求 `data:audio/<格式>;base64,`，格式写 wav/mp3；本地文件读出的
+ * 标准 MIME 是 audio/mpeg、audio/x-wav 等，发送前换成官方格式名。
+ */
+function normalizeAudioDataUris(body) {
+    if (!isJsonObject(body) || !Array.isArray(body.content))
+        return body;
+    const content = body.content.map((item) => {
+        const url = getPointer(item, '/audio_url/url');
+        if (!isJsonObject(item) || !isJsonObject(item.audio_url) || typeof url !== 'string')
+            return item;
+        const match = /^data:audio\/([^;,]+);base64,/i.exec(url);
+        if (!match)
+            return item;
+        const subtype = match[1].toLowerCase();
+        const format = subtype === 'mpeg' || subtype === 'mp3' ? 'mp3'
+            : ['wav', 'x-wav', 'wave', 'vnd.wave'].includes(subtype) ? 'wav' : null;
+        // 方舟只收 wav / mp3；其他格式提交前就拦下，不让用户只看到供应商报错。
+        if (!format)
+            throw new AiRuntimeError('invalid_media', `火山方舟参考音频只支持 MP3 或 WAV，当前是 ${subtype}，请先转换格式`);
+        return { ...item, audio_url: { ...item.audio_url, url: `data:audio/${format};base64,${url.slice(match[0].length)}` } };
+    });
+    return { ...body, content };
 }

package/dist/runtime/retry.js

@@ -41,6 +41,9 @@ export function shouldRetry(error, mode = 'request') {
             || errorChain(error).some(record => providerCode(record)?.toUpperCase() === 'ECONNRESET'
                 && record.message === 'Client network socket disconnected before secure TLS connection was established');
     }
+    // 任务已经终止；retryable 表示用户可重新提交，不允许自动续查或重放计费请求。
+    if (errorChain(error).some(record => record.details && typeof record.details === 'object' && record.details.terminal === true))
+        return false;
     const structuredRetryable = readStructuredRetryable(error);
     if (structuredRetryable !== undefined)
         return structuredRetryable;

package/dist/tool-packs/fal-erase/models/bria-eraser.model.js

@@ -5,7 +5,7 @@ export const briaEraserModel = defineModel({
         canonicalModelId: 'bria-eraser',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'erase', 'mask-input', 'provider-fal'],
+        tags: ['erase'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 20 },
     },
     acceptsPrompt: false,

package/dist/tool-packs/fal-erase/models/finegrain-eraser.model.js

@@ -5,7 +5,7 @@ export const finegrainEraserModel = defineModel({
         canonicalModelId: 'finegrain-eraser',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'erase', 'mask-input', 'provider-fal'],
+        tags: ['erase'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 20 },
     },
     acceptsPrompt: false,

package/dist/tool-packs/fal-erase/models/flux-pro-erase.model.js

@@ -5,7 +5,7 @@ export const fluxProEraseModel = defineModel({
         canonicalModelId: 'flux-pro-erase',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'erase', 'mask-input', 'provider-fal'],
+        tags: ['erase'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 20 },
     },
     acceptsPrompt: false,

package/dist/tool-packs/fal-image-utilities/models/control-light.model.js

@@ -6,7 +6,7 @@ export const falControlLightModel = defineModel({
         canonicalModelId: 'control-light',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'low-light-enhancement', 'provider-fal'],
+        tags: ['low-light-enhancement'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 30 },
     },
     acceptsPrompt: false,

package/dist/tool-packs/fal-image-utilities/models/outpaint.model.js

@@ -6,7 +6,7 @@ export const falOutpaintModel = defineModel({
         canonicalModelId: 'image-apps-v2-outpaint',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'outpainting', 'provider-fal'],
+        tags: ['outpainting'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 30 },
     },
     inputLimits: { images: { exact: 1 }, videos: { max: 0 } },

package/dist/tool-packs/fal-image-utilities/models/photo-restoration.model.js

@@ -6,7 +6,7 @@ export const falPhotoRestorationModel = defineModel({
         canonicalModelId: 'image-apps-v2-photo-restoration',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'photo-restoration', 'provider-fal'],
+        tags: ['photo-restoration'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 30 },
     },
     acceptsPrompt: false,

package/dist/tool-packs/fal-image-utilities/models/pixelcut-background-removal.model.js

@@ -6,7 +6,7 @@ export const falPixelcutBackgroundRemovalModel = defineModel({
         canonicalModelId: 'pixelcut-background-removal',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'background-removal', 'alpha-output', 'provider-fal'],
+        tags: ['transparent-background'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 30 },
     },
     acceptsPrompt: false,

package/dist/tool-packs/fal-image-utilities/models/product-photography.model.js

@@ -6,7 +6,7 @@ export const falProductPhotographyModel = defineModel({
         canonicalModelId: 'image-apps-v2-product-photography',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'product-photography', 'background-generation', 'provider-fal'],
+        tags: ['product-photography'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 30 },
     },
     acceptsPrompt: false,

package/dist/tool-packs/fal-image-utilities/models/relighting.model.js

@@ -26,7 +26,7 @@ export const falRelightingModel = defineModel({
         canonicalModelId: 'image-apps-v2-relighting',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'relighting', 'style-presets', 'provider-fal'],
+        tags: ['relighting'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 30 },
     },
     acceptsPrompt: false,

package/dist/tool-packs/fal-multi-angle/models/flux-2-multiple-angles.model.js

@@ -20,7 +20,7 @@ export const falFlux2MultipleAnglesModel = defineModel({
         canonicalModelId: 'flux-2-multiple-angles',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'multi-angle', 'camera-control', 'provider-fal'],
+        tags: ['multi-angle'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 30 },
     },
     acceptsPrompt: false,

package/dist/tool-packs/fal-multi-angle/models/perspective-change.model.js

@@ -17,7 +17,7 @@ export const falPerspectiveChangeModel = defineModel({
         canonicalModelId: 'perspective-change',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'multi-angle', 'perspective-preset', 'provider-fal'],
+        tags: ['multi-angle'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 30 },
     },
     acceptsPrompt: false,

package/dist/tool-packs/fal-multi-angle/models/qwen-image-edit-2511-multiple-angles.model.js

@@ -21,7 +21,7 @@ export const falQwenImageEdit2511MultipleAnglesModel = defineModel({
         canonicalModelId: 'qwen-image-edit-2511-multiple-angles',
         provider: 'fal',
         type: 'image',
-        tags: ['image-edit', 'multi-angle', 'camera-control', 'provider-fal'],
+        tags: ['multi-angle'],
         polling: { interval: 2_000, maxAttempts: 180, expectedAttempts: 30 },
     },
     acceptsPrompt: false,

package/dist/types/model.d.ts

@@ -8,6 +8,7 @@
  * 这里保留 selector/builder 的真实函数，是 catalog 与所有宿主运行时共同消费的唯一模型
  * 契约；JSON DTO 等跨进程数据类型仍位于 `./runtime.ts`。
  */
+import type { ModelTag } from './modelTags.js';
 import type { GenerateStatus, JsonValue, JsonObject, StructuredGenerationOutput } from './runtime.js';
 /** SDK 内置的模型产出类型。开放类型仍保留这些字面量的编辑器补全。 */
 export type BuiltinModelType = 'image' | 'video' | 'audio';
@@ -23,15 +24,6 @@ export declare const BUILTIN_PROVIDER_IDS: readonly ["apimart", "bailian", "volc
 export type BuiltinProviderId = (typeof BUILTIN_PROVIDER_IDS)[number];
 /** Provider ID：内置供应商 + 第三方扩展字符串。 */
 export type ProviderId = BuiltinProviderId | (string & {});
-/**
- * 模型标签。
- *
- * 应用侧 `src/core/types/ModelTags.ts` 维护了完整的 `KnownModelTag` 字面量清单 +
- * 中文描述表（给标签管理 UI 用），那份是产品资产，不搬进 SDK。SDK 只需要知道
- * "这是一串标签字符串"，不需要在类型层枚举穷尽值——枚举校验交给应用侧或未来的
- * 标签注册表。
- */
-export type ModelTag = string;
 export interface ProgressCurveConfig {
     slowStart?: number;
     slowEnd?: number;
@@ -83,8 +75,15 @@ export interface ModelRuntimeMeta {
     canonicalModelId: string;
     provider: ProviderId;
     type: ModelType;
-    /** 模型能力标签 */
+    /** 模型能力标签，取值与判断标准见 MODEL_TAG_DEFINITIONS */
     tags?: ModelTag[];
+    /** 只认这种语言的提示词；不填表示不限。 */
+    promptLanguage?: 'en';
+    /**
+     * 已过时的原因（平台下线、被新版取代、不再提供等）。填写后能力发现与宿主的普通入口不再列出该模型，
+     * 但仍可按 ID 解析，旧工程能打开、开发者能核对。
+     */
+    deprecated?: string;
     /** 轮询配置：异步任务状态轮询 */
     polling?: {
         interval: number;
@@ -290,6 +289,8 @@ interface RuntimePricingMediaContextRequirementBase {
     aggregation?: RuntimePricingMediaAggregation;
     /** 对媒体指标做固定或参数驱动的倍率变换，例如输出 MP = 输入 MP × 放大倍率²。 */
     multiplier?: RuntimePricingMediaMultiplier;
+    /** 只有部分模式按媒体计价时声明；返回 false 时不读取媒体，也不算缺少指标。 */
+    when?: (params: JsonObject) => boolean;
 }
 export type RuntimePricingMediaContextRequirement = (RuntimePricingMediaContextRequirementBase & {
     mediaType: 'image';
@@ -297,15 +298,22 @@ export type RuntimePricingMediaContextRequirement = (RuntimePricingMediaContextR
 }) | (RuntimePricingMediaContextRequirementBase & {
     mediaType: 'video';
     metric: 'durationSeconds' | 'megapixels' | 'width' | 'height';
+}) | (RuntimePricingMediaContextRequirementBase & {
+    mediaType: 'audio';
+    metric: 'durationSeconds';
 });
 export interface RuntimePricingConfig {
     currency: Currency;
+    /** 估计值不代表实际账单；宿主应同时展示 description 中的依据。 */
+    billingMode?: 'estimated';
     fixed?: number;
     calculator?: (params: JsonObject) => number;
     /** 数值是当前参数总价，还是单个计费单位的参考价；缺省保持既有总价语义。 */
     estimateMode?: 'total' | 'unit';
     /** `estimateMode: 'unit'` 时用于展示的计费单位，例如 `MP`。 */
     estimateUnit?: string;
+    /** 保守预算上限的展示语义；仍是估算，不能承诺供应商实际账单上限。 */
+    estimateKind?: 'upper-bound';
     /**
      * calculator 需要宿主从媒体文件补齐的指标。SDK 只声明契约，不读取文件；
      * Web/Electron 等宿主可用各自的媒体探针统一解析并注入。
@@ -319,7 +327,20 @@ export interface RuntimeInputCountLimit {
     max?: number;
     exact?: number;
 }
-export interface RuntimeVideoConstraints {
+/**
+ * 供应商对输入素材画面尺寸的硬性要求。宽高按显示方向计算（已应用 EXIF 旋转），
+ * 宽高比 = 宽 / 高；“边长 a–b px”写作 minShortSidePx: a、maxLongSidePx: b。
+ */
+export interface RuntimeMediaDimensionConstraints {
+    minShortSidePx?: number;
+    maxLongSidePx?: number;
+    minPixels?: number;
+    maxPixels?: number;
+    minAspectRatio?: number;
+    maxAspectRatio?: number;
+}
+export type RuntimeImageConstraints = RuntimeMediaDimensionConstraints;
+export interface RuntimeVideoConstraints extends RuntimeMediaDimensionConstraints {
     maxSizeMB?: number;
     minDurationSec?: number;
     maxDurationSec?: number;
@@ -332,6 +353,7 @@ export interface RuntimeInputLimitRule {
     images?: RuntimeInputCountLimit;
     videos?: RuntimeInputCountLimit;
     audios?: RuntimeInputCountLimit;
+    imageConstraints?: RuntimeImageConstraints;
     videoConstraints?: RuntimeVideoConstraints;
 }
 export interface RuntimeInputLimitsConfig {
@@ -404,6 +426,38 @@ export interface RuntimeConstraints {
     imageSizeFields?: RuntimeImageSizeFieldConstraint[];
     mediaFields?: RuntimeMediaFieldConstraint[];
 }
+/**
+ * 续接生成请求携带的保留参数，由宿主写入、请求构建读取。
+ * `reference` 是源结果完成时 `capture` 取到的平台引用（任务 ID、草稿缓存等），界面不展示它。
+ */
+export interface RuntimeContinuationParam {
+    id: string;
+    sourceModelId: string;
+    reference: JsonObject;
+}
+/** 续接请求放在参数里的键名。 */
+export declare const CONTINUATION_PARAM = "__continuation";
+/**
+ * 基于一次已完成的结果继续生成。平台常要求引用上一次的任务 ID 或草稿缓存，
+ * 这些引用由 SDK 从结果里取出、宿主随结果保存，用户与助手都不必知道它们。
+ */
+export interface RuntimeContinuation {
+    /** 续接动作标识，如 `finalize-draft`（草稿转正片）、`extend`（续写）、`animate`（做成视频） */
+    id: string;
+    /** 续接到哪个模型；缺省为同一个模型 */
+    targetModelId?: string;
+    /** 按源请求参数判断这次结果能否续接，例如只有草稿能转正片；缺省为都能 */
+    available?: (params: JsonObject) => boolean;
+    /** 从完成结果里取出续接所需的平台引用；取不到时返回 null，表示这次结果不能续接 */
+    capture: (result: {
+        taskId?: string;
+        metadata: JsonValue;
+    }) => JsonObject | null;
+    /** 续接请求的参数：在源参数基础上调整，`__continuation` 由宿主另行合入 */
+    params: (source: JsonObject) => JsonObject;
+    /** direct：参数已齐全，直接提交；edit：带进输入区，由用户补写提示词等再提交 */
+    submit: 'direct' | 'edit';
+}
 export interface ModelRuntimeDefinition {
     meta: ModelRuntimeMeta;
     /**
@@ -418,6 +472,8 @@ export interface ModelRuntimeDefinition {
     inputLimits?: RuntimeInputLimits;
     /** 可以独立构成一次生成输入的自定义参数 ID（如"父任务 ID"） */
     alternativeInputParamIds?: string[];
+    /** 这个模型的结果能做哪些续接生成（草稿转正片、续写、把图做成视频）。 */
+    continuations?: RuntimeContinuation[];
     /** 请求体构建后的运行时安全网约束 */
     runtimeConstraints?: RuntimeConstraints;
     /** 端点选择配置 */
@@ -429,4 +485,4 @@ export interface ModelRuntimeDefinition {
     /** 价格配置 */
     pricing: RuntimePricingConfig;
 }
-export {};
+export * from './modelTags.js';

package/dist/types/model.js

@@ -21,3 +21,6 @@ export const BUILTIN_PROVIDER_IDS = [
     'grsai',
     'siliconflow',
 ];
+/** 续接请求放在参数里的键名。 */
+export const CONTINUATION_PARAM = '__continuation';
+export * from './modelTags.js';

package/dist/types/modelTags.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 生成模型能力标签词表：标签只回答“这个模型能做什么事”，一件事只有一个标签。
+ *
+ * 两层判断标准：
+ * - 形态（form）：按“输入什么、输出什么”判断，模型能做就打。
+ * - 专项（specialty）：模型为这件事提供了专门的参数或接口才打；通用编辑模型只靠写提示词也能做到的不打。
+ *
+ * 能从模型配置读出的事实（供应商、类型、能传几张图、分辨率档位、出图数量、提示词语言）不做标签。
+ * 展示名属于宿主的产品文案，不放在 SDK。
+ */
+export declare const MODEL_TAG_DEFINITIONS: readonly [{
+    readonly id: "text-to-image";
+    readonly layer: "form";
+    readonly mediaType: "image";
+    readonly criterion: "不给图，只凭文字出图";
+}, {
+    readonly id: "image-to-image";
+    readonly layer: "form";
+    readonly mediaType: "image";
+    readonly criterion: "给图，按提示词改图或据此生成新图（参考、融合也算）";
+}, {
+    readonly id: "text-to-video";
+    readonly layer: "form";
+    readonly mediaType: "video";
+    readonly criterion: "不给图或视频，只凭文字出视频";
+}, {
+    readonly id: "image-to-video";
+    readonly layer: "form";
+    readonly mediaType: "video";
+    readonly criterion: "给一张图作首帧生成视频";
+}, {
+    readonly id: "start-end-frame";
+    readonly layer: "form";
+    readonly mediaType: "video";
+    readonly criterion: "同时给首帧和尾帧生成中间过程；必须同时具备图生视频";
+}, {
+    readonly id: "reference-mode";
+    readonly layer: "form";
+    readonly mediaType: "video";
+    readonly criterion: "图片或视频只作参考生成新片段，不锁定首帧，也不保证在原视频上改或接在其后";
+}, {
+    readonly id: "video-to-video";
+    readonly layer: "form";
+    readonly mediaType: "video";
+    readonly criterion: "输入一段视频，在原时间轴上改内容";
+}, {
+    readonly id: "video-extension";
+    readonly layer: "form";
+    readonly mediaType: "video";
+    readonly criterion: "接在输入视频之后继续生成";
+}, {
+    readonly id: "motion-control";
+    readonly layer: "form";
+    readonly mediaType: "video";
+    readonly criterion: "用一段视频的动作驱动图里的主体";
+}, {
+    readonly id: "audio-to-video";
+    readonly layer: "form";
+    readonly mediaType: "video";
+    readonly criterion: "输入一段音频，生成与之同步、等长的视频";
+}, {
+    readonly id: "text-to-audio";
+    readonly layer: "form";
+    readonly mediaType: "audio";
+    readonly criterion: "文字转语音";
+}, {
+    readonly id: "voice-clone";
+    readonly layer: "form";
+    readonly mediaType: "audio";
+    readonly criterion: "用一段声音生成可复用的音色";
+}, {
+    readonly id: "inpainting";
+    readonly layer: "specialty";
+    readonly mediaType: "image";
+    readonly criterion: "有遮罩输入，按提示词只改遮罩内的区域";
+}, {
+    readonly id: "erase";
+    readonly layer: "specialty";
+    readonly mediaType: "image";
+    readonly criterion: "有遮罩输入，不需要提示词，把遮罩内的东西去掉";
+}, {
+    readonly id: "relighting";
+    readonly layer: "specialty";
+    readonly mediaType: "image";
+    readonly criterion: "有光源方向、强度或光照预设等专门参数";
+}, {
+    readonly id: "multi-angle";
+    readonly layer: "specialty";
+    readonly mediaType: "image";
+    readonly criterion: "有镜头角度、视角预设等专门参数";
+}, {
+    readonly id: "outpainting";
+    readonly layer: "specialty";
+    readonly mediaType: "image";
+    readonly criterion: "有扩展方向、边距等专门参数";
+}, {
+    readonly id: "upscaling";
+    readonly layer: "specialty";
+    readonly mediaType: "image";
+    readonly criterion: "专门提高分辨率，有放大倍数或目标尺寸参数";
+}, {
+    readonly id: "photo-restoration";
+    readonly layer: "specialty";
+    readonly mediaType: "image";
+    readonly criterion: "专门修复老照片的划痕、褪色、模糊";
+}, {
+    readonly id: "layer-decomposition";
+    readonly layer: "specialty";
+    readonly mediaType: "image";
+    readonly criterion: "把一张图拆成多张分层图";
+}, {
+    readonly id: "transparent-background";
+    readonly layer: "specialty";
+    readonly mediaType: "image";
+    readonly criterion: "能输出带透明通道的图（抠图、保留透明、透明背景参数）";
+}, {
+    readonly id: "low-light-enhancement";
+    readonly layer: "specialty";
+    readonly mediaType: "image";
+    readonly criterion: "专门提亮暗光照片";
+}, {
+    readonly id: "product-photography";
+    readonly layer: "specialty";
+    readonly mediaType: "image";
+    readonly criterion: "专门给商品图生成新的背景与场景";
+}, {
+    readonly id: "multi-speaker-dialogue";
+    readonly layer: "specialty";
+    readonly mediaType: "audio";
+    readonly criterion: "一段脚本里多个说话人，一次合成整段对话";
+}, {
+    readonly id: "timestamps";
+    readonly layer: "specialty";
+    readonly mediaType: "audio";
+    readonly criterion: "合成结果附带逐字或逐词的时间";
+}];
+export type ModelTagDefinition = (typeof MODEL_TAG_DEFINITIONS)[number];
+export type ModelTag = ModelTagDefinition['id'];
+export type ModelTagLayer = ModelTagDefinition['layer'];
+export declare const MODEL_TAGS: readonly ModelTag[];
+export declare function isModelTag(value: string): value is ModelTag;
+export declare function getModelTagDefinition(tag: ModelTag): ModelTagDefinition;

package/dist/types/modelTags.js

@@ -0,0 +1,44 @@
+/**
+ * 生成模型能力标签词表：标签只回答“这个模型能做什么事”，一件事只有一个标签。
+ *
+ * 两层判断标准：
+ * - 形态（form）：按“输入什么、输出什么”判断，模型能做就打。
+ * - 专项（specialty）：模型为这件事提供了专门的参数或接口才打；通用编辑模型只靠写提示词也能做到的不打。
+ *
+ * 能从模型配置读出的事实（供应商、类型、能传几张图、分辨率档位、出图数量、提示词语言）不做标签。
+ * 展示名属于宿主的产品文案，不放在 SDK。
+ */
+export const MODEL_TAG_DEFINITIONS = [
+    { id: 'text-to-image', layer: 'form', mediaType: 'image', criterion: '不给图，只凭文字出图' },
+    { id: 'image-to-image', layer: 'form', mediaType: 'image', criterion: '给图，按提示词改图或据此生成新图（参考、融合也算）' },
+    { id: 'text-to-video', layer: 'form', mediaType: 'video', criterion: '不给图或视频，只凭文字出视频' },
+    { id: 'image-to-video', layer: 'form', mediaType: 'video', criterion: '给一张图作首帧生成视频' },
+    { id: 'start-end-frame', layer: 'form', mediaType: 'video', criterion: '同时给首帧和尾帧生成中间过程；必须同时具备图生视频' },
+    { id: 'reference-mode', layer: 'form', mediaType: 'video', criterion: '图片或视频只作参考生成新片段，不锁定首帧，也不保证在原视频上改或接在其后' },
+    { id: 'video-to-video', layer: 'form', mediaType: 'video', criterion: '输入一段视频，在原时间轴上改内容' },
+    { id: 'video-extension', layer: 'form', mediaType: 'video', criterion: '接在输入视频之后继续生成' },
+    { id: 'motion-control', layer: 'form', mediaType: 'video', criterion: '用一段视频的动作驱动图里的主体' },
+    { id: 'audio-to-video', layer: 'form', mediaType: 'video', criterion: '输入一段音频，生成与之同步、等长的视频' },
+    { id: 'text-to-audio', layer: 'form', mediaType: 'audio', criterion: '文字转语音' },
+    { id: 'voice-clone', layer: 'form', mediaType: 'audio', criterion: '用一段声音生成可复用的音色' },
+    { id: 'inpainting', layer: 'specialty', mediaType: 'image', criterion: '有遮罩输入，按提示词只改遮罩内的区域' },
+    { id: 'erase', layer: 'specialty', mediaType: 'image', criterion: '有遮罩输入，不需要提示词，把遮罩内的东西去掉' },
+    { id: 'relighting', layer: 'specialty', mediaType: 'image', criterion: '有光源方向、强度或光照预设等专门参数' },
+    { id: 'multi-angle', layer: 'specialty', mediaType: 'image', criterion: '有镜头角度、视角预设等专门参数' },
+    { id: 'outpainting', layer: 'specialty', mediaType: 'image', criterion: '有扩展方向、边距等专门参数' },
+    { id: 'upscaling', layer: 'specialty', mediaType: 'image', criterion: '专门提高分辨率，有放大倍数或目标尺寸参数' },
+    { id: 'photo-restoration', layer: 'specialty', mediaType: 'image', criterion: '专门修复老照片的划痕、褪色、模糊' },
+    { id: 'layer-decomposition', layer: 'specialty', mediaType: 'image', criterion: '把一张图拆成多张分层图' },
+    { id: 'transparent-background', layer: 'specialty', mediaType: 'image', criterion: '能输出带透明通道的图（抠图、保留透明、透明背景参数）' },
+    { id: 'low-light-enhancement', layer: 'specialty', mediaType: 'image', criterion: '专门提亮暗光照片' },
+    { id: 'product-photography', layer: 'specialty', mediaType: 'image', criterion: '专门给商品图生成新的背景与场景' },
+    { id: 'multi-speaker-dialogue', layer: 'specialty', mediaType: 'audio', criterion: '一段脚本里多个说话人，一次合成整段对话' },
+    { id: 'timestamps', layer: 'specialty', mediaType: 'audio', criterion: '合成结果附带逐字或逐词的时间' },
+];
+export const MODEL_TAGS = MODEL_TAG_DEFINITIONS.map((definition) => definition.id);
+export function isModelTag(value) {
+    return MODEL_TAGS.includes(value);
+}
+export function getModelTagDefinition(tag) {
+    return MODEL_TAG_DEFINITIONS.find((definition) => definition.id === tag);
+}

package/dist/types/runtime.d.ts

@@ -57,7 +57,10 @@ export interface AiRuntimeTrace {
 }
 export interface AiGenerateResponseDto {
     status: GenerateStatus;
+    /** 兼容字段：多个输出时用 `|||` 拼接；新代码请读 `urls`。 */
     url: string;
+    /** 全部输出地址，按供应商输出顺序（SDK 生成结果总会给出；宿主自建的 DTO 可省略）。 */
+    urls?: string[];
     filePath?: string;
     /** 宿主本次响应中新建的受管媒体；消费方完成转移后必须释放。 */
     createdFilePaths?: string[];

package/dist/types/speechTimings.d.ts

@@ -0,0 +1,15 @@
+/** Source audio clock, milliseconds. An output index addresses the corresponding generated audio. */
+export type SpeechTimings = {
+    granularity: 'char' | 'word' | 'sentence';
+    items: Array<{
+        text: string;
+        startMs: number;
+        endMs: number;
+        confidence?: number;
+    }>;
+};
+/** Stored in generation metadata.outputTimings; absent means the provider supplied no timestamps. */
+export type GenerationOutputTimings = Array<{
+    outputIndex: number;
+    timings: SpeechTimings;
+}>;

package/dist/types/speechTimings.js

@@ -0,0 +1 @@
+export {};