API 与 CLI

选择适合的接入方式

业务系统可通过 API 创建、查询和修改短链；终端操作与自动化可使用 maolv CLI；支持 Skill 和本地命令执行的 AI 工具可安装毛驴 Skill。三种方式都使用现有账号的 API Token，仍受账号套餐、链接有效期和接口权限限制。

API 参数及响应字段以完整 API 文档为准；安装命令、下载地址与当前使用说明见AI 与 CLI 页面。会员购买、域名绑定和详细访问报表仍需在官网控制台操作。

生成与保护 API Token

1. 注册并登录后，打开API Token 管理。
2. 尚无 Token 时点击“生成 token”，再复制到业务服务器的安全配置或在本机终端交互输入。
3. 接入程序需要更新凭据或怀疑泄露时，可点击“重新生成”。旧 Token 会立即失效，需同步更新所有调用方。

Token 属于账号凭据，不应放在公开网页、前端代码、代码仓库、截图或日志中，也不要粘贴到 AI 对话。自动化任务使用环境变量等安全配置，不把真实 Token 写进示例命令或公开配置。

API 的第一次调用

先将 Token 存入业务服务器环境变量 MAOLV_API_TOKEN，再按完整 API 文档进行调用。以下为创建普通短链的示例：

curl --request POST 'https://www.maolvdl.com/apic/v1/api/cubes' \
  --data-urlencode "api_token=${MAOLV_API_TOKEN}" \
  --data-urlencode 'links=https://example.com/campaign' \
  --data-urlencode 'cube_name=渠道入口测试'

创建参数是 links，不是 link。保存响应中的 id、short 与 short_link；其中 short_link 是可分享的完整短地址，查询接口路径使用文档要求的短地址标识。

操作	方法与路径	注意事项
创建短链	POST /apic/v1/api/cubes	目标网址参数为 links，名称为 cube_name。
查询单条短链	GET /apic/v1/api/cubes/{id}	按 API 文档传入短地址标识和 Token。
快速修改普通短链	POST /apic/v1/api/cubes/{id}/fast_modify	修改目标参数为 link，不是 url；不覆盖高级分流规则。

API 文档中的分组列表接口注明需联系客服开通。不要假定所有账号均可使用全部接口，也不要把创建接口与修改接口的参数名混用。

安装与配置 CLI

1. 打开/cli 安装说明，按实际系统下载并执行对应安装脚本，或从页面链接的 GitHub Releases 下载程序。
2. 安装后按页面说明将程序目录加入命令搜索路径。
3. 在本机终端运行下列命令，按提示输入 Token。交互输入不回显；若已设置 MAOLV_API_TOKEN 环境变量，CLI 优先使用该变量。

maolv config set-token
maolv project list --json

项目查询受账号接口权限影响；查询失败时先阅读错误，不要仅凭一次失败认定 Token 无效。当前安装器不会覆盖已有 CLI，更新 CLI 与更新 Skill 是独立操作，应按/cli 中的更新说明处理。

授权与权限确认后，可创建一条普通短链：

maolv link create https://example.com --name '产品首页' --project '官网' --json

--project 使用项目名称，缺失的项目可能由 API 创建。自动化程序可用 --json 读取结果。CLI 的查询与修改使用短码 short，不要传数据库记录 ID 或完整短链 URL。更多命令见/cli 的使用文档入口。

在 AI 工具中使用

按/cli 的 AI Skill 安装说明，将完整 skills/maolv 目录安装到所用工具支持的位置，保留其中的安装脚本；也可使用该页提供的 Skill 安装命令。

安装并完成本机授权后，可以向支持的 AI 工具描述“为活动页创建毛驴短链”“查询项目列表”或“修改某个短码的目标地址”。执行能力取决于所用工具是否支持 Skill 与本地命令，具体安装路径以对应说明为准。

错误与重试

• 鉴权失败：检查 Token 是否为空、是否已轮换，以及环境变量是否覆盖了本机配置。
• 参数错误：核对目标网址、创建与修改的参数名、短码及链接类型；不要无限重试同一个错误请求。
• 创建或修改超时：先查询并核对服务端结果，再决定是否重试，避免重复创建或重复变更。
• 额度或有效期问题：检查域名与套餐。体验链接创建后 10 分钟失效，修改和升级不会延长原链接；正式投放应在配置完成后创建正式链接。

当前 CLI 的目标修改仅支持普通短链，设备、比例、时间和地域规则应使用控制台规则编辑。API 文档未给出统一每秒请求额度，接入前应核对当前账号权限，不应假定无限调用。