接口文档

安装 Skill，或为自己的产品接入 Oil Tone Pro。安装免费，云端润色和充值入口已开放；润色按实际 Token 用量扣积分。

交给 Agent 接入

把这份文档连同一句说明复制给 Claude Code、Codex 或其他 Agent，让它把接口接进你的项目。

查看提示词内容

帮我在这个项目里接入 Oil Tone Pro 的润色接口。先阅读开放状态，再看哪些地方需要润色文案，按下面的说明实现调用；令牌用环境变量，服务暂时不可用时保留用户文案并显示实际报错。

# Oil Tone Pro 接口

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

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

## 开放状态

云端润色和充值入口已开放，润色按实际 Token 用量扣积分。Skill 安装包可从 Tone 自身域名免费下载；服务暂时不可用时保留原文并显示实际错误。历史本机样例只用于了解润色结果。

## 安装 Skill

下载 [ZIP](https://tone.oiloil.org/downloads/oil-tone-pro/oil-tone-pro-0.2.0.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 或日志。个人令牌在 https://ui.oiloil.org/account/ 获取；本产品还没有网页登录
- `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` | 这次按实际 Token 扣的积分 |
| `usage.balance` | 结算后可用积分 |
| `id` | 请求编号 |

## 报错

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

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

## 历史本机例子

下面的原文和模型返回来自 2026 年 10 月 13 日的本机测试，保持原样。例子中的旧赠送、字数扣费及安装描述都是历史测试条件，不代表当前政策。返回里的 credits 和 balance 也不是按新 Token 费率重算的数值。

请求：

```json
{
  "context": "Oil Tone Pro 官网首页的文案。读者是用 AI Agent 写文案、做产品的人。",
  "items": [
    { "id": "how.lead", "text": "把一句安装提示词发给 Agent，首次使用时在浏览器登录 oiloil 账号。装好 Skill 后，Agent 写完就会自动送稿润色。接入自己的产品可调用 POST /v1/text/polish，一次最多 100 条短文案。", "note": "上一条标题下面的说明" },
    { "id": "know.topup", "text": "充值入口暂未开放。目前可以使用新账号赠送的 100 积分；余额不足后，暂时无法通过充值继续使用。", "note": "“用之前请了解”的第二段" },
    { "id": "mail.low", "text": "{{name}}，你的 Oil Tone Pro 积分余额为 {{balance}}，**积分余额不足**，无法继续润色。充值入口目前暂未开放，开放后可前往 [充值页面](https://tone.oiloil.org/#pricing) 补充积分。", "note": "积分余额不足时发给用户的提醒邮件正文" }
  ]
}
```

返回：

```json
{
  "id": "req_11484704e6d8193d",
  "items": [
    { "id": "how.lead", "text": "把安装提示词发给 Agent，首次使用时在浏览器里登录 oiloil 账号。装好 Skill 后，Agent 写完内容就会自动送来润色。如果要接入自己的产品，可以调用 POST /v1/text/polish 接口，单次最多支持 100 条短文案。" },
    { "id": "know.topup", "text": "充值功能暂未开放。新账号可以使用赠送的 100 积分；积分用完后，暂时还无法通过充值继续使用。" },
    { "id": "mail.low", "text": "{{name}}，你的 Oil Tone Pro 积分余额为 {{balance}}。目前**积分余额不足**，无法继续润色。充值入口暂未开放，开放后你可以前往 [充值页面](https://tone.oiloil.org/#pricing) 补充积分。" }
  ],
  "usage": { "characters": 286, "credits": 5.065, "balance": 94.935 }
}
```

## 账户与充值

- GET https://api.oiloil.org/v1/credits：`balance` 可用积分、`total_balance` 总余额、`reserved` 正在预留的积分
- GET https://api.oiloil.org/v1/usage：`balance`、`month`（近 30 天调用和扣费）与 `recent`（最近 20 次调用）。旧记录可能只有 characters，新记录含实际 Token 用量
- GET /v1/keys、POST /v1/keys、DELETE /v1/keys/{id}：管理 API Key，仅账号令牌（设备或个人手动令牌）可用，API Key 不能管理密钥
- POST https://api.oiloil.org/v1/topups：`{ "amount_usd": 10 | 20 | 50 }`，带新的 UUID `Idempotency-Key`，同一购买操作重发必须沿用原键；返回订单 `id`、`url`、`amount_usd`、`credits`、`status`
- GET https://api.oiloil.org/v1/topups/{id}：查自己的订单。只有确认支付并到账后才视为充值成功

请求均需 Bearer 令牌。账户页：https://tone.oiloil.org/account。页面令牌仅在本次打开的内存中，关闭或刷新页面需要重新连接；不写入本地存储。

## 计费

按 Gemini 3.8 Flash 的实际 Token 用量计费，价格为 ZenMux 同期价格加 10%。$1 = 100 积分，精度为 0.001 积分。每百万 Token：普通输入 82.5 积分、缓存输入 8.25 积分、输出（包含思考 Token）412.5 积分。缓存 Token 已包含在输入中，不重复计费；各项合计后向上取到 0.001 积分。当前促销费率在 2027 年前有效，后续价格会另行公布。

请求先预留积分，成功后按实际用量结算，释放未使用部分；调用失败释放预留，不扣积分。新账号没有赠送积分。充值仅支持 $10、$20、$50，分别到账 1000、2000、5000 积分，无赠送。充值入口已开放；成功创建订单后由用户完成付款，不能把订单创建或浏览器跳转当作积分已到账。503 表示服务暂时不可用，保留订单上下文并显示实际原因。

接口描述文件（OpenAPI 3.1）：https://api.oiloil.org/v1/openapi.json

Agent 能联网时，也可以让它直接读 /docs.md 或 /llms.txt。

安装 Skill

下载 Oil Tone Pro 0.2.0 ZIP，按版本元数据里的 downloads.zip.sha256 核对下载文件的 SHA-256，再解压。
把包内唯一的 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，在 oiloil 账户网页确认授权，再用 node scripts/tone.mjs usage 查看积分。

更新时按最新元数据下载、核验并替换文件夹。安装包免费，润色服务按实际用量扣积分；安装成功不代表模型或充值已开放。服务器和 CI 使用环境变量 OIL_TOKEN，不要把令牌写进命令参数或对话。

地址和令牌

地址: https://api.oiloil.org/v1，请求和返回都是 JSON。接口、令牌和积分是 oiloil 各产品共用的一套
令牌: 请求头 Authorization: Bearer <令牌>。令牌是 oiloil 账号的令牌，在 ui.oiloil.org/account 新建，放进环境变量 OIL_TOKEN，不要写进代码
幂等键: 润色与创建充值订单都要带 Idempotency-Key: <UUID>。每次新操作生成一个 UUID；同一操作再次发送时，保留原键与完全相同的请求体
请求编号: 每个响应都带 x-request-id 响应头，和返回里的 id 或 request_id 相同，反馈问题时带上

`POST /v1/text/polish`

润色一段文字，或一批互相独立的短文案。成功请求按实际 Token 用量结算。

参数	类型	说明
`text`	string	一段或一篇文字，最多 20000 个字符。和 `items` 二选一
`items`	array	一批互相独立的短文案，最多 100 条，合计最多 20000 个字符。每条是 `{ id, text, note? }`：`id` 是你自己的标识，原样返回；`note` 是只针对这一条的说明，例如出现的位置和字数限制
`context`	string，选填	背景，最多 4000 个字符：文字用在哪里、读者是谁、有哪些已经确认的事实。润色时可以用这里的事实去换空话；不传时，空话只能改短
`reorder`	boolean，选填	是否允许调整句子和段落的顺序。默认 `false`，只改句子里的表达

历史本机例子

以下是 2026 年 10 月 13 日的真实返回，原样保留。赠送、旧字数扣费和安装描述是当时的测试条件；credits 与 balance 没有按新费率重算。

请求

{
  "context": "Oil Tone Pro 官网首页的文案。读者是用 AI Agent 写文案、做产品的人。",
  "items": [
    { "id": "how.lead", "text": "把一句安装提示词发给 Agent，首次使用时在浏览器登录 oiloil 账号。装好 Skill 后，Agent 写完就会自动送稿润色。接入自己的产品可调用 POST /v1/text/polish，一次最多 100 条短文案。", "note": "上一条标题下面的说明" },
    { "id": "know.topup", "text": "充值入口暂未开放。目前可以使用新账号赠送的 100 积分；余额不足后，暂时无法通过充值继续使用。", "note": "“用之前请了解”的第二段" },
    { "id": "mail.low", "text": "{{name}}，你的 Oil Tone Pro 积分余额为 {{balance}}，**积分余额不足**，无法继续润色。充值入口目前暂未开放，开放后可前往 [充值页面](https://tone.oiloil.org/#pricing) 补充积分。", "note": "积分余额不足时发给用户的提醒邮件正文" }
  ]
}

{
  "id": "req_11484704e6d8193d",
  "items": [
    { "id": "how.lead", "text": "把安装提示词发给 Agent，首次使用时在浏览器里登录 oiloil 账号。装好 Skill 后，Agent 写完内容就会自动送来润色。如果要接入自己的产品，可以调用 POST /v1/text/polish 接口，单次最多支持 100 条短文案。" },
    { "id": "know.topup", "text": "充值功能暂未开放。新账号可以使用赠送的 100 积分；积分用完后，暂时还无法通过充值继续使用。" },
    { "id": "mail.low", "text": "{{name}}，你的 Oil Tone Pro 积分余额为 {{balance}}。目前**积分余额不足**，无法继续润色。充值入口暂未开放，开放后你可以前往 [充值页面](https://tone.oiloil.org/#pricing) 补充积分。" }
  ],
  "usage": { "characters": 286, "credits": 5.065, "balance": 94.935 }
}

返回字段	说明
`text`	润色后的文字，请求用 `text` 时返回
`items`	润色后的各条文字，顺序和 `id` 与请求一致，请求用 `items` 时返回
`usage.characters`	原文的字符数，仅作统计，不用于计费
`usage.credits`	这次扣的积分
`usage.balance`	实际 Token 结算后的可用积分
`id`	请求编号

`GET /v1/usage`

余额、近 30 天的合计，和最近 20 次调用。以下数字只示意返回结构，不是实际账户账页；旧记录可能只有字符数，新记录会包含 Token 用量。

{
  "balance": 999.587,
  "month": { "calls": 1, "credits": 0.413 },
  "recent": [
    { "id": "req_example", "at": "2026-10-13T00:00:00.000Z", "characters": 215, "credits": 0.413 }
  ]
}

账户与充值

账户页可用个人令牌主动连接。本产品还没有网页登录；连接令牌只保留在当前页面内存中，刷新或关闭后清除。

接口	说明
`GET /v1/credits`	`balance` 可用积分，`total_balance` 总余额，`reserved` 正在预留的积分
`/v1/keys`	GET 查询、POST 创建；DELETE `/v1/keys/{id}` 撤销。仅账号令牌（设备或个人手动令牌）可管理密钥，API Key 不具备此权限
`POST /v1/topups`	请求为 `{ "amount_usd": 10 \| 20 \| 50 }`，需幂等键。返回订单 `id`、支付 `url`、`amount_usd`、`credits`、`status`
`GET /v1/topups/{id}`	查询自己的订单。创建订单或打开支付页不代表积分已到账；确认支付到账后才算充值完成

充值入口已开放。503 表示服务暂时不可用；显示实际原因并保留订单上下文。请求只发送一次；网络中断时保留上下文，手动重发同一订单必须沿用原幂等键。

报错

报错的格式都一样。code 是固定的英文标识，用来在代码里判断；message 写明了原因和怎么改。

400

{
  "error": {
    "code": "invalid_request",
    "message": "text 和 items 需要提供其中一个，不能同时提供",
    "param": "items"
  },
  "request_id": "req_c77fa31ec3e97739"
}

状态码	code	怎么处理
400	`invalid_request`	参数缺失或不合法。message 写明了哪里不对，param 是出错的参数名，改完再发。
401	`unauthorized`	令牌没带、写错了或已经撤销。请求头要写成 Authorization: Bearer <令牌>。
402	`insufficient_credits`	积分不够付这次调用。message 里写了至少需要多少、还剩多少。不要重试。
404	`not_found`	没有这个接口，检查路径。
409	`conflict`	同一操作正在处理，或幂等键与请求不匹配。保留原键与请求体，不另发一项操作。
429	`rate_limited`	已达到调用限额。按 Retry-After 等待，保留操作上下文。
502	`upstream_error`	上游返回不可用。用户决定重试时沿用同一幂等键和请求体。
503	`unavailable`	服务暂时不可用。显示实际原因，保留文案，不循环重试。
504	`timeout`	请求超时。若要重发同一操作，沿用原幂等键和请求体。

计费

按 Gemini 3.8 Flash 的实际 Token 用量计费，价格为 ZenMux 同期价格加 10%。$1 = 100 积分，精度为 0.001 积分。每百万 Token：普通输入 82.5 积分、缓存输入 8.25 积分、输出（包含思考 Token）412.5 积分。缓存 Token 已包含在输入中，不重复计费；各项合计后向上取到 0.001 积分。当前促销费率在 2027 年前有效，后续价格会另行公布。

请求先预留积分，成功后按实际用量结算，释放未使用部分；调用失败释放预留，不扣积分。新账号没有赠送积分。充值仅支持 $10、$20、$50，分别到账 1000、2000、5000 积分，无赠送。充值入口已开放；成功创建订单后由用户完成付款，不能把订单创建或浏览器跳转当作积分已到账。503 表示服务暂时不可用，保留订单上下文并显示实际原因。

接口描述文件：/v1/openapi.json（OpenAPI 3.1）。