jimeng-web-mcp/lib/index.d.cts

MCP服务器项目，直接访问即梦AI Web端进行图像和视频生成（仅供学习研究使用）

#!/usr/bin/env node
/**
 * 主体参考视频生成参数
 */
interface MainReferenceVideoParams {
    referenceImages: string[];
    prompt: string;
    model?: string;
    resolution?: '720p' | '1080p';
    videoAspectRatio?: '21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16';
    fps?: number;
    duration?: number;
    refresh_token?: string;
}

/**
 * API相关类型定义
 * 从api.ts中提取的所有API相关的接口和类型
 */

/**
 * 图像生成参数
 */
interface ImageGenerationParams {
    filePath?: string[];
    model?: string;
    prompt: string;
    aspectRatio?: string;
    sample_strength?: number;
    negative_prompt?: string;
    refresh_token?: string;
    req_key?: string;
    blend_mode?: 'single' | 'multi';
    reference_strength?: number[];
    count?: number;
    /**
     * 是否异步模式
     * - false (默认): 同步等待生成完成，返回图片URL数组
     * - true: 立即返回historyId，不等待完成
     */
    async?: boolean;
    /**
     * 多帧场景描述数组
     * - 最多15个元素
     * - 非空字符串才有效
     * - 会与prompt组合成最终提示词
     *
     * @example
     * frames: ["实验室场景", "时空隧道", "外星球"]
     * 最终prompt: "{prompt} 实验室场景 时空隧道 外星球，一共3张图"
     */
    frames?: string[];
}
/**
 * 多帧配置
 */
interface MultiFrameConfig {
    idx: number;
    duration_ms: number;
    prompt: string;
    image_path: string;
}
/**
 * 视频生成参数
 */
interface VideoGenerationParams {
    filePath?: string[];
    model?: string;
    prompt: string;
    refresh_token?: string;
    req_key?: string;
    resolution?: string;
    multiFrames?: MultiFrameConfig[];
    duration_ms?: number;
    fps?: number;
    video_aspect_ratio?: string;
}
/**
 * 视频后处理基础参数
 */
interface VideoPostProcessParams {
    videoId: string;
    originHistoryId: string;
    refresh_token?: string;
}
/**
 * 帧插值参数
 */
interface FrameInterpolationParams extends VideoPostProcessParams {
    targetFps: 30 | 60;
    originFps: number;
    duration?: number;
}
/**
 * 超分辨率参数
 */
interface SuperResolutionParams extends VideoPostProcessParams {
    targetWidth: number;
    targetHeight: number;
    originWidth: number;
    originHeight: number;
}
/**
 * 音效生成参数
 */
interface AudioEffectGenerationParams extends VideoPostProcessParams {
}
/**
 * 统一视频后处理参数
 */
interface VideoPostProcessUnifiedParams {
    operation: 'frame_interpolation' | 'super_resolution' | 'audio_effect';
    videoId: string;
    originHistoryId: string;
    refresh_token?: string;
    targetFps?: 30 | 60;
    originFps?: number;
    targetWidth?: number;
    targetHeight?: number;
    originWidth?: number;
    originHeight?: number;
    duration?: number;
}

/**
 * 宽高比预设选项 - 使用API官方预定义尺寸
 */
interface AspectRatioPreset {
    name: string;
    ratio: number;
    displayName: string;
    imageRatio: number;
    width: number;
    height: number;
    resolutionType: string;
}
/**
 * 宽高比预设列表 - 基于JiMeng API官方预定义的8种尺寸
 * 对应API返回的 image_ratio_sizes 数组
 */
declare const ASPECT_RATIO_PRESETS: AspectRatioPreset[];

interface DimensionInfo {
    width: number;
    height: number;
    resolutionType: string;
}

declare class ImageDimensionCalculator {
    static calculateDimensions(aspectRatio?: string, width?: number, height?: number): DimensionInfo;
    private static getResolutionType;
    static getAspectRatioPreset(name: string): AspectRatioPreset | undefined;
    static getAspectRatioByName(ratioName: string): number;
}

/**
 * JimengClient - 重构后的主客户端（组合模式）
 *
 * 架构变更：
 * - 移除 extends BaseClient 继承
 * - 使用组合模式：注入 HttpClient, ImageUploader, NewCreditService, VideoService
 * - 保持所有现有API签名不变（100%向后兼容）
 * - 旧方法静默重定向到新方法（无警告）
 */

/**
 * JimengClient - 组合模式实现
 */
declare class NewJimengClient {
    private httpClient;
    private imageUploader;
    private creditService;
    private videoService;
    private promptValidator;
    constructor(token?: string);
    /**
     * 图片生成（保持100%向后兼容）
     * 支持继续生成功能（>4张自动触发）
     */
    generateImage(params: ImageGenerationParams & {
        async: true;
    }): Promise<string>;
    generateImage(params: ImageGenerationParams & {
        async?: false;
    }): Promise<string[]>;
    /**
     * 异步提交图像生成任务
     */
    generateImageAsync(params: ImageGenerationParams): Promise<string>;
    /**
     * 查询图像/视频生成结果
     * 自动判断ID类型：UUID格式使用submit_ids，数字格式使用history_ids
     */
    getImageResult(historyId: string): Promise<any>;
    /**
     * 批量查询任务结果（真正的批量API）
     * 自动按ID类型分组：图片用history_ids，视频用submit_ids
     */
    getBatchResults(ids: string[]): Promise<Record<string, any>>;
    /**
     * 解析查询结果（提取公共逻辑）
     */
    private parseQueryResult;
    /**
     * 执行同步继续生成（用于同步模式）
     * 发送一次继续生成确认，告诉 API 继续完成所有剩余图片
     * 不等待完成，让调用者继续轮询原始 historyId
     */
    private performSyncContinueGeneration;
    /**
     * 执行异步继续生成（智能继续生成核心方法）
     * [CONSTITUTION-EXCEPTION: Tech Debt] 重构以使用CacheManager
     */
    private performAsyncContinueGeneration;
    /**
     * 旧视频生成API（向后兼容，静默重定向）
     */
    generateVideo(params: VideoGenerationParams): Promise<string>;
    /**
     * 文生视频（新API）
     */
    generateTextToVideo(params: any): Promise<any>;
    /**
     * 多帧视频（新API）
     */
    generateMultiFrameVideo(params: any): Promise<any>;
    /**
     * 主参考视频（新API）
     */
    generateMainReferenceVideo(params: MainReferenceVideoParams): Promise<string>;
    /**
     * 主参考视频（统一API）
     */
    generateMainReferenceVideoUnified(params: any): Promise<any>;
    /**
     * 查询视频生成结果（单个）
     */
    queryVideoResult(submitId: string): Promise<any>;
    /**
     * 批量查询视频生成结果
     */
    queryVideoResults(submitIds: string[]): Promise<Record<string, any>>;
    /**
     * 视频后处理（帧插值、超分辨率、音效）
     */
    videoPostProcess(params: any): Promise<any>;
    /**
     * 帧插值（视频后处理）
     */
    frameInterpolation(params: any): Promise<string>;
    /**
     * 超分辨率（视频后处理）
     */
    superResolution(params: any): Promise<string>;
    /**
     * 音效生成（视频后处理）
     */
    generateAudioEffect(params: any): Promise<string>;
    /**
     * 获取积分
     */
    getCredits(): Promise<number>;
    /**
     * 获取详细积分信息
     */
    getCredit(): Promise<any>;
    /**
     * 领取积分
     */
    receiveCredit(): Promise<void>;
    /**
     * 提交图片生成任务
     *
     * [CONSTITUTION-EXCEPTION: Tech Debt] 重构以使用CacheManager
     * @param apiParams - API parameters for request
     * @param originalParams - Optional original user parameters (for cache)
     * @param uploadedImages - Optional uploaded images (for cache)
     */
    private submitImageTask;
    /**
     * 构建初始请求参数（首次生成）
     *
     * [CONSTITUTION-EXCEPTION: Tech Debt] 提取自submitImageTask方法以降低复杂度
     * @param params - API parameters
     */
    private buildInitialRequest;
    /**
     * 构建继续生成请求参数
     *
     * [CONSTITUTION-EXCEPTION: Tech Debt] 提取自submitImageTask方法以降低复杂度
     */
    private buildContinuationRequest;
    /**
     * 构建abilities结构
     */
    private buildAbilities;
    /**
     * 等待图片生成完成
     * 注意：缓存清理延迟到 generateImage 末尾，以支持手动继续生成
     *
     * @returns { imageUrls, totalCount, isPartial }
     *   - imageUrls: 已生成的图片URL数组
     *   - totalCount: API返回的总目标数量
     *   - isPartial: 是否为部分完成（需要继续生成）
     */
    private waitForImageCompletion;
    /**
     * 睡眠函数
     */
    private sleep;
    /**
     * 验证并过滤frames数组（与旧代码一致）
     */
    private validateAndFilterFrames;
    /**
     * 构建包含frames的最终prompt（与旧代码一致）
     */
    private buildPromptWithFrames;
    /**
     * 获取refresh token
     */
    getRefreshToken(): string;
}

/**
 * HttpClient - HTTP请求客户端
 * 整合auth.ts和a_bogus.ts中的认证逻辑
 * 提供统一的HTTP请求接口
 */
interface RequestOptions {
    url: string;
    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
    data?: any;
    headers?: Record<string, string>;
    params?: Record<string, any>;
    timeout?: number;
}
/**
 * HttpClient类
 * 使用组合模式，独立于继承体系
 */
declare class HttpClient {
    private refreshToken;
    constructor(token?: string);
    /**
     * 执行HTTP请求
     */
    request<T = any>(options: RequestOptions): Promise<T>;
    /**
     * 生成请求认证参数（用于图片上传等）
     */
    generateRequestParams(): any;
    /**
     * 生成认证头和签名（用于ImageX API）
     */
    generateAuthorizationAndHeader(accessKeyId: string, secretAccessKey: string, sessionToken: string, region: string, service: string, method: string, params?: Record<string, any>, data?: Record<string, any>): Promise<Record<string, string>>;
    /**
     * 生成Authorization签名（完整AWS4-HMAC-SHA256算法）
     */
    private generateAuthorization;
    /**
     * 构建规范化的请求头字符串
     */
    private buildCanonicalHeaders;
    /**
     * 构建已签名的请求头列表
     */
    private buildSignedHeaders;
    /**
     * HTTP查询字符串构建
     */
    httpBuildQuery(params: Record<string, any>): string;
    /**
     * 生成随机字符串
     */
    generateRandomString(length: number): string;
    /**
     * 获取refresh token
     */
    getRefreshToken(): string;
    /**
     * 统一错误处理
     */
    private handleError;
}

/**
 * ImageUploader - 图片上传服务
 * 使用image-size库替代手动解析（删除132行代码）
 * 提供图片上传、格式检测和批量上传功能
 * 支持图片上传步骤的自动重试机制
 */

interface UploadResult {
    uri: string;
    originalPath: string;
    width: number;
    height: number;
    format: string;
}
interface ImageMetadata {
    format: 'png' | 'jpeg' | 'jpg' | 'webp' | 'gif';
    width: number;
    height: number;
}
/**
 * ImageUploader类
 * 使用组合模式，依赖HttpClient而非继承
 */
declare class ImageUploader {
    private httpClient;
    constructor(httpClient: HttpClient);
    /**
     * 上传单张图片
     */
    upload(imagePath: string): Promise<UploadResult>;
    /**
     * 批量上传图片（并行处理）
     */
    uploadBatch(imagePaths: string[]): Promise<UploadResult[]>;
    /**
     * 检测图片格式和尺寸（使用image-size库，替代132行手动解析）
     */
    detectFormat(pathOrBuffer: string | Buffer): ImageMetadata;
    /**
     * 读取文件内容（支持本地文件和HTTP URL）
     */
    private getFileContent;
    /**
     * 上传图片数据（带重试机制）
     * 这是唯一需要重试的步骤，因为网络传输最容易失败
     */
    private uploadImageDataWithRetry;
    /**
     * 获取上传凭证
     */
    private getUploadAuth;
}

/**
 * VideoService - 统一视频生成服务
 * 合并4个独立生成器的功能（TextToVideo, MultiFrame, MainReference）
 * 内联轮询逻辑（≤30行），移除timeout.ts依赖
 * 使用组合模式，依赖HttpClient和ImageUploader
 */

interface VideoResult {
    videoUrl?: string;
    taskId?: string;
    metadata: {
        model: string;
        resolution: string;
        duration: number;
        fps: number;
    };
}
interface TextToVideoParams {
    prompt: string;
    model?: string;
    resolution?: '720p' | '1080p';
    fps?: number;
    duration?: number;
    async?: boolean;
    firstFrameImage?: string;
    lastFrameImage?: string;
    videoAspectRatio?: string;
}
interface FrameConfig {
    idx: number;
    imagePath: string;
    duration_ms: number;
    prompt: string;
}
interface MultiFrameParams {
    frames: FrameConfig[];
    model?: string;
    resolution?: '720p' | '1080p';
    fps?: number;
    async?: boolean;
    videoAspectRatio?: string;
}
interface MainReferenceParams {
    referenceImages: string[];
    prompt: string;
    model?: string;
    resolution?: '720p' | '1080p';
    fps?: number;
    duration?: number;
    async?: boolean;
    videoAspectRatio?: string;
}
/**
 * VideoService类
 * 整合所有视频生成功能
 */
declare class VideoService {
    private httpClient;
    private imageUploader;
    constructor(httpClient: HttpClient, imageUploader: ImageUploader);
    /**
     * 文本生成视频（支持首尾帧）
     */
    generateTextToVideo(params: TextToVideoParams): Promise<VideoResult>;
    /**
     * 生成UUID（本地方法）
     */
    private generateUuid;
    /**
     * 多帧视频生成（2-10帧）
     */
    generateMultiFrame(params: MultiFrameParams): Promise<VideoResult>;
    /**
     * 主参考视频生成（2-4张参考图）
     */
    generateMainReference(params: MainReferenceParams): Promise<VideoResult>;
    /**
     * 上传多个帧图片
     */
    private uploadFrames;
    /**
     * 提交draft格式的视频生成任务
     */
    private submitTaskWithDraft;
    /**
     * 轮询直到任务完成（内联实现，≤30行）
     */
    private pollUntilComplete;
    /**
     * 检查任务状态
     */
    private checkTaskStatus;
    /**
     * 深度搜索对象中的URL字段
     */
    private deepSearchUrl;
    /**
     * 睡眠函数
     */
    private sleep;
    /**
     * 查询视频生成结果（单个）
     */
    queryVideo(submitId: string): Promise<any>;
    /**
     * 批量查询视频生成结果
     */
    queryVideoBatch(submitIds: string[]): Promise<Record<string, any>>;
    /**
     * 解析主参考提示词（提取[图N]引用）
     */
    private parseMainReferencePrompt;
    /**
     * 构建idip_meta_list（主参考模式参数）
     * 正确格式参考: generate_zhuti_request.json
     */
    private buildIdipMetaList;
}

/**
 * CreditService - 积分管理服务
 * 使用组合模式，依赖HttpClient而非继承
 * 负责积分查询和领取功能
 */

interface CreditInfo {
    giftCredit: number;
    purchaseCredit: number;
    vipCredit: number;
    totalCredit: number;
}
/**
 * CreditService类（新版本 - 组合模式）
 */
declare class NewCreditService {
    private httpClient;
    constructor(httpClient: HttpClient);
    /**
     * 获取积分余额
     */
    getBalance(): Promise<number>;
    /**
     * 获取详细积分信息
     */
    getCredit(): Promise<CreditInfo>;
    /**
     * 领取积分
     */
    receiveCredit(): Promise<void>;
    /**
     * 检查是否有足够积分
     */
    hasEnoughCredits(amount: number): Promise<boolean>;
    /**
     * 扣除积分（记录原因）
     */
    deductCredits(amount: number, reason: string): Promise<void>;
}

/**
 * JiMeng MCP API - 重构后的主入口文件
 *
 * 📁 此文件已重构为模块化架构，原2800+行代码被拆分为以下模块：
 * - src/types/api.types.ts - API类型定义 (200行)
 * - src/types/models.ts - 模型映射和常量 (80行)
 * - src/api/ApiClient.ts - 基础API客户端 (90行)
 * - src/api/CreditService.ts - 积分服务 (40行)
 * - src/api/JimengClient.ts - 统一客户端 (400行)
 * - src/utils/auth.ts - 认证工具 (200行)
 * - src/utils/dimensions.ts - 尺寸计算工具 (已存在)
 *
 * ✅ 保持完全向后兼容 - 所有现有代码无需修改即可正常工作
 * 🔄 如遇问题，可使用 api-original-backup.ts 作为备用方案
 */

declare const getApiClient: (token?: string) => NewJimengClient;
/**
 * 图像生成 - 统一接口，支持同步和异步模式
 * ✨ 支持所有新特性：单图参考、多图参考、Draft-based响应、creation_agent模式、多帧场景描述
 */
declare function generateImage(params: ImageGenerationParams & {
    async: true;
}): Promise<string>;
declare function generateImage(params: ImageGenerationParams & {
    async?: false;
}): Promise<string[]>;
/**
 * 视频生成 - 与原API完全兼容
 * ✨ 支持传统模式和智能多帧模式
 */
declare const generateVideo: (params: VideoGenerationParams) => Promise<string>;
declare function frameInterpolation(params: FrameInterpolationParams): Promise<string>;
declare function superResolution(params: SuperResolutionParams): Promise<string>;
declare function generateAudioEffect(params: AudioEffectGenerationParams): Promise<string>;
declare function videoPostProcess(params: VideoPostProcessUnifiedParams): Promise<string>;

export { ASPECT_RATIO_PRESETS, HttpClient, ImageDimensionCalculator, ImageUploader, NewJimengClient as JimengClient, NewCreditService, VideoService, frameInterpolation, generateAudioEffect, generateImage, generateVideo, getApiClient, superResolution, videoPostProcess };