Ununu 工具调用文档POST
AI 助手安装说明
本页只说明可用工具、Key、接口、返回和错误。把本页发给你的 AI 助手，它只需要知道这些公开能力和接口。
基础地址
https://skill.founderx.dev所有公开接口都以这个地址为前缀。所有接口都使用 POST。
使用流程
- 没有 Key：创建首次购买订单，展示微信支付二维码，支付成功后保存 issued_key。
- 已有 Key：先查 Key 状态，再预估、提交、查询任务，最后返回下载地址。
- 积分不足：创建积分包充值订单。
- Key 到期：创建续费订单；续费沿用当前套餐。
- 续费叠加有效期；升级套餐从支付成功时间重新开始；积分包不改变有效期。
- 下载地址有有效期，过期后重新查询任务。
可用工具
视频号解析下载
- 工具 ID：videohao.download
- 输入：视频号链接，例如 https://weixin.qq.com/sph/AVJ7zN0H7v。
- 输出：任务 ID、任务状态、文件名、文件大小、下载地址、扣费结果。
- 计费：按实际下载文件大小扣积分；每 100MB 扣 1 积分，不足 100MB 按 1 积分算。
- 安全：只返回网关下载地址，不返回 Cookie、上游签名链接或服务端密钥。
Key 和支付
- 首次购买可以选择包月、包季或包年。
- 续费必须使用当前 Key，默认沿用当前套餐。
- 续费在未过期时叠加有效期；过期后从支付成功时间重新开始。
- 升级套餐从支付成功时间重新开始，并切换到新套餐。
- 积分包只增加积分，不延长有效期。
- Key 过期不会清空积分；续费后继续保留余额。
- 微信支付订单会返回 pay_url 和/或 qr_code_url。
套餐
| 套餐 ID | 名称 | 价格 | 积分 | 有效期 |
|---|---|---|---|---|
| monthly_3000 | 包月 | ￥9.90 | 3000 积分 | 31 天 |
| quarterly_10000 | 包季 | ￥26.90 | 10000 积分 | 93 天 |
| yearly_48000 | 包年 | ￥89.90 | 48000 积分 | 366 天 |
| credits_1000 | 积分包 | ￥5.00 | 1000 积分 | 不延长有效期 |
接口
请求头统一使用 Content-Type: application/json。需要 Key 的接口再加 Authorization: Bearer 用户 Key。
POST
查询工具
/api/v1/skills
不需要 Key
需要提供
- 不需要参数
会返回
- 返回当前可用工具
- 包含工具 ID、分类、状态和服务商
POST
查询 Key
/api/v1/me
Authorization: Bearer <用户Key>
需要提供
- 不需要参数
会返回
- 返回 Key 状态
- 返回套餐、积分余额、预留积分和到期时间
POST
预估视频号下载
/api/v1/skills/videohao.download/quote
Authorization: Bearer <用户Key>
需要提供
- url：视频号链接
会返回
- 返回视频标题、作者等媒体信息
- 返回预估积分和是否可下载
POST
提交视频号下载
/api/v1/skills/videohao.download/run
Authorization: Bearer <用户Key>
需要提供
- url：视频号链接
- Idempotency-Key：可选，用于避免重复提交
会返回
- 创建下载任务
- 返回 job_id、任务状态和预估扣费
POST
查询任务
/api/v1/jobs/{job_id}
Authorization: Bearer <用户Key>
需要提供
- job_id：提交下载时返回的任务 ID
会返回
- 返回任务进度和扣费结果
- 成功后返回文件名、文件大小和临时下载地址
POST
下载文件
/api/v1/files/download/{token}
不需要 Key，token 是临时下载凭证
需要提供
- token：查询任务返回的下载凭证
- Range：可选，用于断点或分段下载
会返回
- 返回视频文件
- 下载地址会过期，过期后重新查询任务
POST
查询套餐
/api/v1/plans
不需要 Key
需要提供
- 不需要参数
会返回
- 返回包月、包季、包年和积分包
- 包含价格、积分和有效期
POST
创建支付订单
/api/v1/orders
首次购买不需要 Key；续费、升级、充值需要 Authorization
需要提供
- order_kind：first_purchase、renewal、upgrade 或 top_up
- plan_id：首次购买、升级、充值时传入目标套餐
- provider：可选，默认微信支付
会返回
- 返回订单号、金额和过期时间
- 微信支付会返回支付链接或二维码
POST
查询支付订单
/api/v1/orders/{order_id}
不需要 Key；order_id 按临时凭证保存
需要提供
- order_id：创建订单时返回的订单号
会返回
- 返回订单状态、支付状态、支付链接、二维码和过期时间
- 支付成功后返回结算结果，首次购买只返回一次 issued_key
错误处理
| 错误码 | 含义 |
|---|---|
| INVALID_KEY | Key 不存在、写错或缺少 Authorization。 |
| PAYMENT_REQUIRED | Key 还没有付款开通。 |
| KEY_EXPIRED | Key 已过期，需要续费。 |
| KEY_DISABLED / KEY_REVOKED | Key 被禁用或撤销，需要联系管理员。 |
| INSUFFICIENT_CREDITS | 积分不足，需要充值积分包。 |
| PROVIDER_CREDENTIAL_EXPIRED | 视频号服务凭据失效，需要管理员刷新元宝 Cookie。 |
| VIDEOHAO_METADATA_ONLY | 链接不是可下载视频，可能只有图文或元数据。 |
| JOB_FAILED | 任务失败，展示错误原因；retryable=true 时可重试。 |
| DOWNLOAD_TOKEN_EXPIRED | 下载链接过期，重新查询任务获取新的下载地址。 |
安全边界
不要把完整 Key 展示在普通聊天里。
不要泄露 Cookie、服务端密钥或上游签名视频地址。
同一个请求不要重复提交 run。
保存 order_id、pay_url、qr_code_url、download_url 时按临时敏感信息处理。
支付二维码过期后重新创建订单。
所有失败保留错误码，并用中文告诉用户下一步。