aiconductor-cli 1.3.3 → 1.3.5

package/api_docs/md_to_xhs.md

@@ -0,0 +1,87 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/md_to_xhs`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将 Markdown 文本转换为精美图片，支持 10 种主题风格和多种宽高比，自动分页渲染，按生成图片数量计费。
+
+### 主题列表
+
+| theme 值 | 风格说明 | 别名 |
+|----------|---------|------|
+| `xhs` | 小红书风格（默认） | - |
+| `minimal` | 极简主义 | - |
+| `magazine` | 文艺杂志 | - |
+| `techdark` | 科技暗黑 | - |
+| `wood` | 温暖木质 | - |
+| `mint` | 清新薄荷 | - |
+| `notepad` | 记事本风格 | - |
+| `bwminimal` | 黑白极简 | `blackwhite` / `bw` / `black-white` / `黑白极简` |
+| `memo` | 备忘录风格（带顶部导航栏） | - |
+| `iphone-memo` | iPhone 备忘录风格（加粗文字黄色高亮） | - |
+
+### 宽高比预设
+
+| aspectRatio | 输出尺寸 | 适用场景 |
+|-------------|---------|---------|
+| `3:4` | 1080 × 1440 | 小红书竖图（默认） |
+| `9:16` | 1080 × 1920 | 手机全屏封面 / 短视频封面 |
+| `1:1` | 1080 × 1080 | Instagram / 小红书方图 |
+| `16:9` | 1920 × 1080 | 横屏封面 / PPT 风格 |
+| `4:3` | 1440 × 1080 | 传统横屏 |
+| `2:3` | 1080 × 1620 | 海报竖图 |
+| `3:2` | 1620 × 1080 | 海报横图 |
+
+> 不在预设中的比例（如 `"5:7"`、`"21:9"`）也能自动解析，宽度固定 1080，高度按比例计算。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| md_text | string | 是 | - | Markdown 文本内容，最长 5000 字符 |
+| theme | string | 否 | `"xhs"` | 主题名称，见上方主题列表 |
+| aspectRatio | string | 否 | `"3:4"` | 宽高比，见上方预设列表，也支持任意 `"w:h"` 格式 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| theme | string | 实际使用的主题名 |
+| aspectRatio | string | 实际使用的宽高比 |
+| width | integer | 输出图片宽度（px） |
+| height | integer | 输出图片高度（px） |
+| count | integer | 生成图片数量 |
+| images | array\<string\> | 图片 URL 列表 |
+| billing | object | 计费信息 |
+| billing.service_fee | float | 服务费（单价 × 数量） |
+| billing.discount_applied | boolean | 是否应用折扣 |
+| billing.balance_before | float | 扣费前余额 |
+| billing.balance_after | float | 扣费后余额 |
+| billing.currency | string | 货币类型（CNY） |
+| billing.transaction_id | string | 交易ID |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/md_to_xhs" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "md_text": "# 标题\n\n正文内容\n\n- 列表项1\n- 列表项2",
+    "theme": "xhs",
+    "aspectRatio": "9:16"
+  }'
+```
+
+## 注意事项
+1. Markdown 文本最长 5000 字符，超出会返回错误
+2. 图片自动分页，内容超长会生成多张图片，按实际生成数量计费
+3. 图片存储在 OSS 的 `temporary_90` 目录，90 天后自动删除
+4. 主题别名（如 `bw` → `bwminimal`）仅影响输入解析，响应中 `theme` 字段始终返回标准化名称
+5. 不在预设中的宽高比（如 `"5:7"`）也能自动解析

package/api_docs/md_to_xlsx.md

@@ -0,0 +1,52 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/md_to_xlsx`
+- **方法**: `POST`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将 Markdown 文本中的表格转换为 XLSX 格式文档，支持多工作表和自动列宽调整。按次计费，费用以 api_services 表配置为准。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| md_text | string | 是 | - | Markdown 文本内容（需包含表格，否则转换失败） |
+| filename | string | 否 | "document" | 输出文件名（不含后缀），系统会自动追加时间戳与 UUID 后缀 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| filename | string | 生成的 XLSX 文件名（失败时为 null） |
+| file_url | string | 生成的文件下载 URL（失败或 OSS 上传失败时为空） |
+| message | string | 响应消息 |
+| billing | object | 计费信息（见下方子字段） |
+| billing.service_fee | float | 本次服务费用 |
+| billing.discount_applied | boolean | 是否应用折扣 |
+| billing.balance_before | float | 扣费前账户余额 |
+| billing.balance_after | float | 扣费后账户余额 |
+| billing.currency | string | 货币单位（CNY） |
+| billing.transaction_id | string | 交易流水号（未扣费时为 null） |
+| billing.error | string | 错误信息（仅失败响应的 billing 中可能出现） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/md_to_xlsx" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "md_text": "| 名称 | 价格 |\n|------|------|\n| 苹果 | 5 |\n| 香蕉 | 3 |",
+    "filename": "水果价格表"
+  }'
+```
+
+## 注意事项
+1. 输入的 Markdown 必须至少包含一个表格，否则返回 `success=false` 且提示「未发现 Markdown 格式表格」，此情况不扣费。
+2. Markdown 文本为空时返回失败且不扣费；API 密钥无效、账户禁用或余额不足时均不扣费。
+3. OSS 上传失败时仍返回 `success=true`，但 `file_url` 为空字符串，且不会扣费（计费信息保持初始值）。
+4. 工作表名称取对应标题（h1~h5），长度超过 31 字符会被截断以符合 Excel 规范。

package/api_docs/portrait_enhancement.md

@@ -0,0 +1,69 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/portrait_enhancement`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+整合人脸美颜、智能瘦脸、智能美肤的人像智能优化服务。按成功处理的优化功能计费，每个成功功能固定 0.05 元（代码内硬编码 `service_fee_per_item=0.05`，与 api_services 表无关）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| image_url | string | 是 | - | 待处理图片 URL（不能包含中文字符） |
+| enable_beauty | boolean | 是 | - | 是否启用人脸美颜 |
+| enable_slimming | boolean | 是 | - | 是否启用智能瘦脸 |
+| enable_skin_retouch | boolean | 是 | - | 是否启用智能美肤 |
+| beauty_sharp | float | 否 | `0.1` | 美颜锐化程度 |
+| beauty_smooth | float | 否 | `0.3` | 美颜平滑程度 |
+| beauty_white | float | 否 | `0.8` | 美颜美白程度 |
+| slimming_degree | float | 否 | `1.0` | 瘦脸力度 |
+| skin_retouch_degree | float | 否 | `1.0` | 磨皮力度 |
+| skin_whitening_degree | float | 否 | `1.0` | 美白力度 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| final_image_url | string | 处理后图片 URL（转存至 OSS temporary_7 目录，7天保留），失败为空 |
+| processing_steps | array | 各处理步骤详情列表 |
+| processing_steps[].step | string | 步骤名：`skin_retouch`/`beauty`/`slimming` |
+| processing_steps[].success | boolean | 该步骤是否成功 |
+| processing_steps[].parameters | object | 该步骤实际使用的参数（成功时返回） |
+| processing_steps[].error | string | 失败原因（失败时返回） |
+| billing | object | 计费信息 |
+| billing.service_fee | float | 本次总费用（0.05 × 成功功能数） |
+| billing.discount_applied | boolean | 是否应用折扣（成功分支恒为 true） |
+| billing.balance_before | float | 扣费前余额 |
+| billing.balance_after | float | 扣费后余额 |
+| billing.currency | string | 货币单位，固定 `CNY` |
+| billing.transaction_id | int/null | 首笔交易 ID |
+| billing.transaction_ids | array | 所有成功功能对应的交易 ID 列表（成功时返回） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/portrait_enhancement" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "image_url": "https://example.com/portrait.jpg",
+    "enable_beauty": true,
+    "enable_slimming": true,
+    "enable_skin_retouch": true,
+    "beauty_white": 0.8,
+    "slimming_degree": 1.0
+  }'
+```
+
+## 注意事项
+1. `enable_beauty`、`enable_slimming`、`enable_skin_retouch` 三个开关至少开启一个，全部关闭返回 `success=false`。
+2. `image_url` 不能包含中文字符；图片需满足分辨率/体积限制（仅美颜时最大 2000px/3MB，组合时最大 5000px/6MB），插件会自动压缩。
+3. 采用后扣费模式：仅当至少一个优化功能成功、且成品图成功转存至 OSS 后才扣费；余额不足、转存失败或处理失败均不扣费（billing.service_fee=0）。
+4. 校验失败、图片下载/上传失败、OSS 初始化失败等异常均返回 `success=false` 且不扣费。
+5. `billing.discount_applied` 在成功分支一律为 `true`（代码逻辑如此，与真实折扣无关）。

package/api_docs/published_webpages.md

@@ -0,0 +1,45 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/published_webpages`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+分页查询当前用户已发布的网页列表，免费。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| page | integer | 否 | 1 | 页码，必须为大于等于 1 的整数 |
+| page_size | integer | 否 | 20 | 每页返回条数，范围 1~100 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| webpages | array | 当前页的已发布网页列表 |
+| webpages[].id | integer | 网页记录 ID，可用于删除接口 |
+| webpages[].source | string | 发布来源，如 `html_publish` 或 `md_to_html` |
+| webpages[].title | string | 网页标题或文件名 |
+| webpages[].online_url | string | 网页的公开访问链接 |
+| webpages[].created_at | string | 发布时间（ISO 8601 格式） |
+| total | integer | 当前用户的已发布网页总数 |
+| page | integer | 当前页码 |
+| page_size | integer | 当前每页条数 |
+
+## 请求示例
+
+```bash
+curl "http://plugin.aiconductor.fun/api/published_webpages?page=1&page_size=20" \
+  -H "Authorization: Bearer your_api_key"
+```
+
+## 注意事项
+1. 只会返回当前 API 密钥所属用户的发布记录。
+2. 结果按发布时间倒序排列，同一时间的记录按 ID 倒序排列。
+3. page 或 page_size 不符合范围时，接口会返回参数错误且不执行查询。

package/api_docs/r2_uploader.md

@@ -0,0 +1,51 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/r2_uploader`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`（`file_url` / `file_base64`）或 `multipart/form-data`（`file`）
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将本地文件、远程文件或 Base64 内容上传至 Cloudflare R2 并返回公开链接；需 API 密钥鉴权，不计费，可选择 1 天或 7 天有效期。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| file | file | 条件必填 | - | `multipart/form-data` 本地文件。与 `file_url`、`file_base64` 三选一。 |
+| file_url | string | 条件必填 | - | 待转存的 HTTP/HTTPS 文件链接。与 `file`、`file_base64` 三选一。 |
+| file_base64 | string | 条件必填 | - | 文件 Base64 内容，支持 `data:image/png;base64,...` 格式。与 `file`、`file_url` 三选一。 |
+| filename | string | 否 | 源文件名 | 自定义保存文件名。 |
+| valid_days | integer | 否 | 1 | 文件有效期，仅支持 `1` 或 `7`。`1` 写入 `temporary_1/`，`7` 写入 `temporary_7/`。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| file_url | string | R2 公开文件链接，失败时为空字符串 |
+| filename | string | 实际保存的文件名，失败时为空字符串 |
+| content_type | string | 文件 MIME 类型，失败时为空字符串 |
+| size | integer | 文件大小，单位为字节，失败时为 `0` |
+| valid_days | integer | 实际有效期，成功时为 `1` 或 `7`，失败时为 `0` |
+| expires_at | string | 预计过期时间，ISO 8601 UTC 格式，失败时为空字符串 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/r2_uploader" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "file_url": "https://example.com/image.png",
+    "filename": "image.png",
+    "valid_days": 7
+  }'
+```
+
+## 注意事项
+1. 必须提供有效且已启用的 API 密钥；接口不计费，也不会生成交易记录。
+2. `file`、`file_url`、`file_base64` 必须且只能提供一个；文件最大为 100MB。
+3. 仅支持 HTTP/HTTPS 的 `file_url`，`valid_days` 仅支持 `1` 或 `7`。

package/api_docs/schedulerx_job_create.md

@@ -0,0 +1,56 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/schedulerx_job_create`
+- **方法**: `POST`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（仅做 API 密钥验证，不扣费）
+
+## 功能说明
+阿里云 SchedulerX 任务创建接口，支持创建一次性任务和周期性（Cron）任务。需要 API 密钥验证但**不扣费**。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| region_id | string | 是 | - | 阿里云地域 ID（如 cn-hangzhou） |
+| access_key_id | string | 是 | - | 阿里云 AccessKeyId |
+| access_key_secret | string | 是 | - | 阿里云 AccessKeySecret |
+| namespace | string | 是 | - | SchedulerX 命名空间 ID |
+| group_id | string | 是 | - | SchedulerX 应用分组 ID |
+| job_name | string | 是 | - | 任务名称（需唯一） |
+| http_url | string | 是 | - | 目标触发 URL |
+| description | string | 否 | 空字符串 | 任务描述 |
+| http_method | string | 否 | GET | 请求方法（GET / POST 等） |
+| timeout | int | 否 | 10 | 超时时间（秒） |
+| max_attempt | int | 否 | 2 | 失败重试次数 |
+| one_time_expression | string | 否 | 空字符串 | 一次性任务执行时间（与 cron_expression 二选一必填） |
+| cron_expression | string | 否 | 空字符串 | 周期任务 Cron 表达式（与 one_time_expression 二选一必填） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 操作是否成功 |
+| message | string | 返回消息 |
+| job_id | int | 任务 ID（成功时返回，失败为 0） |
+| request_id | string | 请求 ID（成功时返回） |
+| mode | string | 任务模式（onetime / cron） |
+| expression | string | 执行表达式（一次性时间或 Cron 表达式） |
+| error | string | 错误信息（失败时，成功为空字符串） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/schedulerx_job_create" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"region_id": "cn-hangzhou", "access_key_id": "your_ak", "access_key_secret": "your_sk", "namespace": "ns-xxx", "group_id": "grp-xxx", "job_name": "my_job", "http_url": "https://example.com/hook", "cron_expression": "0 0 * * *"}'
+```
+
+## 注意事项
+1. 仅校验 API 密钥有效性，本接口**不扣费**。
+2. one_time_expression 与 cron_expression 必须且只能提供其中一个；都不提供或都提供均返回失败。
+3. 任务模式由表达式自动判定：提供 one_time_expression 为 onetime，提供 cron_expression 为 cron。
+4. 上游 SchedulerX 创建接口请求超时 30 秒，超时返回"请求SchedulerX API超时"。
+5. access_key_id / access_key_secret 为调用方自己的阿里云凭证，平台不托管。

package/api_docs/transaction_query.md

@@ -0,0 +1,52 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/users/transaction_query`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据 API 密钥查询当前账户的消费/充值记录，支持类型、时间范围筛选、排序与分页（每页 20 条）。本插件仅校验密钥、不计费（无 billing）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| page | int | 否 | 1 | 页码（从 1 开始） |
+| type | string | 否 | "" | 交易类型筛选：`consume`（消费）/ `recharge`（充值），为空则不筛选 |
+| start_date | string | 否 | "" | 起始日期，格式 `YYYY-MM-DD` |
+| end_date | string | 否 | "" | 结束日期，格式 `YYYY-MM-DD` |
+| order | string | 否 | "desc" | 排序方向：`asc`（升序）/ `desc`（降序） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| data | array[object] | 交易记录列表（见下） |
+| pagination | object | 分页信息（见下） |
+| summary | object | 金额汇总（见下） |
+
+`data[]` 字段：`id`(int)、`service_code`(string)、`amount`(float)、`balance_after`(float)、`type`(string, consume/recharge)、`notes`(string)、`created_at`(string, `YYYY-MM-DD HH:MM:SS`)。
+
+`pagination` 字段：`page`(int)、`page_size`(int, 固定 20)、`total`(int)、`total_pages`(int)。
+
+`summary` 字段：`total_consume`(float, 消费总额)、`total_recharge`(float, 充值总额)。
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/users/transaction_query" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"page": 1, "type": "consume", "start_date": "2026-07-01", "end_date": "2026-07-29", "order": "desc"}'
+```
+
+## 注意事项
+1. 本插件仅校验 api_key 并查询其对应账户记录，不扣费（无 billing 字段）。
+2. 参数校验：`page < 1`、`type` 非 consume/recharge、`order` 非 asc/desc 均返回失败。
+3. 筛选 `start_date`/`end_date` 自动补全为当日 `00:00:00` ~ `23:59:59`。
+4. `summary` 汇总金额针对全部匹配记录（不限当前页）；`page` 超出 `total_pages` 时返回失败。
+5. 失败情况（密钥无效、账户禁用、参数错误、服务异常）均返回空 data 与零值分页/汇总。

package/api_docs/url_to_markdown.md

@@ -0,0 +1,50 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/url_to_markdown`
+- **方法**: `POST`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将网页 URL 转换为干净的 Markdown 格式文本（使用 defuddle-proxy 服务）。按次计费，费用以 api_services 表配置为准。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| url | string | 是 | - | 要转换的网页 URL（必须以 http:// 或 https:// 开头） |
+| timeout | int | 否 | 30 | 请求超时时间（秒） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| markdown | string | 转换后的 Markdown 内容（失败时为 ""） |
+| billing | object | 计费信息（见下方子字段） |
+| billing.service_fee | float | 本次服务费用 |
+| billing.discount_applied | boolean | 是否应用折扣 |
+| billing.balance_before | float | 扣费前账户余额 |
+| billing.balance_after | float | 扣费后账户余额 |
+| billing.currency | string | 货币单位（CNY） |
+| billing.transaction_id | string | 交易流水号（未扣费时为 null） |
+| billing.error | string | 错误信息（仅失败响应的 billing 中可能出现） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/url_to_markdown" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://example.com/article",
+    "timeout": 30
+  }'
+```
+
+## 注意事项
+1. 采用后扣费模式：仅当成功取得非空 Markdown 内容后才记录交易并扣费；下游返回 400/500、内容为空或请求超时时返回失败且不扣费。
+2. URL 格式无效（非 http/https 开头）、余额不足、API 密钥无效、账户禁用时不扣费。
+3. 请求下游服务的超时时间由 `timeout` 参数控制（连接阶段固定 10 秒）。

package/api_docs/video_download_url.md

@@ -0,0 +1,57 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/video_download_url`
+- **方法**: `POST`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+解析视频链接并获取无水印下载地址，支持抖音、快手等多个平台，提供视频信息与下载链接，包含 API 密钥验证与按次计费，费用以 api_services 表配置为准。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| video_url | string | 是 | - | 视频链接 URL（支持从分享文本中提取链接，保留 URL 参数） |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息（成功/失败原因） |
+| source | string | 视频来源平台（如 douyin） |
+| author | string | 视频作者 |
+| title | string | 视频标题 |
+| thumbnail | string | 视频缩略图 URL |
+| duration | number | 视频时长（毫秒） |
+| medias | array | 媒体文件列表 |
+| medias[].url | string | 媒体文件下载地址 |
+| medias[].type | string | 媒体类型（video / audio） |
+| medias[].quality | string | 质量标识（如 No Watermark / Audio） |
+| medias[].extension | string | 文件扩展名（如 mp4 / mp3） |
+| medias[].data_size | number | 文件大小（备用方案无法获取时为 0） |
+| medias[].duration | number | 音频时长（秒，仅音频类型返回） |
+| billing | object | 计费信息 |
+| billing.service_fee | number | 本次服务费用 |
+| billing.discount_applied | boolean | 是否应用折扣/计费 |
+| billing.balance_before | number | 扣费前余额 |
+| billing.balance_after | number | 扣费后余额 |
+| billing.currency | string | 货币单位（CNY） |
+| billing.transaction_id | string | 交易流水号（失败为 null） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/video_download_url" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"video_url": "https://v.douyin.com/xxxx/"}'
+```
+
+## 注意事项
+1. 采用后扣费模式：解析失败（主方案失败且抖音备用方案也失败、非抖音域名）均不扣费（service_fee 为 0）。
+2. 抖音域名主方案失败时自动尝试抖音备用解析方案（parse_douyin_video），备用方案成功同样计费并返回无水印视频与音频。
+3. 按次计费：解析成功即扣费，与返回媒体数量无关。
+4. medias 中音频类型会额外返回 duration 字段；备用方案返回的媒体 data_size 为 0。

package/api_docs/video_download_url_oss.md

@@ -0,0 +1,55 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/video_download_url_oss`
+- **方法**: `POST`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+解析视频链接获取无水印下载地址，将无水印视频文件下载并上传至用户指定的阿里云 OSS，返回单个 OSS 链接。仅保留 quality=no_watermark 的视频，支持抖音、快手等多平台，包含 API 密钥验证与按次计费，费用以 api_services 表配置为准。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| video_url | string | 是 | - | 视频链接 URL（支持从分享文本中提取链接，保留 URL 参数） |
+| OSS_ACCESS_KEY_ID | string | 是 | - | 用户阿里云 OSS 的 AccessKeyId |
+| OSS_ACCESS_KEY_SECRET | string | 是 | - | 用户阿里云 OSS 的 AccessKeySecret |
+| OSS_ENDPOINT | string | 是 | - | 用户阿里云 OSS 的 Endpoint（如 oss-cn-hangzhou.aliyuncs.com） |
+| OSS_BUCKET_NAME | string | 是 | - | 用户阿里云 OSS 的 Bucket 名称 |
+| oss_directory | string | 否 | temporary | OSS 中的存储目录 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| source | string | 视频来源平台（如 douyin） |
+| author | string | 视频作者 |
+| title | string | 视频标题 |
+| video_url_oss | string | 上传至 OSS 后的无水印视频链接 |
+| billing | object | 计费信息 |
+| billing.service_fee | number | 本次服务费用 |
+| billing.discount_applied | boolean | 是否应用折扣/计费 |
+| billing.balance_before | number | 扣费前余额 |
+| billing.balance_after | number | 扣费后余额 |
+| billing.currency | string | 货币单位（CNY） |
+| billing.transaction_id | string | 交易流水号（失败为 null） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/video_download_url_oss" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"video_url": "https://v.douyin.com/xxxx/", "OSS_ACCESS_KEY_ID": "your_ak", "OSS_ACCESS_KEY_SECRET": "your_sk", "OSS_ENDPOINT": "oss-cn-hangzhou.aliyuncs.com", "OSS_BUCKET_NAME": "my-bucket", "oss_directory": "temporary"}'
+```
+
+## 注意事项
+1. 仅保留 type=video 且 quality=no_watermark 的媒资，未找到则失败且不扣费。
+2. 采用后扣费模式：解析失败、OSS 配置错误、上传失败均不扣费（service_fee 为 0）。
+3. OSS 凭证由调用方自行提供，平台仅做上传不托管密钥；OSS 配置错误会返回明确错误。
+4. 下载并上传至 OSS 的超时时间为 300 秒；上传失败（如下载异常、OSS 写入失败）返回失败且不扣费。
+5. 按次计费：上传成功即扣费。

package/api_docs/video_to_text.md

@@ -0,0 +1,48 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/video_to_text`
+- **方法**: `POST`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将视频文件 URL 转换为文字，使用 DashScope API 进行语音识别转写，包含 API 密钥验证与按秒计费（基础费率 × 视频时长秒数，向上取整），具体费率以 api_services 表配置为准。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| file_url | string | 是 | - | 待转写的视频文件 URL |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息（成功/失败原因） |
+| text | string | 转写文本结果 |
+| billing | object | 计费信息 |
+| billing.service_fee | number | 本次服务费用 |
+| billing.discount_applied | boolean | 是否应用折扣/计费 |
+| billing.balance_before | number | 扣费前余额 |
+| billing.balance_after | number | 扣费后余额 |
+| billing.currency | string | 货币单位（CNY） |
+| billing.transaction_id | string | 交易流水号（失败为 null） |
+| billing.base_fee | number | 基础费率（成功及余额不足分支返回） |
+| billing.duration_seconds | number | 计费时长（秒，向上取整，成功及余额不足分支返回） |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/video_to_text" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"file_url": "https://example.com/video.mp4"}'
+```
+
+## 注意事项
+1. 视频时长超过 20 分钟将被拒绝转写并返回失败，不计费。
+2. 采用后扣费模式：转写失败、无法获取时长、密钥无效等异常均不扣费（service_fee 为 0）。
+3. 单次转写超时约 55 秒，超时视为失败且不扣费。
+4. 费用 = 基础费率 × 视频时长（向上取整秒数）；余额不足时返回失败且预置计费信息（transaction_id 为 null）。