aiconductor-cli 1.3.4 → 1.4.0

package/api_docs/doubao_search.md

@@ -0,0 +1,80 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/doubao_search`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+豆包搜索 Custom 版，支持网页与图片搜索，套餐密钥优先；套餐不可用时自动切换按量密钥。按次计费，当前基础价格为0.02元/次，业务成功后扣费。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| query | string | 是 | - | 搜索关键词，1~100字符。 |
+| search_type | string | 是 | - | 搜索类型：`web`（网页）或 `image`（图片）。 |
+| count | integer | 否 | web为`10`，image为`5` | 返回条数；web范围为1~50，image范围为1~5。 |
+| query_rewrite | boolean | 否 | `false` | 是否开启 Query 改写。 |
+| need_content | boolean | 否 | `false` | 仅web：是否仅返回包含正文的结果。 |
+| need_url | boolean | 否 | `false` | 仅web：是否仅返回带原文链接的结果。 |
+| sites | string | 否 | - | 仅web：限定搜索站点，完整域名以`\|`分隔，最多20个。 |
+| block_hosts | string | 否 | - | 仅web：屏蔽站点，完整域名以`\|`分隔，最多5个。 |
+| auth_info_level | integer | 否 | `0` | 仅web：权威度过滤，`0`不限制，`1`仅非常权威内容。 |
+| time_range | string | 否 | - | 仅web：`OneDay`、`OneWeek`、`OneMonth`、`OneYear`，或`YYYY-MM-DD..YYYY-MM-DD`。 |
+| content_formats | string | 否 | `text` | 仅web：正文格式，`text`或`markdown`。 |
+| industry | string | 否 | - | 仅web：行业搜索类型，`finance`、`game`或`gov`。 |
+| image_width_min | integer | 否 | - | 仅image：图片最小宽度，不能大于`image_width_max`。 |
+| image_width_max | integer | 否 | - | 仅image：图片最大宽度。 |
+| image_height_min | integer | 否 | - | 仅image：图片最小高度，不能大于`image_height_max`。 |
+| image_height_max | integer | 否 | - | 仅image：图片最大高度。 |
+| image_shapes | array&lt;string&gt; / string | 否 | - | 仅image：允许的形状：`横长方形`、`竖长方形`、`方形`。POST传数组；GET以`\|`分隔。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功。 |
+| message | string | 响应消息。 |
+| data | object | 原样保留的豆包上游完整响应。 |
+| data.ResponseMetadata | object | 上游元信息，包含`RequestId`；上游业务失败时包含`Error`。 |
+| data.ResponseMetadata.Error.Code | string | 上游错误码。 |
+| data.ResponseMetadata.Error.Message | string | 上游错误说明。 |
+| data.Result | object | 搜索结果；上游业务失败时为`null`。 |
+| data.Result.ResultCount | integer | 搜索结果数量。 |
+| data.Result.WebResults | array | 网页结果列表，仅`search_type=web`返回。 |
+| data.Result.ImageResults | array | 图片结果列表，仅`search_type=image`返回。 |
+| data.Result.SearchContext | object | 搜索上下文，包含原始关键词与搜索类型。 |
+| data.Result.TimeCost | integer | 上游搜索耗时，单位毫秒。 |
+| data.Result.LogId | string | 上游日志ID。 |
+| 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 | integer | 成功扣费后的交易ID；未扣费时为`null`。 |
+| billing.error | string | 失败原因；成功时为`null`。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/doubao_search" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "最新的北京游玩攻略",
+    "search_type": "web",
+    "count": 10,
+    "need_url": true,
+    "time_range": "OneYear",
+    "content_formats": "markdown"
+  }'
+```
+
+## 注意事项
+1. 搜索成功后才扣费；参数校验失败、上游业务错误、网络错误和余额不足均不会扣费。
+2. 服务优先使用`BYTED_WEB_SEARCH_SUBSCRIPTION_API_KEY`；仅上游返回套餐不支持、套餐不可用或套餐额度耗尽（10409、10410、10412）时，才自动切换`BYTED_WEB_SEARCH_POSTPAID_API_KEY`。
+3. 套餐与按量密钥均未配置时接口会返回服务异常；密钥只应配置在服务端`.env`中，不得由调用方传入。
+4. `data`为上游完整响应，请按`data.Result.WebResults`或`data.Result.ImageResults`读取结果。

package/api_docs/douyin_link_to_text_v1.md

@@ -0,0 +1,50 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_link_to_text_v1`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将抖音视频链接转换为文字（语音转写）。按次计费，费用以 api_services 表配置为准：含下载解析费（服务码 `Get_Download_Url`）+ 转写费（服务码 `douyin_link_to_text_v1`，转写费 = 基础费率 × 视频时长秒数向上取整）。仅转写成功才计转写费；时长超过 20 分钟会失败。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| video_url | string | 是 | - | 抖音视频分享链接或包含链接的文本。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功。 |
+| message | string | 响应消息。 |
+| text | string | 转写得到的文本；失败时为固定值 `文字提取失败`。 |
+| billing | object | 计费信息。 |
+| billing.service_fee | float | 本次总扣费（下载费 + 转写费）。 |
+| billing.base_fee | float | 转写基础费率（仅在转写成功时出现）。 |
+| billing.duration_seconds | integer | 计费时长秒数（向上取整，仅转写成功时出现）。 |
+| billing.discount_applied | boolean | 是否应用折扣。 |
+| billing.balance_before | float | 扣费前余额。 |
+| billing.balance_after | float | 扣费后余额。 |
+| billing.currency | string | 货币类型，固定为 `CNY`。 |
+| billing.transaction_id | integer | 成功扣费后的交易ID；未扣费/失败时 `null`。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/douyin_link_to_text_v1" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "video_url": "https://v.douyin.com/xxxxxxxx/"
+  }'
+```
+
+## 注意事项
+1. 先校验 API 密钥与余额（最低需 0.02 元），解析链接与下载失败不扣费；仅下载成功扣下载费，仅转写成功再扣转写费。
+2. 视频时长 ≤5 分钟走 Coze STT；5~20 分钟走阿里云 STT；超过 20 分钟直接返回失败，不扣费。
+3. 转写失败（如准确度不达标、上游异常）仅扣除已产生的下载费，不再扣转写费。
+4. 返回的 `text` 在失败分支固定为字符串 `文字提取失败`。

package/api_docs/douyin_link_to_text_v2.md

@@ -0,0 +1,50 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_link_to_text_v2`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+将抖音视频链接转换为文字（语音转写，V2 增强版：多级转写策略 + 准确度校验 + 备用解析链路）。按次计费，费用以 api_services 表配置为准：含下载解析费（服务码 `Get_Download_Url`）+ 转写费（服务码 `douyin_link_to_text_v2`，转写费 = 基础费率 × 视频时长秒数向上取整）。时长超过 20 分钟会失败。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| video_url | string | 是 | - | 抖音视频分享链接或包含链接的文本。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功。 |
+| message | string | 响应消息。 |
+| text | string | 转写得到的文本；失败时为固定值 `文字提取失败`。 |
+| billing | object | 计费信息。 |
+| billing.service_fee | float | 本次总扣费（下载费 + 转写费）。 |
+| billing.base_fee | float | 转写基础费率（仅在转写成功时出现）。 |
+| billing.duration_seconds | integer | 计费时长秒数（向上取整，仅转写成功时出现）。 |
+| billing.discount_applied | boolean | 是否应用折扣。 |
+| billing.balance_before | float | 扣费前余额。 |
+| billing.balance_after | float | 扣费后余额。 |
+| billing.currency | string | 货币类型，固定为 `CNY`。 |
+| billing.transaction_id | integer | 成功扣费后的交易ID；未扣费/失败时 `null`。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/douyin_link_to_text_v2" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "video_url": "https://v.douyin.com/xxxxxxxx/"
+  }'
+```
+
+## 注意事项
+1. 先校验 API 密钥与余额（最低需 0.02 元），解析链接与下载失败不扣费；仅下载成功扣下载费，仅转写成功再扣转写费。
+2. 主解析（`get_video_download_url`）失败时会自动回退到 `douyin_video_parser` 备用解析链路。
+3. 转写支持 mp3 / mp4 双策略，并对结果做准确度校验（每秒中文字符数不足判为失败）；时长超过 20 分钟直接失败，不扣费。
+4. 转写失败（准确度不达标、上游异常）仅扣除已产生的下载费，不再扣转写费。

package/api_docs/douyin_user_detail.md

@@ -0,0 +1,65 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_user_detail`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据抖音用户主页 URL 获取用户详情，自动解析长链接并提取 sec_user_id，返回分类后的用户信息。按次计费，费用以 api_services 表配置为准（服务码 `douyin_user_info`）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| home_page | string | 是 | - | 抖音用户主页 URL（支持短链接，会自动解析为长链接）。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功。 |
+| message | string | 响应消息。 |
+| data | object | 分类后的用户详情。 |
+| data.identity.uid | string | 用户 uid。 |
+| data.identity.sec_user_id | string | 用户 sec_uid。 |
+| data.identity.unique_id | string | 抖音号 / short_id。 |
+| data.identity.nickname | string | 昵称。 |
+| data.profile.signature | string | 个性签名。 |
+| data.profile.avatar | string | 头像地址。 |
+| data.profile.cover_url | array | 主页背景图地址列表。 |
+| data.profile.gender | integer | 性别。 |
+| data.profile.user_age | integer | 年龄。 |
+| data.profile.ip_location | string | IP 归属地。 |
+| data.profile.custom_verify | string | 自定义认证信息。 |
+| data.stats.following_count | integer | 关注数。 |
+| data.stats.follower_count | integer | 粉丝数。 |
+| data.stats.mplatform_followers_count | integer | 全平台粉丝数。 |
+| data.stats.total_favorited | integer | 获赞总数。 |
+| data.stats.aweme_count | integer | 作品数。 |
+| data.live.live_status | integer | 直播状态。 |
+| data.live.room_id | string | 直播间 ID。 |
+| 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 | integer | 成功扣费后的交易ID；未扣费时为 `null`。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/douyin_user_detail" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "home_page": "https://www.douyin.com/user/xxxxxx"
+  }'
+```
+
+## 注意事项
+1. 先校验 API 密钥与余额，余额不足或密钥无效不扣费；链接解析失败、sec_user_id 提取失败、上游请求最终失败均不扣费。
+2. 上游请求内置最多 10 次重试（每次间隔 2 秒）；全部重试失败才返回错误。
+3. 上游（RapidAPI）密钥仅配置在服务端，调用方无需也不应传入。

package/api_docs/douyin_user_search.md

@@ -0,0 +1,58 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_user_search`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据关键词搜索抖音用户，支持按粉丝数量、用户类型筛选，并自动翻页。按页计费，费用以 api_services 表配置为准（服务码 `douyin_user_search`，每翻一页扣一次费，不足一页不扣）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| keyword | string | 是 | - | 搜索关键词。 |
+| douyin_user_fans | string | 否 | `''` | 粉丝量筛选条件（透传 TikHub 接口，如 `1_10` 表示区间）。 |
+| douyin_user_type | string | 否 | `''` | 用户类型筛选条件。 |
+| max_pages | integer | 否 | `1` | 最大翻页页数，`0` 表示不限制页数（受 max_seconds 约束）。 |
+| max_seconds | integer | 否 | `180` | 最大运行秒数，内部上限 180 秒。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功。 |
+| message | string | 响应消息。 |
+| data | object | 搜索结果。 |
+| data.user_list | array | 用户列表，每项含 uid、nickname、unique_id、sec_uid、short_id、signature、avatar_url、follower_count、total_favorited、aweme_count、enterprise_verify_reason 等字段。 |
+| data.cursor | integer | 下一页游标。 |
+| data.has_more | integer | 是否还有更多（0/1）。 |
+| billing | object | 计费信息。 |
+| billing.service_fee | float | 单页服务费率。 |
+| billing.total_fee | float | 实际总扣费（页数 × 单页费率）。 |
+| billing.discount_applied | boolean | 是否应用折扣。 |
+| billing.pages_charged | integer | 实际扣费页数。 |
+| billing.balance_before | float | 扣费前余额。 |
+| billing.balance_after | float | 扣费后余额。 |
+| billing.currency | string | 货币类型，固定为 `CNY`。 |
+| billing.transaction_ids | array | 各页扣费交易ID列表。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/douyin_user_search" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "keyword": "美食博主",
+    "douyin_user_fans": "100000_500000",
+    "max_pages": 3
+  }'
+```
+
+## 注意事项
+1. 仅当某一页成功返回用户数据时才对该页扣费；第一页即失败则不扣费，并直接返回失败。
+2. 受 `max_pages` 与 `max_seconds`（上限 180 秒）双重限制；超时或后续翻页失败会返回已成功获取的部分数据（success 仍为 true）。
+3. 上游（TikHub）密钥仅配置在服务端，调用方无需也不应传入。

package/api_docs/douyin_user_videos.md

@@ -0,0 +1,49 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_user_videos`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+
+## 功能说明
+根据抖音用户主页URL获取该用户发布的视频列表，支持分页获取和时间限制，按页计费（0.03元/页）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| home_page | string | 是 | - | 抖音用户主页URL |
+| api_key | string | 是 | - | 计费系统API密钥 |
+| max_seconds | integer | 否 | 50 | 最长运行时间（秒），最大50 |
+| max_pages | integer | 否 | 1 | 最大页数 |
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功 |
+| message | string | 响应消息 |
+| data | object | 视频数据 |
+| data.aweme_list | array | 视频列表 |
+| data.aweme_list[].author | object | 作者信息（nickname、signature） |
+| data.aweme_list[].create_time | integer | 创建时间戳 |
+| data.aweme_list[].create_time_formatted | string | 格式化创建时间 |
+| data.aweme_list[].home_page | string | 用户主页URL |
+| data.aweme_list[].desc | string | 视频描述 |
+| data.aweme_list[].share_url | string | 分享链接 |
+| data.aweme_list[].cover_url | string | 视频封面图片链接 |
+| data.aweme_list[].duration | string | 视频时长（MM:SS） |
+| data.aweme_list[].statistics | object | 统计数据（点赞、收藏、评论、分享） |
+| billing | object | 计费信息 |
+| billing.service_fee | float | 每页服务费 |
+| billing.total_fee | float | 总费用 |
+| billing.discount_applied | boolean | 是否应用折扣 |
+| billing.pages_charged | integer | 计费页数 |
+| billing.balance_before | float | 扣费前余额 |
+| billing.balance_after | float | 扣费后余额 |
+| billing.currency | string | 货币类型（CNY） |
+| billing.transaction_ids | array | 交易ID列表 |
+
+## 注意事项
+1. 支持抖音短链接和长链接，自动解析
+2. max_seconds最大值为50秒
+3. 按页收费，每成功获取一页数据扣费一次
+4. 达到时间限制或页数限制时会自动停止翻页

package/api_docs/douyin_user_videos_async.md

@@ -0,0 +1,45 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_user_videos_async`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+调用抖音异步抓取服务，自动生成 task_id 并提交异步主页抓取任务（服务端以异步方式执行，不等待结果返回）。本接口仅负责提交任务，结果需配合 `douyin_user_videos_async_query` 查询。**本插件不参与计费系统**（无 verify_api_key / billing 调用）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| home_page | string | 是 | - | 抖音用户主页链接（自动提取并解析为长链接）。 |
+| max_seconds | integer | 否 | `300` | 异步任务最长等待秒数。 |
+| max_pages | integer | 否 | `30` | 异步任务最大翻页页数。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表（该参数将一并透传给异步后端服务）。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 任务是否提交成功。 |
+| task_id | string | 本次异步任务 ID（用于后续查询结果）。 |
+| message | string | 响应消息。 |
+| status_code | integer | 异步后端返回的 HTTP 状态码（成功为 200/202；网络异常为 0）。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/douyin_user_videos_async" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "home_page": "https://www.douyin.com/user/xxxxxx",
+    "max_pages": 10
+  }'
+```
+
+## 注意事项
+1. 本接口为异步提交，返回 200/202 仅表示任务已成功提交，不代表数据已抓取完成；请用返回的 `task_id` 调用 `douyin_user_videos_async_query` 查询结果。
+2. 链接解析失败（短链无法解析）会直接返回失败，不提交任务。
+3. 本插件无计费逻辑，不会进行余额校验与扣费。
+4. 异步后端密钥/服务地址仅配置在服务端，调用方无需也不应传入。

package/api_docs/douyin_user_videos_async_query.md

@@ -0,0 +1,41 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_user_videos_async_query`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据 `douyin_user_videos_async` 提交任务后返回��� `task_id`，从结果存储（阿里云 OSS）拉取并解析对应的 JSON 结果文件。**本插件不参与计费系统**（无 verify_api_key / billing 调用，且请求本身不要求 api_key）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| task_id | string | 是 | - | 由 `douyin_user_videos_async` 返回的任务 ID。 |
+
+> **鉴权参数**：本接口逻辑不消费 api_key；若框架统一注入，可照常通过请求头 `Authorization: Bearer <api_key>` 传递，但不影响计费（无计费）。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功（查询到结果文件为 true）。 |
+| result | object | 解析后的 JSON 内容（成功时返回；失败时为空对象 `{}`）。 |
+| error | string | 错误信息（成功时为空字符串 `""`；文件未生成/网络异常时返回提示）。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/douyin_user_videos_async_query" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "task_id": "3f9b1c2e-7d4a-4c8e-9b2a-1c2d3e4f5a6b"
+  }'
+```
+
+## 注意事项
+1. `result` 的具体字段结构取决于异步任务写入的内容，本接口原样返回 OSS 上的 JSON。
+2. 若结果尚未生成（任务仍在执行），通常会返回 404 相关提示：`查询结果尚未生成，请稍后再试`。此时应稍后重试查询。
+3. 若文件明确标记 `file_exists=false`，`success` 为 false 且 `error` 携带具体原因。
+4. 本插件无计费逻辑，不会进行余额校验与扣费。

package/api_docs/douyin_user_videos_max.md

@@ -0,0 +1,59 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_user_videos_max`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据抖音用户主页 URL 获取该用户发布的视频列表，逐页获取后对每条视频调用详情接口获取完整信息（视频下载/封面链接、音乐、作者粉丝数等），支持分页与时间限制。双路独立计费，费用以 api_services 表配置为准：主页翻页按 `douyin_homepage_max` 扣费，每条成功富化的视频按 `douyin_video_info_max` 扣费。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| home_page | string | 是 | - | 抖音用户主页 URL（支持短链接，自动解析长链接并提取 sec_user_id）。 |
+| max_seconds | integer | 否 | `180` | 最长运行时间（秒），内部上限 180 秒。 |
+| max_pages | integer | 否 | `1` | 最大翻页页数，`0` 表示不限制页数（受 max_seconds 约束）。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功。 |
+| message | string | 响应消息。 |
+| data | object | 结果数据。 |
+| data.aweme_list | array | 富化后的视频列表，每项含：author{nickname,signature,sec_uid,avatar,follower_count,total_favorited}、create_time、create_time_formatted、home_page、desc、share_url、duration（MM:SS）、statistics{digg_count,collect_count,comment_count,share_count}、enriched（是否成功富化）、video_id、interaction_detail{like,collect,share,comment}、video{cover,no_watermark_video,watermark_video}、images、music{title,author,play_url}。 |
+| data.total_pages_charged | integer | 实际扣费的主页翻页数。 |
+| data.total_videos_enriched | integer | 成功富化的视频数。 |
+| data.total_videos_failed | integer | 富化失败的视频数（保留基础数据并标记 enriched=false）。 |
+| billing | object | 计费信息。 |
+| billing.service_fee_homepage | float | 主页翻页单页费率。 |
+| billing.service_fee_video | float | 单个视频详情费率。 |
+| billing.total_fee | float | 实际总扣费（主页费 + 视频费）。 |
+| billing.discount_applied | boolean | 是否应用折扣。 |
+| billing.pages_charged | integer | 实际扣费页数。 |
+| billing.videos_charged | integer | 实际扣费视频数。 |
+| billing.balance_before | float | 扣费前余额。 |
+| billing.balance_after | float | 扣费后余额。 |
+| billing.currency | string | 货币类型，固定为 `CNY`。 |
+| billing.transaction_ids | array | 全部扣费交易ID列表（主页 + 视频）。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/douyin_user_videos_max" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "home_page": "https://www.douyin.com/user/xxxxxx",
+    "max_pages": 3
+  }'
+```
+
+## 注意事项
+1. 先校验 API 密钥与余额（至少够一页主页费），余额不足或密钥无效不扣费。
+2. 双路计费：每翻一页扣一次主页费；每成功富化一条视频（余额足够时）扣一次视频费；余额不足时剩余视频不再扣费。
+3. 视频详情接口 QPS 限制为 2，内置重试机制；富化失败的视频保留基础数据并标记 `enriched=false`，不扣视频费。
+4. 上游（TikHub / RapidAPI）密钥仅配置在服务端，调用方无需也不应传入。

package/api_docs/douyin_video_comments.md

@@ -0,0 +1,68 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_video_comments`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据抖音视频 URL 获取该视频的评论列表（含评论内容、点赞数、IP 归属地、作者信息等）。按次计费，费用以 api_services 表配置为准（服务码 `douyin_single_video_comment_get`）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| video_url | string | 是 | - | 抖音视频 URL（自动解析长链接并提取 video_id）。 |
+| max_count | integer | 否 | `50` | 获取的评论条数。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功。 |
+| message | string | 响应消息。 |
+| data | object | 评论结果。 |
+| data.total | integer | 评论总数。 |
+| data.cursor | integer | 下一页游标。 |
+| data.has_more | integer | 是否还有更多（0/1）。 |
+| data.comments | array | 评论列表，每项含以下字段： |
+| data.comments[].text | string | 评论内容。 |
+| data.comments[].digg_count | integer | 评论点赞数。 |
+| data.comments[].ip_label | string | IP 归属地。 |
+| data.comments[].create_time | integer | 评论时间（Unix 时间戳）。 |
+| data.comments[].nickname | string | 评论者昵称。 |
+| data.comments[].reply_comment_total | integer | 回复总数。 |
+| data.comments[].cid | string | 评论 ID。 |
+| data.comments[].is_hot | boolean | 是否热评。 |
+| data.comments[].stick_position | integer | 置顶位置。 |
+| data.comments[].label_text | string | 标签文本。 |
+| data.comments[].reply_id | string | 回复的评论 ID。 |
+| data.comments[].level | integer | 评论层级。 |
+| data.comments[].is_author_digged | boolean | 作者是否点赞。 |
+| data.comments[].is_folded | boolean | 是否被折叠。 |
+| data.comments[].user | object | 评论者信息：uid、nickname、unique_id、sec_uid、region、avatar、custom_verify。 |
+| 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 | integer | 成功扣费后的交易ID；未扣费时为 `null`。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/douyin_video_comments" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "video_url": "https://www.douyin.com/video/7113430448613267720",
+    "max_count": 50
+  }'
+```
+
+## 注意事项
+1. 先校验 API 密钥与余额，余额不足或密钥无效不扣费；链接解析/视频 ID 提取失败不扣费。成功获取到评论数据后才扣费。
+2. 上游接口遇 HTTP 429（并发受限）或返回错误状态时自动重试（最多 5 次，每次间隔 2 秒）。
+3. 上游（RapidAPI）密钥仅配置在服务端，调用方无需也不应传入。

package/api_docs/douyin_video_info.md

@@ -0,0 +1,70 @@
+## 接口信息
+- **URL**: `http://plugin.aiconductor.fun/api/douyin_video_info`
+- **方法**: `POST` / `GET`
+- **Content-Type**: `application/json`
+- **鉴权**: 请求头 `Authorization: Bearer <api_key>`（兼容 body/query 中 `api_key` 参数）
+
+## 功能说明
+根据抖音视频分享链接获取视频详情（标题、时间、互动数据、作者、无水印/有水印视频地址、音乐等）。按次计费，费用以 api_services 表配置为准（服务码 `douyin_video_info_max`）。
+
+## 请求参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| share_url | string | 是 | - | 抖音视频分享链接或包含链接的文本（自动提取纯净链接并解析长链接）。 |
+
+> **鉴权参数**：api_key 通过请求头 `Authorization: Bearer <api_key>` 传递，不再列入请求参数表。
+
+## 响应参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| success | boolean | 是否成功。 |
+| message | string | 响应消息。 |
+| data | object | 视频详情。 |
+| data.video_id | string | 视频 aweme_id。 |
+| data.title | string | 视频描述/标题。 |
+| data.create_time | integer | 发布时间（Unix 时间戳）。 |
+| data.create_time_formatted | string | 发布日期（YYYY-MM-DD）。 |
+| data.duration | integer | 时长（毫秒）。 |
+| data.duration_seconds | integer | 时长（秒，毫秒整除 1000）。 |
+| data.interaction.like | integer | 点赞数。 |
+| data.interaction.collect | integer | 收藏数。 |
+| data.interaction.share | integer | 分享数。 |
+| data.interaction.comment | integer | 评论数。 |
+| data.author.nickname | string | 作者昵称。 |
+| data.author.sec_uid | string | 作者 sec_uid。 |
+| data.author.signature | string | 作者签名。 |
+| data.author.avatar | string | 作者头像地址。 |
+| data.author.follower_count | integer | 作者粉丝数。 |
+| data.author.total_favorited | integer | 作者获赞总数。 |
+| data.video.cover | string | 封面地址。 |
+| data.video.no_watermark_video | string | 无水印视频地址。 |
+| data.video.watermark_video | string | 有水印视频地址。 |
+| data.images | array | 图文/笔记图片地址列表（非图文视频为 `null`）。 |
+| data.music.title | string | 背景音乐标题。 |
+| data.music.author | string | 背景音乐作者。 |
+| data.music.play_url | 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 | integer | 成功扣费后的交易ID；未扣费时为 `null`。 |
+
+## 请求示例
+
+```bash
+curl -X POST "http://plugin.aiconductor.fun/api/douyin_video_info" \
+  -H "Authorization: Bearer your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "share_url": "https://v.douyin.com/xxxxxxxx/"
+  }'
+```
+
+## 注意事项
+1. 先校验 API 密钥与余额，余额不足或密钥无效不扣费；链接提取/解析失败、视频数据不存在/获取失败均不扣费。
+2. 上游接口在两个 URL 间轮流重试（最多 5 次，每次间隔 2 秒）；均失败才返回错误并扣费（因已通过余额校验，按约定本次视为已计费请求）。
+3. 上游（RapidAPI）密钥仅配置在服务端，调用方无需也不应传入。