Ununu 工具调用文档POST

AI 助手安装说明

本页只说明可用工具、Key、接口、返回和错误。把本页发给你的 AI 助手，它只需要知道这些公开能力和接口。

基础地址

https://test-skill.founderx.dev

所有公开接口都以这个地址为前缀。所有接口都使用 POST。

使用流程

  • 没有 Key：创建首次购买订单，展示微信支付二维码，支付成功后保存 issued_key。
  • 首次购买创建订单时保存 order_id 和 order_access_token；它只能查询这笔订单，不能调用工具。
  • 已有 Key：先查 Key 状态，再预估、提交、查询任务，最后返回下载地址。
  • 积分不足：创建积分包充值订单。
  • Key 到期：创建续费订单；续费沿用当前套餐。
  • 续费叠加有效期；升级套餐从支付成功时间重新开始；积分包不改变有效期。
  • 下载地址有有效期，过期后重新查询任务。

Key 保存

固定位置

  • 拿到 issued_key 后，必须写入固定配置文件，后续对话、重启和切换任务都从这里读取。
  • macOS / Linux：$HOME/.ununu/tool-gateway/config.json。
  • Windows：%USERPROFILE%\.ununu\tool-gateway\config.json。
  • 目录不存在时先创建目录；不要只保存在聊天上下文里。

读写规则

  • 文件里至少保存 base_url、key 和 updated_at。
  • 首次购买创建订单后，先保存 pending_order.order_id 和 pending_order.order_access_token。
  • 首次购买支付成功后，把查询订单返回的 issued_key 写入 key 字段。
  • 后续调用需要 Key 的接口时，先读这个文件，再发送 Authorization: Bearer <用户Key>。
  • UNUNU_GATEWAY_KEY 只作为临时覆盖，不替代这个固定文件。
  • Key 丢失或需要更换时，让用户联系管理员处理。
{
  "base_url": "https://test-skill.founderx.dev",
  "key": "<用户Key>",
  "pending_order": {
    "order_id": "<首次购买订单ID>",
    "order_access_token": "<订单访问凭证>"
  },
  "updated_at": "<ISO时间>"
}

可用工具

视频号解析下载

  • 工具 ID：videohao.download
  • 输入：视频号链接，例如 https://weixin.qq.com/sph/AVJ7zN0H7v。
  • 输出：任务 ID、任务状态、文件名、文件大小、下载地址、扣费结果。
  • 计费：按实际下载后的文件大小扣积分；每 1MB 扣 1 积分，不足 1MB 按 1 积分算。
  • 安全：只返回网关下载地址，不返回 Cookie、上游签名链接或服务端密钥。

Key 和支付

  • 每次调用需要 Key 的接口时，都用 Authorization: Bearer <用户Key>。
  • 首次购买可以选择包月、包季或包年。
  • 首次购买支付前不会返回正式 Key，只返回订单访问凭证。
  • 续费、升级和积分充值都继续使用同一个 Key。
  • 续费必须使用当前 Key，默认沿用当前套餐。
  • 续费叠加有效期；升级套餐从支付成功时间重新开始并切换套餐。
  • 积分包只增加积分，不延长有效期。
  • Key 过期不会清空积分；续费后继续保留余额。
  • 微信支付订单会返回 pay_url 和/或 qr_code_url。

套餐

套餐 ID名称价格积分有效期
monthly_3000包月￥9.903000 积分31 天
quarterly_10000包季￥26.9010000 积分93 天
yearly_48000包年￥89.9048000 积分366 天
credits_1000积分包￥5.001000 积分不延长有效期

Key 状态决策

无需付款

  • /api/v1/me 返回 key.status=active、key.is_expired=false、credits.available 足够时，直接调用工具。
  • 每次下载前可以先 quote 预估积分，再 run。

需要首次购买

  • 本地固定配置文件没有 key 时，调用 /api/v1/orders 创建 first_purchase。
  • 保存 order_id 和 order_access_token；付款后用它查询订单。
  • 查询到 settlement_result.issued_key 后，立刻保存为 key。

需要续费或升级

  • /api/v1/me 返回 key.is_expired=true，创建 renewal 订单，续费沿用当前套餐。
  • 用户要换更高套餐时，创建 upgrade 订单并传目标订阅 plan_id。
  • 续费和升级必须使用当前 Key，只能查询当前 Key 的订单。

需要充值

  • 接口返回 INSUFFICIENT_CREDITS 或 credits.available 不足时，可以创建 top_up 订单。
  • top_up 只允许选择积分包 plan_id，例如 credits_1000。
  • 积分包只加积分，不改变 Key 有效期。

接口

请求头统一使用 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：可选，默认微信支付
会返回
  • 返回订单号、金额和过期时间
  • 首次购买会返回 order_access_token，只能查询这笔订单
  • 微信支付会返回支付链接或二维码
POST

查询支付订单

/api/v1/orders/{order_id}
首次购买用 order_access_token；续费、升级、充值用 Authorization
需要提供
  • order_id：创建订单时返回的订单号
  • order_access_token：仅首次购买订单需要
会返回
  • 返回订单状态、支付状态、支付链接、二维码和过期时间
  • 首次购买支付成功后返回 issued_key，拿到后必须立刻保存为用户 Key

错误处理

错误码含义
INVALID_KEYKey 不存在、写错或缺少 Authorization。
PAYMENT_REQUIREDKey 还没有付款开通。
KEY_EXPIREDKey 已过期，需要续费。
KEY_DISABLED / KEY_REVOKEDKey 被禁用或撤销，需要联系管理员。
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 时按临时敏感信息处理。
支付二维码过期后重新创建订单。
所有失败保留错误码，并用中文告诉用户下一步。