koishi-plugin-ai-video 0.0.1

package/lib/index.d.ts

@@ -0,0 +1,204 @@
+import { Schema } from 'koishi';
+export declare const name = "ai-video";
+export declare const inject: {
+    required: string[];
+    optional: string[];
+};
+type Infer<T> = T extends Schema<infer U> ? U : never;
+export declare const Config: Schema<Schemastery.ObjectS<{
+    debug: Schema<boolean, boolean>;
+    timeout: Schema<number, number>;
+    rateLimit: Schema<number, number>;
+    maxVideos: Schema<number, number>;
+    videoDuration: Schema<number, number>;
+    videoResolution: Schema<string, string>;
+    enableForward: Schema<boolean, boolean>;
+    enableTxt2Video: Schema<boolean, boolean>;
+    enableImg2Video: Schema<boolean, boolean>;
+    videoSendMode: Schema<"video" | "url" | "both", "video" | "url" | "both">;
+    pollEnabled: Schema<boolean, boolean>;
+    pollInterval: Schema<number, number>;
+    pollTimeout: Schema<number, number>;
+}> | Schemastery.ObjectS<{
+    proxyEnabled: Schema<boolean, boolean>;
+    proxyProtocol: Schema<"http" | "https", "http" | "https">;
+    proxyHost: Schema<string, string>;
+    proxyPort: Schema<number, number>;
+    proxyAuth: Schema<boolean, boolean>;
+    proxyUsername: Schema<string, string>;
+    proxyPassword: Schema<string, string>;
+}> | Schemastery.ObjectS<{
+    useCustomApi: Schema<boolean, boolean>;
+    apiEndpoint: Schema<string, string>;
+    apiKey: Schema<string, string>;
+    model: Schema<string, string>;
+    img2videoModel: Schema<string, string>;
+    videoDuration: Schema<number, number>;
+    videoResolution: Schema<string, string>;
+    txt2videoPrompt: Schema<string, string>;
+    img2videoPrompt: Schema<string, string>;
+    customHeaders: Schema<string, string>;
+}> | Schemastery.ObjectS<{
+    apiStrategy: Schema<"sequence" | "roundrobin", "sequence" | "roundrobin">;
+    customApiList: Schema<Schemastery.ObjectS<{
+        enable: Schema<boolean, boolean>;
+        endpoint: Schema<string, string>;
+        apiKey: Schema<string, string>;
+        model: Schema<string, string>;
+        img2videoModel: Schema<string, string>;
+        videoDuration: Schema<number, number>;
+        videoResolution: Schema<string, string>;
+        txt2videoPrompt: Schema<string, string>;
+        img2videoPrompt: Schema<string, string>;
+        customHeaders: Schema<string, string>;
+        bodyTemplate: Schema<string, string>;
+    }>[], Schemastery.ObjectT<{
+        enable: Schema<boolean, boolean>;
+        endpoint: Schema<string, string>;
+        apiKey: Schema<string, string>;
+        model: Schema<string, string>;
+        img2videoModel: Schema<string, string>;
+        videoDuration: Schema<number, number>;
+        videoResolution: Schema<string, string>;
+        txt2videoPrompt: Schema<string, string>;
+        img2videoPrompt: Schema<string, string>;
+        customHeaders: Schema<string, string>;
+        bodyTemplate: Schema<string, string>;
+    }>[]>;
+}> | Schemastery.ObjectS<{
+    blacklistAdmins: Schema<string[], string[]>;
+}> | Schemastery.ObjectS<{
+    messages: Schema<Schemastery.ObjectS<{
+        generating: Schema<string, string>;
+        empty: Schema<string, string>;
+        noApi: Schema<string, string>;
+        fail: Schema<string, string>;
+        noContent: Schema<string, string>;
+        templateError: Schema<string, string>;
+        txt2videoDisabled: Schema<string, string>;
+        img2videoDisabled: Schema<string, string>;
+        rateLimit: Schema<string, string>;
+        needAssets: Schema<string, string>;
+        blacklisted: Schema<string, string>;
+        noPermission: Schema<string, string>;
+        blacklistAddSuccess: Schema<string, string>;
+        blacklistRemoveSuccess: Schema<string, string>;
+        blacklistAddFail: Schema<string, string>;
+        blacklistRemoveFail: Schema<string, string>;
+        invalidUserId: Schema<string, string>;
+        blacklistListEmpty: Schema<string, string>;
+        blacklistListTitle: Schema<string, string>;
+        noLastTask: Schema<string, string>;
+        redrawing: Schema<string, string>;
+        redrawImg2Video: Schema<string, string>;
+    }>, Schemastery.ObjectT<{
+        generating: Schema<string, string>;
+        empty: Schema<string, string>;
+        noApi: Schema<string, string>;
+        fail: Schema<string, string>;
+        noContent: Schema<string, string>;
+        templateError: Schema<string, string>;
+        txt2videoDisabled: Schema<string, string>;
+        img2videoDisabled: Schema<string, string>;
+        rateLimit: Schema<string, string>;
+        needAssets: Schema<string, string>;
+        blacklisted: Schema<string, string>;
+        noPermission: Schema<string, string>;
+        blacklistAddSuccess: Schema<string, string>;
+        blacklistRemoveSuccess: Schema<string, string>;
+        blacklistAddFail: Schema<string, string>;
+        blacklistRemoveFail: Schema<string, string>;
+        invalidUserId: Schema<string, string>;
+        blacklistListEmpty: Schema<string, string>;
+        blacklistListTitle: Schema<string, string>;
+        noLastTask: Schema<string, string>;
+        redrawing: Schema<string, string>;
+        redrawImg2Video: Schema<string, string>;
+    }>>;
+}>, {
+    debug: boolean;
+    timeout: number;
+    rateLimit: number;
+    maxVideos: number;
+    videoDuration: number;
+    videoResolution: string;
+    enableForward: boolean;
+    enableTxt2Video: boolean;
+    enableImg2Video: boolean;
+    videoSendMode: "video" | "url" | "both";
+    pollEnabled: boolean;
+    pollInterval: number;
+    pollTimeout: number;
+} & import("cosmokit").Dict & {
+    proxyEnabled: boolean;
+    proxyProtocol: "http" | "https";
+    proxyHost: string;
+    proxyPort: number;
+    proxyAuth: boolean;
+    proxyUsername: string;
+    proxyPassword: string;
+} & {
+    useCustomApi: boolean;
+    apiEndpoint: string;
+    apiKey: string;
+    model: string;
+    img2videoModel: string;
+    videoDuration: number;
+    videoResolution: string;
+    txt2videoPrompt: string;
+    img2videoPrompt: string;
+    customHeaders: string;
+} & {
+    apiStrategy: "sequence" | "roundrobin";
+    customApiList: Schemastery.ObjectT<{
+        enable: Schema<boolean, boolean>;
+        endpoint: Schema<string, string>;
+        apiKey: Schema<string, string>;
+        model: Schema<string, string>;
+        img2videoModel: Schema<string, string>;
+        videoDuration: Schema<number, number>;
+        videoResolution: Schema<string, string>;
+        txt2videoPrompt: Schema<string, string>;
+        img2videoPrompt: Schema<string, string>;
+        customHeaders: Schema<string, string>;
+        bodyTemplate: Schema<string, string>;
+    }>[];
+} & {
+    blacklistAdmins: string[];
+} & {
+    messages: Schemastery.ObjectT<{
+        generating: Schema<string, string>;
+        empty: Schema<string, string>;
+        noApi: Schema<string, string>;
+        fail: Schema<string, string>;
+        noContent: Schema<string, string>;
+        templateError: Schema<string, string>;
+        txt2videoDisabled: Schema<string, string>;
+        img2videoDisabled: Schema<string, string>;
+        rateLimit: Schema<string, string>;
+        needAssets: Schema<string, string>;
+        blacklisted: Schema<string, string>;
+        noPermission: Schema<string, string>;
+        blacklistAddSuccess: Schema<string, string>;
+        blacklistRemoveSuccess: Schema<string, string>;
+        blacklistAddFail: Schema<string, string>;
+        blacklistRemoveFail: Schema<string, string>;
+        invalidUserId: Schema<string, string>;
+        blacklistListEmpty: Schema<string, string>;
+        blacklistListTitle: Schema<string, string>;
+        noLastTask: Schema<string, string>;
+        redrawing: Schema<string, string>;
+        redrawImg2Video: Schema<string, string>;
+    }>;
+}>;
+declare module 'koishi' {
+    interface Tables {
+        ai_video_blacklist: AIVideoBlacklist;
+    }
+}
+interface AIVideoBlacklist {
+    id: string;
+    createdAt: Date;
+}
+export declare function apply(ctx: any, cfg: Infer<typeof Config>): Promise<void>;
+export {};

package/lib/index.js

@@ -0,0 +1,683 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = exports.inject = exports.name = void 0;
+exports.apply = apply;
+const koishi_1 = require("koishi");
+const axios_1 = __importDefault(require("axios"));
+const yaml_1 = __importDefault(require("yaml"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.name = 'ai-video';
+exports.inject = {
+    required: ['console', 'i18n', 'database'],
+    optional: ['assets'],
+};
+const logger = new koishi_1.Logger('ai-video');
+exports.Config = koishi_1.Schema.intersect([
+    koishi_1.Schema.object({
+        debug: koishi_1.Schema.boolean().default(false).description('开启调试模式，输出完整请求日志'),
+        timeout: koishi_1.Schema.number().default(600000).description('接口请求超时时间（毫秒），视频生成较慢，建议加大'),
+        rateLimit: koishi_1.Schema.number().default(50).description('每小时调用次数限制'),
+        maxVideos: koishi_1.Schema.number().default(1).description('单次生成最多视频数量'),
+        videoDuration: koishi_1.Schema.number().default(5).description('默认视频时长（秒）'),
+        videoResolution: koishi_1.Schema.string().default('1024x576').description('默认视频分辨率（宽x高）'),
+        enableForward: koishi_1.Schema.boolean().default(true).description('多视频结果是否使用合并转发'),
+        enableTxt2Video: koishi_1.Schema.boolean().default(true).description('启用文生视频功能'),
+        enableImg2Video: koishi_1.Schema.boolean().default(true).description('启用图生视频功能'),
+        videoSendMode: koishi_1.Schema.union([
+            koishi_1.Schema.const('video').description('仅发送视频文件'),
+            koishi_1.Schema.const('url').description('仅发送视频链接'),
+            koishi_1.Schema.const('both').description('发送视频文件和链接'),
+        ]).default('video').description('生成结果发送方式'),
+        pollEnabled: koishi_1.Schema.boolean().default(false).description('是否启用异步轮询（若 API 返回任务 ID 则自动轮询至完成）'),
+        pollInterval: koishi_1.Schema.number().default(3000).description('轮询间隔（毫秒）'),
+        pollTimeout: koishi_1.Schema.number().default(600000).description('轮询总超时时间（毫秒）'),
+    }).description('基本设置'),
+    koishi_1.Schema.object({
+        proxyEnabled: koishi_1.Schema.boolean().default(false).description('是否启用 HTTP/HTTPS 代理'),
+        proxyProtocol: koishi_1.Schema.union([
+            koishi_1.Schema.const('http').description('HTTP'),
+            koishi_1.Schema.const('https').description('HTTPS'),
+        ]).default('http').description('代理协议'),
+        proxyHost: koishi_1.Schema.string().default('').description('代理地址'),
+        proxyPort: koishi_1.Schema.number().default(8080).description('代理端口'),
+        proxyAuth: koishi_1.Schema.boolean().default(false).description('代理是否需要认证'),
+        proxyUsername: koishi_1.Schema.string().default('').description('代理用户名'),
+        proxyPassword: koishi_1.Schema.string().role('secret').default('').description('代理密码'),
+    }).description('代理设置'),
+    koishi_1.Schema.object({
+        useCustomApi: koishi_1.Schema.boolean().default(false).description('是否使用自定义 API 配置（开启后下方自定义列表生效）'),
+        apiEndpoint: koishi_1.Schema.string().default('https://api.openai.com/v1/video/generations').description('API 端点地址'),
+        apiKey: koishi_1.Schema.string().role('secret').default('').description('API 密钥'),
+        model: koishi_1.Schema.string().default('video-generation-model').description('模型名称'),
+        img2videoModel: koishi_1.Schema.string().default('').description('图生视频专用模型名称（留空则使用上方模型）'),
+        videoDuration: koishi_1.Schema.number().default(0).description('视频时长（秒，留空则使用全局默认）'),
+        videoResolution: koishi_1.Schema.string().default('').description('视频分辨率（留空则使用全局默认）'),
+        txt2videoPrompt: koishi_1.Schema.string().default('').description('文生视频提示词模板。变量：{prompt}（留空则直接使用用户输入）'),
+        img2videoPrompt: koishi_1.Schema.string().default('').description('图生视频提示词模板。变量：{url} {prompt}（留空则直接使用用户输入）'),
+        customHeaders: koishi_1.Schema.string().role('textarea').default('{}').description('自定义请求头 JSON 对象（合并到默认请求头）'),
+    }).description('内置 API 设置'),
+    koishi_1.Schema.object({
+        apiStrategy: koishi_1.Schema.union([
+            koishi_1.Schema.const('sequence').description('顺序模式'),
+            koishi_1.Schema.const('roundrobin').description('负载均衡模式'),
+        ]).default('roundrobin').description('API 调度策略'),
+        customApiList: koishi_1.Schema.array(koishi_1.Schema.object({
+            enable: koishi_1.Schema.boolean().default(true).description('是否启用此 API'),
+            endpoint: koishi_1.Schema.string().default('https://api.openai.com/v1/video/generations').description('API 端点地址'),
+            apiKey: koishi_1.Schema.string().role('secret').default('').description('API 密钥'),
+            model: koishi_1.Schema.string().default('video-generation-model').description('模型名称'),
+            img2videoModel: koishi_1.Schema.string().default('').description('图生视频专用模型名称（留空则使用上方模型）'),
+            videoDuration: koishi_1.Schema.number().default(0).description('视频时长（秒，留空使用全局默认）'),
+            videoResolution: koishi_1.Schema.string().default('').description('视频分辨率（留空使用全局默认）'),
+            txt2videoPrompt: koishi_1.Schema.string().default('').description('文生视频提示词模板。变量：{prompt}（留空则直接使用用户输入）'),
+            img2videoPrompt: koishi_1.Schema.string().default('').description('图生视频提示词模板。变量：{url} {prompt}（留空则直接使用用户输入）'),
+            customHeaders: koishi_1.Schema.string().role('textarea')
+                .default('{"Authorization":"Bearer {apiKey}","Content-Type":"application/json"}')
+                .description('自定义请求头 JSON，支持 {apiKey} 变量'),
+            bodyTemplate: koishi_1.Schema.string().role('textarea')
+                .default(JSON.stringify({
+                txt2videoBody: { model: '{model}', prompt: '{prompt}', duration: '{duration}', size: '{size}' },
+                img2videoBody: { model: '{model}', prompt: '{prompt}', duration: '{duration}', size: '{size}', image_url: '{url}' },
+                responseVideoPath: 'video_url',
+                pollUrlTemplate: '{endpoint}/{task_id}',
+                taskIdPath: 'task_id',
+            }, null, 2))
+                .description('自定义请求体 JSON 模板（高级，留空使用内置格式）。\n支持变量：{model}、{prompt}、{duration}、{size}、{url}。\n轮询配置可选：pollUrlTemplate、taskIdPath'),
+        })).default([]).description('自定义 API 配置列表（仅当"使用自定义 API 配置"开启时生效）'),
+    }).description('自定义 API 配置'),
+    koishi_1.Schema.object({
+        blacklistAdmins: koishi_1.Schema.array(String).default([]).description('黑名单管理员的 QQ 号列表'),
+    }).description('权限管理'),
+    koishi_1.Schema.object({
+        messages: koishi_1.Schema.object({
+            generating: koishi_1.Schema.string().default('视频生成中，请耐心等待...').description('开始生成视频时的提示'),
+            empty: koishi_1.Schema.string().default('[提示] 请输入提示词').description('未输入提示词时的提示'),
+            noApi: koishi_1.Schema.string().default('[提示] 未配置可用API').description('无可用 API 时的提示'),
+            fail: koishi_1.Schema.string().default('[提示] 视频生成失败').description('视频生成失败时的提示'),
+            noContent: koishi_1.Schema.string().default('（未返回任何视频内容）').description('API 返回空结果时的追加提示'),
+            templateError: koishi_1.Schema.string().default('（模板配置错误）').description('请求体模板解析失败时的追加提示'),
+            txt2videoDisabled: koishi_1.Schema.string().default('[提示] 文生视频功能未启用').description('文生视频被禁用时的提示'),
+            img2videoDisabled: koishi_1.Schema.string().default('[提示] 图生视频功能未启用').description('图生视频被禁用时的提示'),
+            rateLimit: koishi_1.Schema.string().default('[提示] 调用次数已达上限，请稍后再试').description('触发频率限制时的提示'),
+            needAssets: koishi_1.Schema.string().default('[提示] 图生视频需要正确配置 assets 服务（selfUrl 未正确设置或服务未启动）').description('缺少 assets 服务时的提示'),
+            blacklisted: koishi_1.Schema.string().default('[提示] 你已被加入黑名单，无法使用视频生成功能').description('黑名单用户被拦截时的提示'),
+            noPermission: koishi_1.Schema.string().default('[提示] 你没有权限管理黑名单').description('无黑名单管理权限时的提示'),
+            blacklistAddSuccess: koishi_1.Schema.string().default('已将 {targets} 加入黑名单').description('黑名单添加成功的提示'),
+            blacklistRemoveSuccess: koishi_1.Schema.string().default('已将 {targets} 移出黑名单').description('黑名单移除成功的提示'),
+            blacklistAddFail: koishi_1.Schema.string().default('{targets} 已在黑名单中或无效').description('黑名单添加失败的提示'),
+            blacklistRemoveFail: koishi_1.Schema.string().default('{targets} 不在黑名单中').description('黑名单移除失败的提示'),
+            invalidUserId: koishi_1.Schema.string().default('无效的QQ号：{targets}').description('无效 QQ 号的提示'),
+            blacklistListEmpty: koishi_1.Schema.string().default('当前黑名单为空').description('黑名单为空时的提示'),
+            blacklistListTitle: koishi_1.Schema.string().default('当前黑名单：').description('黑名单列表标题'),
+            noLastTask: koishi_1.Schema.string().default('没有上一次生成记录，无法重绘').description('无重绘历史时的提示'),
+            redrawing: koishi_1.Schema.string().default('正在重绘上一次文生视频...').description('重绘开始时的提示'),
+            redrawImg2Video: koishi_1.Schema.string().default('[提示] 重绘仅支持文生视频任务，图生视频任务请直接发起新的图生视频指令').description('图生视频任务无法重绘时的提示'),
+        }).description('所有提示文案的自定义配置，支持模板变量'),
+    }).description('消息文本'),
+]);
+async function apply(ctx, cfg) {
+    const debug = cfg.debug;
+    try {
+        const loc = path_1.default.join(__dirname, 'locales', 'zh-CN.yml');
+        if (fs_1.default.existsSync(loc)) {
+            ctx.i18n.define('zh-CN', yaml_1.default.parse(fs_1.default.readFileSync(loc, 'utf8')));
+        }
+    }
+    catch { }
+    const lastTaskMap = new Map();
+    let apiRoundRobinIdx = 0;
+    const apiCallTimestamps = [];
+    ctx.model.extend('ai_video_blacklist', {
+        id: 'string',
+        createdAt: 'date',
+    }, {
+        primary: 'id',
+    });
+    function checkRateLimit() {
+        const now = Date.now();
+        const oneHourAgo = now - 3600000;
+        let trimIdx = 0;
+        while (trimIdx < apiCallTimestamps.length && apiCallTimestamps[trimIdx] < oneHourAgo) {
+            trimIdx++;
+        }
+        if (trimIdx > 0) {
+            apiCallTimestamps.splice(0, trimIdx);
+        }
+        return apiCallTimestamps.length + 1 <= cfg.rateLimit;
+    }
+    function recordApiCall() {
+        apiCallTimestamps.push(Date.now());
+    }
+    const BUILTIN_TXT2VIDEO = {
+        model: '{model}',
+        prompt: '{prompt}',
+        duration: '{duration}',
+        size: '{size}',
+    };
+    const BUILTIN_IMG2VIDEO = {
+        model: '{model}',
+        prompt: '{prompt}',
+        duration: '{duration}',
+        size: '{size}',
+        image_url: '{url}',
+    };
+    function parseApiEntry(entry) {
+        if (!entry.endpoint)
+            return null;
+        const headers = {
+            'Content-Type': 'application/json'
+        };
+        if (entry.apiKey) {
+            headers['Authorization'] = `Bearer ${entry.apiKey}`;
+        }
+        if (entry.customHeaders) {
+            try {
+                const custom = JSON.parse(entry.customHeaders);
+                for (const [k, v] of Object.entries(custom)) {
+                    headers[k] = typeof v === 'string' ? v.replace(/\{apiKey\}/g, entry.apiKey || '') : String(v);
+                }
+            }
+            catch { }
+        }
+        let txt2videoBody;
+        let img2videoBody;
+        let responseVideoPath;
+        let pollUrlTemplate;
+        let taskIdPath;
+        if (entry.bodyTemplate) {
+            try {
+                const tmpl = JSON.parse(entry.bodyTemplate);
+                txt2videoBody = tmpl.txt2videoBody || BUILTIN_TXT2VIDEO;
+                img2videoBody = tmpl.img2videoBody || BUILTIN_IMG2VIDEO;
+                responseVideoPath = tmpl.responseVideoPath || 'video_url';
+                pollUrlTemplate = tmpl.pollUrlTemplate || '';
+                taskIdPath = tmpl.taskIdPath || '';
+            }
+            catch {
+                return null;
+            }
+        }
+        else {
+            txt2videoBody = BUILTIN_TXT2VIDEO;
+            img2videoBody = BUILTIN_IMG2VIDEO;
+            responseVideoPath = 'video_url';
+            pollUrlTemplate = '';
+            taskIdPath = '';
+        }
+        return {
+            endpoint: entry.endpoint,
+            headers,
+            txt2videoBody,
+            img2videoBody,
+            responseVideoPath,
+            pollUrlTemplate,
+            taskIdPath,
+            method: 'POST',
+            videoDuration: entry.videoDuration || 0,
+            videoResolution: entry.videoResolution || '',
+            txt2videoPrompt: entry.txt2videoPrompt || '',
+            img2videoPrompt: entry.img2videoPrompt || '',
+            model: entry.model,
+            img2videoModel: entry.img2videoModel || '',
+        };
+    }
+    function buildBuiltinApi() {
+        const headers = {
+            'Content-Type': 'application/json'
+        };
+        if (cfg.apiKey) {
+            headers['Authorization'] = `Bearer ${cfg.apiKey}`;
+        }
+        if (cfg.customHeaders) {
+            try {
+                const custom = JSON.parse(cfg.customHeaders);
+                for (const [k, v] of Object.entries(custom)) {
+                    headers[k] = typeof v === 'string' ? v.replace(/\{apiKey\}/g, cfg.apiKey || '') : String(v);
+                }
+            }
+            catch { }
+        }
+        return {
+            endpoint: cfg.apiEndpoint || 'https://api.openai.com/v1/video/generations',
+            headers,
+            txt2videoBody: BUILTIN_TXT2VIDEO,
+            img2videoBody: BUILTIN_IMG2VIDEO,
+            responseVideoPath: 'video_url',
+            pollUrlTemplate: '',
+            taskIdPath: '',
+            method: 'POST',
+            videoDuration: cfg.videoDuration || 0,
+            videoResolution: cfg.videoResolution || '',
+            txt2videoPrompt: cfg.txt2videoPrompt || '',
+            img2videoPrompt: cfg.img2videoPrompt || '',
+            model: cfg.model || 'video-generation-model',
+            img2videoModel: cfg.img2videoModel || '',
+        };
+    }
+    function getApi() {
+        if (cfg.useCustomApi) {
+            const entries = cfg.customApiList.filter((e) => e.enable);
+            if (entries.length === 0)
+                return null;
+            const apis = entries
+                .map((e) => parseApiEntry(e))
+                .filter((a) => a !== null);
+            if (apis.length === 0)
+                return null;
+            if (cfg.apiStrategy === 'sequence')
+                return apis[0];
+            const api = apis[apiRoundRobinIdx % apis.length];
+            apiRoundRobinIdx++;
+            return api;
+        }
+        else {
+            if (!cfg.apiEndpoint && !cfg.apiKey)
+                return null;
+            return buildBuiltinApi();
+        }
+    }
+    function resolveTemplate(template, vars) {
+        const jsonStr = JSON.stringify(template);
+        let processed = jsonStr;
+        for (const [key, value] of Object.entries(vars)) {
+            if (value === undefined || value === null)
+                continue;
+            const regex = new RegExp(`\\{${key}\\}`, 'g');
+            processed = processed.replace(regex, JSON.stringify(String(value)).slice(1, -1));
+        }
+        return JSON.parse(processed);
+    }
+    function getValueByPath(obj, pathStr) {
+        if (!obj || !pathStr)
+            return undefined;
+        const normalized = pathStr.replace(/\[(\d+)\]/g, '.$1');
+        const keys = normalized.split('.').filter(k => k !== '');
+        let current = obj;
+        for (const key of keys) {
+            if (current === undefined || current === null)
+                return undefined;
+            const numKey = /^\d+$/.test(key) ? parseInt(key) : key;
+            current = current[numKey];
+        }
+        return current;
+    }
+    async function pollForResult(pollUrl, headers, path, interval, timeout) {
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            try {
+                const res = await axios_1.default.get(pollUrl, { headers, timeout: 10000 });
+                const status = getValueByPath(res.data, 'status');
+                if (status === 'completed' || status === 'succeeded') {
+                    return res.data;
+                }
+                if (status === 'failed' || status === 'error') {
+                    throw new Error('Task failed');
+                }
+                await new Promise(r => setTimeout(r, interval));
+            }
+            catch (e) {
+                if (e.message === 'Task failed')
+                    throw e;
+                await new Promise(r => setTimeout(r, interval));
+            }
+        }
+        throw new Error('Polling timeout');
+    }
+    async function sendVideo(session, url) {
+        const mode = cfg.videoSendMode;
+        if (mode === 'url') {
+            await safeSend(session, url);
+        }
+        else {
+            try {
+                await safeSend(session, koishi_1.segment.video(url));
+            }
+            catch {
+                if (mode === 'both')
+                    await safeSend(session, url);
+            }
+            if (mode === 'both')
+                await safeSend(session, url);
+        }
+    }
+    async function handleVideoResponse(session, responseData, api) {
+        let videoUrl = getValueByPath(responseData, api.responseVideoPath);
+        if (!videoUrl) {
+            const found = findFirstVideoUrl(responseData);
+            if (found)
+                videoUrl = found;
+        }
+        if (videoUrl && typeof videoUrl === 'string') {
+            await sendVideo(session, videoUrl.trim());
+        }
+        else {
+            await safeSend(session, cfg.messages.fail + cfg.messages.noContent);
+        }
+    }
+    function findFirstVideoUrl(obj) {
+        if (!obj)
+            return null;
+        if (typeof obj === 'string') {
+            const trimmed = obj.trim();
+            if (/^https?:\/\/.+\.(mp4|mov|avi|webm|mkv)(\?.*)?$/i.test(trimmed))
+                return trimmed;
+            return null;
+        }
+        if (Array.isArray(obj)) {
+            for (const item of obj) {
+                const found = findFirstVideoUrl(item);
+                if (found)
+                    return found;
+            }
+        }
+        else if (typeof obj === 'object') {
+            for (const key of Object.keys(obj)) {
+                const found = findFirstVideoUrl(obj[key]);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
+    }
+    function validateEndpointUrl(url) {
+        try {
+            const parsed = new URL(url);
+            return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+        }
+        catch {
+            return false;
+        }
+    }
+    async function safeSend(session, message) {
+        try {
+            await session.send(message);
+        }
+        catch (e) {
+            logger.error('发送消息失败', e);
+        }
+    }
+    function getErrorMessage(err) {
+        if (axios_1.default.isAxiosError(err)) {
+            if (err.code === 'ECONNABORTED')
+                return '请求超时';
+            if (err.response) {
+                const status = err.response.status;
+                if (status === 401)
+                    return 'API Key 无效';
+                if (status === 429)
+                    return '请求过于频繁';
+                if (status >= 500)
+                    return '服务器错误';
+                return `HTTP ${status}`;
+            }
+            return '网络错误';
+        }
+        return err.message?.slice(0, 100) || '未知错误';
+    }
+    function sanitizeForLog(obj, sensitive) {
+        if (!sensitive)
+            return obj;
+        try {
+            const str = JSON.stringify(obj);
+            return JSON.parse(str.split(sensitive).join('***'));
+        }
+        catch {
+            return obj;
+        }
+    }
+    function isValidQQ(id) {
+        return /^\d{5,11}$/.test(id);
+    }
+    async function isBlacklisted(userId) {
+        try {
+            const rows = await ctx.database.get('ai_video_blacklist', { id: userId });
+            return rows.length > 0;
+        }
+        catch (e) {
+            return false;
+        }
+    }
+    async function addToBlacklist(ids) {
+        const success = [];
+        const fail = [];
+        const validIds = ids.filter(id => { if (isValidQQ(id))
+            return true; fail.push(id); return false; });
+        if (validIds.length === 0)
+            return { success, fail };
+        const existing = await ctx.database.get('ai_video_blacklist', { id: validIds });
+        const existingSet = new Set(existing.map((e) => e.id));
+        const toCreate = validIds.filter(id => !existingSet.has(id));
+        for (const id of toCreate) {
+            try {
+                await ctx.database.create('ai_video_blacklist', { id, createdAt: new Date() });
+                success.push(id);
+            }
+            catch {
+                fail.push(id);
+            }
+        }
+        for (const entry of existing)
+            fail.push(entry.id);
+        return { success, fail };
+    }
+    async function removeFromBlacklist(ids) {
+        const success = [];
+        const fail = [];
+        const validIds = ids.filter(id => { if (isValidQQ(id))
+            return true; fail.push(id); return false; });
+        if (validIds.length === 0)
+            return { success, fail };
+        const existing = await ctx.database.get('ai_video_blacklist', { id: validIds });
+        const existingSet = new Set(existing.map((e) => e.id));
+        const toRemove = validIds.filter(id => existingSet.has(id));
+        for (const id of toRemove) {
+            try {
+                await ctx.database.remove('ai_video_blacklist', { id });
+                success.push(id);
+            }
+            catch {
+                fail.push(id);
+            }
+        }
+        for (const id of validIds.filter(id => !existingSet.has(id)))
+            fail.push(id);
+        return { success, fail };
+    }
+    async function customGenerateVideo(session, api, prompt, imageUrl = '', modelOverride) {
+        const isImg2Video = !!imageUrl;
+        const model = modelOverride || (isImg2Video ? (api.img2videoModel || api.model) : api.model);
+        const duration = api.videoDuration || cfg.videoDuration || 5;
+        const resolution = api.videoResolution || cfg.videoResolution || '1024x576';
+        const promptTemplate = isImg2Video ? api.img2videoPrompt : api.txt2videoPrompt;
+        let finalPrompt = prompt;
+        if (promptTemplate) {
+            finalPrompt = promptTemplate.replace('{prompt}', prompt).replace('{url}', imageUrl || '');
+        }
+        const bodyTemplate = isImg2Video ? api.img2videoBody : api.txt2videoBody;
+        const bodyVars = { model, prompt: finalPrompt, duration: String(duration), size: resolution };
+        if (isImg2Video) {
+            bodyVars['url'] = imageUrl;
+        }
+        let body;
+        try {
+            body = resolveTemplate(bodyTemplate, bodyVars);
+        }
+        catch {
+            await safeSend(session, cfg.messages.fail + cfg.messages.templateError);
+            return;
+        }
+        if (!validateEndpointUrl(api.endpoint)) {
+            await safeSend(session, cfg.messages.fail + '（API端点配置无效）');
+            return;
+        }
+        const sensitive = api.headers?.Authorization?.split(' ')[1] || '';
+        if (debug) {
+            logger.info('API请求', JSON.stringify(sanitizeForLog(body, sensitive)));
+        }
+        try {
+            const config = {
+                url: api.endpoint,
+                method: api.method,
+                headers: api.headers,
+                data: body,
+                timeout: cfg.timeout,
+            };
+            if (cfg.proxyEnabled && cfg.proxyHost) {
+                config.proxy = {
+                    protocol: cfg.proxyProtocol,
+                    host: cfg.proxyHost,
+                    port: cfg.proxyPort,
+                    auth: cfg.proxyAuth && cfg.proxyUsername ? { username: cfg.proxyUsername, password: cfg.proxyPassword } : undefined,
+                };
+            }
+            let responseData = (await (0, axios_1.default)(config)).data;
+            if (cfg.pollEnabled && api.taskIdPath) {
+                const taskId = getValueByPath(responseData, api.taskIdPath);
+                if (taskId) {
+                    const pollUrl = api.pollUrlTemplate.replace('{endpoint}', api.endpoint).replace('{task_id}', taskId);
+                    responseData = await pollForResult(pollUrl, api.headers, api.responseVideoPath, cfg.pollInterval, cfg.pollTimeout);
+                }
+            }
+            await handleVideoResponse(session, responseData, api);
+            const userId = `${session.guildId || 'private'}-${session.userId}`;
+            lastTaskMap.set(userId, {
+                prompt,
+                imageUrl,
+                isImg2Video,
+                model,
+                duration,
+                resolution,
+            });
+        }
+        catch (err) {
+            logger.error('视频生成失败', err);
+            await safeSend(session, cfg.messages.fail + ` [${getErrorMessage(err)}]`);
+        }
+    }
+    async function generateVideo(session, prompt, imageUrl = '', modelOverride) {
+        if (!checkRateLimit()) {
+            await safeSend(session, cfg.messages.rateLimit);
+            return;
+        }
+        const api = getApi();
+        if (!api) {
+            await safeSend(session, cfg.messages.noApi);
+            return;
+        }
+        recordApiCall();
+        return customGenerateVideo(session, api, prompt, imageUrl, modelOverride);
+    }
+    ctx.command('video <raw:text>', 'AI视频生成（文生视频/图生视频自动识别）')
+        .action(async ({ session }, raw) => {
+        try {
+            if (!session)
+                return;
+            if (await isBlacklisted(session.userId))
+                return safeSend(session, cfg.messages.blacklisted);
+            const prompt = (raw || '').trim();
+            const imgs = koishi_1.h.select(session.elements, 'img');
+            const hasImage = imgs.length > 0;
+            if (hasImage && !cfg.enableImg2Video)
+                return safeSend(session, cfg.messages.img2videoDisabled);
+            if (!hasImage && !cfg.enableTxt2Video)
+                return safeSend(session, cfg.messages.txt2videoDisabled);
+            if (!prompt) {
+                if (hasImage)
+                    return safeSend(session, '图生视频请提供提示词');
+                return safeSend(session, cfg.messages.empty);
+            }
+            if (prompt.length > 6000)
+                return safeSend(session, '提示词过长，请限制在6000字符以内');
+            if (!hasImage) {
+                await safeSend(session, cfg.messages.generating);
+                await generateVideo(session, prompt);
+                return;
+            }
+            const assets = ctx.assets;
+            if (!assets)
+                return safeSend(session, cfg.messages.needAssets);
+            const uploadResult = await assets.upload(imgs[0].attrs.src, 'ref_image.jpg');
+            if (!uploadResult || !/^https?:\/\//.test(uploadResult)) {
+                return safeSend(session, cfg.messages.needAssets);
+            }
+            await safeSend(session, cfg.messages.generating);
+            await generateVideo(session, prompt, uploadResult);
+        }
+        catch (e) {
+            logger.error('video命令异常', e);
+            await safeSend(session, cfg.messages.fail);
+        }
+    });
+    ctx.command('redraw', '重绘上一次文生视频')
+        .action(async ({ session }) => {
+        try {
+            if (!session)
+                return;
+            if (await isBlacklisted(session.userId))
+                return safeSend(session, cfg.messages.blacklisted);
+            const userId = `${session.guildId || 'private'}-${session.userId}`;
+            const last = lastTaskMap.get(userId);
+            if (!last)
+                return safeSend(session, cfg.messages.noLastTask);
+            if (last.isImg2Video)
+                return safeSend(session, cfg.messages.redrawImg2Video);
+            await safeSend(session, cfg.messages.redrawing);
+            await generateVideo(session, last.prompt, '', last.model);
+        }
+        catch (e) {
+            logger.error('重绘命令异常', e);
+            await safeSend(session, cfg.messages.fail);
+        }
+    });
+    const blacklistCmd = ctx.command('blacklist', '黑名单管理');
+    blacklistCmd.subcommand('.list', '查看黑名单').action(async ({ session }) => {
+        if (!session)
+            return;
+        if (!cfg.blacklistAdmins.includes(session.userId))
+            return safeSend(session, cfg.messages.noPermission);
+        try {
+            const entries = await ctx.database.get('ai_video_blacklist', {});
+            if (entries.length === 0)
+                return safeSend(session, cfg.messages.blacklistListEmpty);
+            const list = entries.map(e => e.id).join('\n');
+            return safeSend(session, cfg.messages.blacklistListTitle + '\n' + list);
+        }
+        catch (e) {
+            return safeSend(session, cfg.messages.fail);
+        }
+    });
+    blacklistCmd.subcommand('.add <...targets:string>', '添加黑名单').action(async ({ session }, ...targets) => {
+        if (!session)
+            return;
+        if (!cfg.blacklistAdmins.includes(session.userId))
+            return safeSend(session, cfg.messages.noPermission);
+        const ids = targets.map(t => t.trim()).filter(id => id.length > 0);
+        const invalid = ids.filter(id => !isValidQQ(id));
+        if (invalid.length)
+            return safeSend(session, cfg.messages.invalidUserId.replace('{targets}', invalid.join(', ')));
+        const { success, fail } = await addToBlacklist(ids);
+        if (success.length)
+            await safeSend(session, cfg.messages.blacklistAddSuccess.replace('{targets}', success.join(', ')));
+        if (fail.length)
+            await safeSend(session, cfg.messages.blacklistAddFail.replace('{targets}', fail.join(', ')));
+    });
+    blacklistCmd.subcommand('.remove <...targets:string>', '移除黑名单').action(async ({ session }, ...targets) => {
+        if (!session)
+            return;
+        if (!cfg.blacklistAdmins.includes(session.userId))
+            return safeSend(session, cfg.messages.noPermission);
+        const ids = targets.map(t => t.trim()).filter(id => id.length > 0);
+        const invalid = ids.filter(id => !isValidQQ(id));
+        if (invalid.length)
+            return safeSend(session, cfg.messages.invalidUserId.replace('{targets}', invalid.join(', ')));
+        const { success, fail } = await removeFromBlacklist(ids);
+        if (success.length)
+            await safeSend(session, cfg.messages.blacklistRemoveSuccess.replace('{targets}', success.join(', ')));
+        if (fail.length)
+            await safeSend(session, cfg.messages.blacklistRemoveFail.replace('{targets}', fail.join(', ')));
+    });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "koishi-plugin-ai-video",
+  "version": "0.0.1",
+  "description": "Koishi AI 视频生成插件，支持文生视频、图生视频",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "locales"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "koishi",
+    "koishi-plugin",
+    "ai",
+    "video",
+    "ai-video",
+    "text-to-video",
+    "image-to-video",
+    "文生视频",
+    "图生视频",
+    "视频生成"
+  ],
+  "author": "Minecraft-1314",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Minecraft-1314/koishi-plugin-ai-video.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Minecraft-1314/koishi-plugin-ai-video/issues"
+  },
+  "homepage": "https://github.com/Minecraft-1314/koishi-plugin-ai-video#readme",
+  "peerDependencies": {
+    "koishi": "^4.18.0"
+  },
+  "dependencies": {
+    "axios": "^1.7.9",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.2"
+  }
+}

package/readme.md

@@ -0,0 +1,273 @@
+# koishi-plugin-ai-video
+
+## 项目介绍 (Project Introduction)
+
+### 中文
+一款为 Koishi 聊天机器人框架开发的 AI 视频生成插件，支持**文生视频 + 图生视频**，**兼容 OpenAI 标准接口的同时支持自定义 API 端点**，可接入任意视频生成服务。  
+内置多 API 负载均衡、调试日志、超时机制、异步轮询、全配置化提示文案（含自定义提示模板），配置灵活、开箱即用、稳定可靠。  
+图生视频支持附带参考图片，自动切换模式。  
+提供**黑名单管理**功能，数据持久化到数据库，管理员可通过指令添加、移除用户及查看黑名单。  
+
+### English
+An AI video generation plugin for the Koishi chatbot framework, supporting **text-to-video & image-to-video**.  
+Compatible with OpenAI‑standard APIs, and also supports **custom API endpoints** for any video generation service.  
+Built‑in multi‑API load balancing, debug logging, timeout mechanism, async polling, fully configurable messages and prompt templates.  
+Image‑to‑video works by attaching a reference image, automatic mode switching.  
+**Blacklist management** with database persistence.  
+
+## 使用说明 (Usage)
+
+### 中文
+
+| 命令 (Command)                     | 功能说明 (Description) |
+|------------------------------------|------------------------|
+| `video <提示词>`                  | **AI 视频生成**：根据提示词生成视频；若消息中同时附带了图片，则自动切换为图生视频模式。 |
+| `redraw` / `rd` / `重绘`         | 重绘：重新生成上一次的文生视频结果 |
+| `blacklist list`                 | 查看当前黑名单（仅管理员） |
+| `blacklist add <QQ号> [QQ号 ...]`  | 将指定 QQ 号加入黑名单（仅管理员） |
+| `blacklist remove <QQ号> [QQ号 ...]` | 将指定 QQ 号移出黑名单（仅管理员） |
+
+### English
+
+| Command                             | Description |
+|-------------------------------------|-------------|
+| `video <prompt>`                   | **AI Video Generation**: Generate video from prompt. If an image is attached, automatically switches to image-to-video mode. |
+| `redraw` / `rd` / `重绘`         | Redraw: Re-generate the last text-to-video result |
+| `blacklist list`                  | Show current blacklist (admin only) |
+| `blacklist add <QQ_number> [QQ_number ...]` | Add QQ number(s) to blacklist (admin only) |
+| `blacklist remove <QQ_number> [QQ_number ...]` | Remove QQ number(s) from blacklist (admin only) |
+
+## 配置说明 (Configuration)
+
+### 中文
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| **基本设置** | | |
+| `debug` | 调试模式，输出完整请求/响应日志 | `false` |
+| `timeout` | API 请求超时时间（毫秒），视频生成较慢建议加大 | `600000` |
+| `rateLimit` | 每小时调用次数上限 | `50` |
+| `maxVideos` | 单次生成最多视频数量 | `1` |
+| `videoDuration` | 默认视频时长（秒） | `5` |
+| `videoResolution` | 默认视频分辨率（宽x高） | `1024x576` |
+| `enableForward` | 多视频结果是否使用合并转发 | `true` |
+| `enableTxt2Video` | 启用文生视频功能 | `true` |
+| `enableImg2Video` | 启用图生视频功能 | `true` |
+| `videoSendMode` | 视频发送方式：`video`（仅视频文件）、`url`（仅链接）、`both`（视频文件+链接） | `video` |
+| `pollEnabled` | 是否启用异步轮询（若 API 返回任务 ID 则自动轮询至完成） | `false` |
+| `pollInterval` | 轮询间隔（毫秒） | `3000` |
+| `pollTimeout` | 轮询总超时时间（毫秒） | `600000` |
+| **代理设置** | | |
+| `proxyEnabled` | 是否启用 HTTP/HTTPS 代理 | `false` |
+| `proxyProtocol` | 代理协议：`http` / `https` | `http` |
+| `proxyHost` | 代理地址 | (空) |
+| `proxyPort` | 代理端口 | `8080` |
+| `proxyAuth` | 代理是否需要认证 | `false` |
+| `proxyUsername` | 代理用户名 | (空) |
+| `proxyPassword` | 代理密码 | (空) |
+| **内置 API 设置** | 简单模式，使用 OpenAI 格式 | |
+| `useCustomApi` | 是否启用自定义 API（开启后下方自定义列表生效） | `false` |
+| `apiEndpoint` | API 端点地址 | `https://api.openai.com/v1/video/generations` |
+| `apiKey` | API 密钥 | (空) |
+| `model` | 模型名称 | `video-generation-model` |
+| `img2videoModel` | 图生视频专用模型（留空使用上方模型） | (空) |
+| `videoDuration` | 视频时长（秒，留空使用全局默认） | `0` |
+| `videoResolution` | 视频分辨率（留空使用全局默认） | (空) |
+| `txt2videoPrompt` | 文生视频提示词模板（留空直接使用用户输入） | (空) |
+| `img2videoPrompt` | 图生视频提示词模板（留空直接使用用户输入） | (空) |
+| `customHeaders` | 自定义请求头 JSON（合并到默认请求头） | `{}` |
+| **自定义 API 配置** | 高级模式，每个条目独立配置 | `[]` |
+| `apiStrategy` | API 调度策略：`sequence` / `roundrobin` | `roundrobin` |
+| `customApiList[].enable` | 是否启用此 API | `true` |
+| `customApiList[].endpoint` | API 端点地址 | `https://api.openai.com/v1/video/generations` |
+| `customApiList[].apiKey` | API 密钥 | (空) |
+| `customApiList[].model` | 模型名称 | `video-generation-model` |
+| `customApiList[].img2videoModel` | 图生视频专用模型（留空使用上方模型） | (空) |
+| `customApiList[].videoDuration` | 视频时长（秒，留空使用全局默认） | `0` |
+| `customApiList[].videoResolution` | 视频分辨率（留空使用全局默认） | (空) |
+| `customApiList[].txt2videoPrompt` | 文生视频提示词模板 | (空) |
+| `customApiList[].img2videoPrompt` | 图生视频提示词模板 | (空) |
+| `customApiList[].customHeaders` | 自定义请求头 JSON，支持 `{apiKey}` 变量 | 见预设 |
+| `customApiList[].bodyTemplate` | 自定义请求体 JSON（高级，留空使用内置） | 见预设 |
+| **权限管理** | | |
+| `blacklistAdmins` | 黑名单管理员 QQ 号列表 | `[]` |
+| **消息文本** | 所有提示文案均可自定义，支持模板变量 | 见配置页 |
+
+> 指令名称（`video`、`redraw`、`blacklist`）为固定注册名，可在 Koishi 的指令管理页面中单独配置别名。
+
+#### 请求范式 JSON (`bodyTemplate` 字段)
+
+`bodyTemplate` 是高级选项，用于完全自定义请求体。留空时插件使用内置模板。
+
+| 字段 | 说明 | 默认值 |
+|------|------|--------|
+| `txt2videoBody` | 文生视频请求体 JSON 模板，支持变量 `{model}` `{prompt}` `{duration}` `{size}` | 内置 |
+| `img2videoBody` | 图生视频请求体 JSON 模板，支持变量 `{model}` `{prompt}` `{duration}` `{size}` `{url}` | 内置 |
+| `responseVideoPath` | 响应 JSON 中视频 URL 的字段路径，如 `video_url` | `video_url` |
+| `pollUrlTemplate` | 轮询地址模板，如 `{endpoint}/{task_id}` | 无 |
+| `taskIdPath` | 返回的任务 ID 字段路径，如 `task_id` | 无 |
+| `method` | HTTP 方法 | `POST` |
+
+**变量说明**  
+- `{model}`：模型名称（取自配置中的全局模型或专用模型）  
+- `{prompt}`：用户输入的提示词（经过提示模板处理后的最终文本）  
+- `{duration}`：视频时长（秒）  
+- `{size}`：视频分辨率（宽x高）  
+- `{url}`：图生视频时参考图片的链接（字符串）  
+- `{apiKey}`：API 密钥，仅用于 `headers` 字段  
+
+**异步轮询说明**  
+当 `pollEnabled` 开启且 API 返回任务 ID 时，插件会根据 `pollUrlTemplate` 和 `taskIdPath` 自动轮询任务状态，直到完成或超时。  
+
+**视频 URL 自动扫描**  
+当 `responseVideoPath` 未命中时，插件会自动扫描响应 JSON 中**第一个包含视频扩展名（.mp4/.mov/.avi/.webm/.mkv）的 HTTP/HTTPS URL** 作为视频地址。  
+
+---
+
+### English
+
+| Config Item | Description | Default |
+|-------------|-------------|---------|
+| **Basic** | | |
+| `debug` | Debug mode, logs full request/response | `false` |
+| `timeout` | Request timeout (ms), video generation usually slower | `600000` |
+| `rateLimit` | Hourly call limit | `50` |
+| `maxVideos` | Max number of videos per generation | `1` |
+| `videoDuration` | Default video duration (seconds) | `5` |
+| `videoResolution` | Default video resolution (WxH) | `1024x576` |
+| `enableForward` | Use forward message for multiple videos | `true` |
+| `enableTxt2Video` | Enable text-to-video | `true` |
+| `enableImg2Video` | Enable image-to-video | `true` |
+| `videoSendMode` | Video send mode: `video`, `url`, `both` | `video` |
+| `pollEnabled` | Enable async polling (polls until completion if task ID returned) | `false` |
+| `pollInterval` | Polling interval (ms) | `3000` |
+| `pollTimeout` | Polling total timeout (ms) | `600000` |
+| **Proxy** | | |
+| `proxyEnabled` | Enable HTTP/HTTPS proxy | `false` |
+| `proxyProtocol` | Proxy protocol: `http` / `https` | `http` |
+| `proxyHost` | Proxy host | (empty) |
+| `proxyPort` | Proxy port | `8080` |
+| `proxyAuth` | Proxy requires authentication | `false` |
+| `proxyUsername` | Proxy username | (empty) |
+| `proxyPassword` | Proxy password | (empty) |
+| **Built-in API** | Simple mode, uses OpenAI format | |
+| `useCustomApi` | Enable custom API (below list takes effect) | `false` |
+| `apiEndpoint` | API endpoint URL | `https://api.openai.com/v1/video/generations` |
+| `apiKey` | API key | (empty) |
+| `model` | Model name | `video-generation-model` |
+| `img2videoModel` | Image-to-video model (falls back to model) | (empty) |
+| `videoDuration` | Video duration (seconds, 0 = use global) | `0` |
+| `videoResolution` | Video resolution (empty = use global) | (empty) |
+| `txt2videoPrompt` | Prompt template (empty = raw user input) | (empty) |
+| `img2videoPrompt` | Prompt template (empty = raw user input) | (empty) |
+| `customHeaders` | Custom headers JSON (merged into default) | `{}` |
+| **Custom API Config** | Advanced mode, per-entry configuration | `[]` |
+| `apiStrategy` | API strategy: `sequence` / `roundrobin` | `roundrobin` |
+| `customApiList[].enable` | Enable this API | `true` |
+| `customApiList[].endpoint` | API endpoint URL | `https://api.openai.com/v1/video/generations` |
+| `customApiList[].apiKey` | API key | (empty) |
+| `customApiList[].model` | Model name | `video-generation-model` |
+| `customApiList[].img2videoModel` | Image-to-video model (falls back to model) | (empty) |
+| `customApiList[].videoDuration` | Video duration (seconds, 0 = use global) | `0` |
+| `customApiList[].videoResolution` | Video resolution (empty = use global) | (empty) |
+| `customApiList[].txt2videoPrompt` | Prompt template | (empty) |
+| `customApiList[].img2videoPrompt` | Prompt template | (empty) |
+| `customApiList[].customHeaders` | Custom headers JSON, supports `{apiKey}` | preset |
+| `customApiList[].bodyTemplate` | Custom request body JSON (advanced) | preset |
+| **Permissions** | | |
+| `blacklistAdmins` | Admin QQ number list | `[]` |
+| **Messages** | All messages customizable with template vars | see schema |
+
+> Command names (`video`, `redraw`, `blacklist`) are fixed; aliases can be configured via Koishi's command management page.
+
+#### Request Template JSON (`bodyTemplate` field)
+
+`bodyTemplate` is the advanced option for full custom request bodies. Leave empty to use built-in templates.
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `txt2videoBody` | Txt2video request body template, vars `{model}` `{prompt}` `{duration}` `{size}` | built-in |
+| `img2videoBody` | Img2video request body template, vars `{model}` `{prompt}` `{duration}` `{size}` `{url}` | built-in |
+| `responseVideoPath` | JSON path to video URL, e.g. `video_url` | `video_url` |
+| `pollUrlTemplate` | Polling URL template, e.g. `{endpoint}/{task_id}` | none |
+| `taskIdPath` | JSON path to task ID, e.g. `task_id` | none |
+| `method` | HTTP method | `POST` |
+
+**Variable placeholders**  
+- `{model}` — Model name  
+- `{prompt}` — Processed user prompt after template expansion  
+- `{duration}` — Video duration in seconds  
+- `{size}` — Video resolution (WxH)  
+- `{url}` — Reference image URL for image-to-video  
+- `{apiKey}` — API key, used only in `headers`
+
+**Async Polling**  
+When `pollEnabled` is on and the API returns a task ID, the plugin will automatically poll using `pollUrlTemplate` and `taskIdPath` until completion or timeout.  
+
+**Auto Video URL Scanning**  
+When `responseVideoPath` fails, the plugin scans the response JSON for the **first HTTP/HTTPS URL with a video extension (.mp4/.mov/.avi/.webm/.mkv)** as the video address.  
+
+---
+
+## 自定义 API 端点示例 (Custom Endpoint Examples)
+
+### 基础视频生成 API（同步返回）
+```json
+{
+  "endpoint": "https://api.example.com/v1/video/generations",
+  "apiKey": "sk-xxxx",
+  "headers": {"Authorization":"Bearer {apiKey}","Content-Type":"application/json"},
+  "txt2videoBody": "{\"model\":\"{model}\",\"prompt\":\"{prompt}\",\"duration\":{duration},\"size\":\"{size}\"}",
+  "img2videoBody": "{\"model\":\"{model}\",\"prompt\":\"{prompt}\",\"duration\":{duration},\"size\":\"{size}\",\"image_url\":\"{url}\"}",
+  "responseVideoPath": "video_url"
+}
+```
+
+### 异步轮询 API（返回任务 ID）
+```json
+{
+  "endpoint": "https://api.example.com/v1/video/tasks",
+  "apiKey": "sk-xxxx",
+  "headers": {"Authorization":"Bearer {apiKey}","Content-Type":"application/json"},
+  "txt2videoBody": "{\"model\":\"{model}\",\"prompt\":\"{prompt}\",\"duration\":{duration},\"size\":\"{size}\"}",
+  "img2videoBody": "{\"model\":\"{model}\",\"prompt\":\"{prompt}\",\"duration\":{duration},\"size\":\"{size}\",\"image_url\":\"{url}\"}",
+  "responseVideoPath": "result.video_url",
+  "pollUrlTemplate": "{endpoint}/{task_id}",
+  "taskIdPath": "task_id"
+}
+```
+
+## 依赖 (Dependencies)
+- **数据库 (database)**：必须启用，用于黑名单持久化。
+- **图生视频 (img2video)**：需要 `assets` 服务及正确的 `selfUrl` 配置。
+
+## 功能特性 (Features)
+- 文生视频 / 图生视频（自动识别消息中是否附带图片）
+- 多 API 轮询与负载均衡（sequence / roundrobin）
+- 支持同步返回与异步轮询两种模式，适配不同视频生成服务
+- 灵活的请求体模板系统，变量自动替换，一套配置兼容任意平台
+- 视频结果支持文件发送和链接发送
+- 黑名单管理（持久化到数据库）
+- 全配置化提示文案，支持模板变量
+- 调试日志、超时控制、频率限制
+
+## 项目贡献者 (Contributors)
+| 贡献者 (Contributor) | 贡献内容 (Contribution) |
+| --- | --- |
+| Minecraft-1314 | 插件完整开发（从绘图插件改造） |
+| （欢迎提交 PR / Issues 加入贡献者列表） |
+
+## 许可协议 (License)
+本项目采用 MIT 许可证，详情参见 LICENSE 文件。
+
+This project is licensed under the MIT License, see the LICENSE file for details.
+
+## 支持我们 (Support Us)
+如果这个项目对您有帮助，欢迎点亮右上角的 Star 支持我们，这将是对所有贡献者最大的鼓励！
+
+If this project is helpful to you, please feel free to star it in the upper right corner to support us, which will be the greatest encouragement to all contributors!
+
+## 问题反馈 (Feedback)
+如有问题或建议，可通过 Issues 提交反馈。
+
+If you have any questions or suggestions, please submit feedback via Issues.