# Oil Tone Pro 接口

POST https://api.oiloil.org/v1/text/polish

去掉套话和 AI 味，把中文或英文文案改得自然、易读、通顺、清楚。只改表达，不加入原文和背景里都没有的内容。

## 开放状态

登录后即可使用。Skill 安装包可从 Tone 自身域名免费下载；服务暂时不可用时保留原文并显示实际错误。

## 安装 Skill

下载 [ZIP](https://tone.oiloil.org/downloads/oil-tone-pro/oil-tone-pro-0.2.1.zip)，按[版本元数据](https://tone.oiloil.org/downloads/oil-tone-pro/release-manifest.json)的 downloads.zip.sha256 核对文件摘要，再解压。将包内唯一的 oil-tone-pro 文件夹放进当前 Agent 的技能目录：Codex 使用 ~/.codex/skills/，Claude Code 使用 ~/.claude/skills/，其他 Agent 按自己的技能目录安装。已有安装先备份旧目录再整体替换，然后按 Agent 要求重新加载技能。

需要 Node 18.17 及以上。在 Skill 文件夹执行 node scripts/tone.mjs version 和 node scripts/tone.mjs health；health 不收费。需要登录时执行 node scripts/tone.mjs login，仍由 oil CLI 发起账户网页授权；CI 使用 OIL_TOKEN。不要将令牌写进命令参数、URL 或对话。更新时按新的元数据下载并核验压缩包，重复上述替换步骤。

## 请求

请求头：

- `Authorization: Bearer <令牌>`，令牌从环境变量 `OIL_TOKEN` 读取，不写进代码、URL 或日志。Skill 通过登录命令取得设备令牌；网页账户使用邮箱验证码登录
- `Content-Type: application/json`
- `Idempotency-Key: <UUID>`，每次新的润色操作生成一个 UUID。网络失败后再次查询或重发同一操作，沿用同一个键和完全相同的请求体，不换键自动重试

请求体：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `text` | string | 一段或一篇文字，最多 20000 字符。和 `items` 二选一 |
| `items` | array | 一批互相独立的短文案，最多 100 条、合计最多 20000 字符。每条是 `{ "id", "text", "note"? }`：`id` 原样返回；`note` 是只针对这一条的说明，如出现的位置和字数限制 |
| `context` | string | 选填，最多 4000 字符。文字用在哪里、读者是谁、有哪些已经确认的事实。没有背景时，空泛的句子只能写短，没有具体内容可以换上去 |
| `reorder` | boolean | 选填，默认 false。是否允许调整句子和段落的顺序 |

## 返回

| 字段 | 说明 |
| --- | --- |
| `text` | 润色后的文字，请求用 `text` 时返回 |
| `items` | 润色后的各条文字，顺序和 `id` 与请求一致，请求用 `items` 时返回 |
| `usage.characters` | 原文的字符数 |
| `usage.credits` | 这次使用的积分 |
| `usage.balance` | 可用积分 |
| `id` | 请求编号 |

## 报错

`{ "error": { "code", "message", "param"? }, "request_id" }`

400 照着 `message` 修改参数。401 是令牌没带、写错或已撤销；402 是可用积分不足，把 `message` 转告用户，不要重试。409 是同一幂等键已在处理，或键与请求不匹配；保持原操作上下文。429 是达到限额，按 `Retry-After` 等待，不自动发起另一项操作。服务暂时不可用时显示中文错误。502、504 或网络中断可能没有收到完整结果，用户决定重试时沿用原幂等键和请求体。

## 账户与充值

账户页可以查看余额、充值与使用记录。充值 $10、$20、$50，分别到账 1000、2000、5000 积分。

请求均需 Bearer 令牌。账户页：https://tone.oiloil.org/account。网页使用邮箱验证码登录，刷新页面和支付返回后会恢复登录；退出登录会清除当前网页会话。Skill 的设备令牌与服务器、CI 的 OIL_TOKEN 仍用于接口调用。