降 AI API：快速接入与接口说明

1. 使用规则

API 使用网页账号的同一能力和积分账户：

• 基础降 AI 每开始一个 3000 字计费单位消耗 1 积分；高级降 AI消耗 2 积分。
• 计费单位按输入字符数向上取整；服务端重新报价，不信任调用方传入的字数或金额。
• 继续使用网页账号的订阅、降 AI 开关、高级权限、积分批次、消费流水和失败退款。
• 用户只能选择 basic / advanced 和公开的强度档，不能指定模型、供应商或模型凭证。
• 每次请求独立处理，不保留上下文。

1.1 快速启动：同步改写

先在网页登录“个人设置 → API 接口”创建 Key；完整 Key 只显示一次，请保存在服务端环境变量中， 不要写进前端、Git、URL 或日志。

下面这段命令复制后只需替换 Key，即可完成第一次改写：

export BANXING_API_KEY="bx_live_替换成你创建的完整Key"

curl --fail-with-body https://banxing.cc/v1/rewrites \
  -X POST \
  -H "Authorization: Bearer $BANXING_API_KEY" \
  -H "Idempotency-Key: order-demo-20260831-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "basic",
    "text": "请把这段文字改得更自然，但不要改变原意。",
    "strength": 1
  }'

成功时只需读取 data.rewritten_text：

{
  "success": true,
  "data": {
    "id": "run_123",
    "mode": "basic",
    "status": "succeeded",
    "rewritten_text": "改写后的正文……",
    "billing": { "charged_points": 1 }
  },
  "error": null
}

mode 使用 basic 即可开始；需要更强处理时改为 advanced。strength 可选，基础模式支持 1/2/3，高级模式支持 0/1/2/3。每个业务订单都应生成新的 Idempotency-Key；网络超时重试 时必须复用原 Key，这样不会重复扣费。默认同步等待模型完成，通常几秒到几十秒。

不希望长时间保持 HTTP 连接时，使用异步改写。

需要在扣费前展示预计消耗时，可调用 POST /v1/rewrite-quotes。执行响应中的 data.billing 是最终计费依据。

2. API Key 管理

API Key 格式为 bx_live_<43 个 base64url 字符>，创建响应只展示一次完整值。

网页 JWT 用于管理 Key：

创建

POST /api/api-keys
Authorization: Bearer <网页 access token>
Content-Type: application/json

{
  "name": "生产工作流",
  "scopes": ["rewrite:basic", "rewrite:advanced", "credits:read"],
  "expiresInDays": 365
}

每个账号最多保留 5 个未撤销、未过期的 Key。支持的 scope：

查询和撤销

GET /api/api-keys
DELETE /api/api-keys/{id}
Authorization: Bearer <网页 access token>

API Key 只能通过 Authorization: Bearer bx_live_... 发送，禁止放在 URL、请求正文或日志中。

3. 接口说明

接口地址：https://banxing.cc/v1

所有响应遵守统一契约：

{"success":true,"data":{},"error":null}

失败响应保持 error 为字符串，机器使用的错误码放在 data.code。

3.1 报价（可选）

POST /v1/rewrite-quotes
Authorization: Bearer bx_live_xxx
Content-Type: application/json

{
  "mode": "advanced",
  "text": "需要处理的正文",
  "strength": 1
}

响应示例：

{
  "success": true,
  "data": {
    "mode": "advanced",
    "input_chars": 4200,
    "billing_units": 2,
    "points_per_unit": 2,
    "required_points": 4,
    "balance": 35,
    "unlimited": false
  },
  "error": null
}

报价不扣积分。最终扣费仍以执行时的服务端计算为准。

计费单位按输入字符数向上取整（不是 token 数）：

空文本不执行；超过 30000 字会返回参数错误。特殊字符的长度以接口返回的 input_chars 和 required_points 为准。

3.2 降 AI 改写

POST /v1/rewrites
Authorization: Bearer bx_live_xxx
Idempotency-Key: customer-order-20260831-001
Content-Type: application/json

{
  "mode": "advanced",
  "text": "需要处理的正文",
  "strength": 1
}

mode=basic 支持强度 1/2/3；mode=advanced 支持 0/1/2/3。请求正文最多 30000 字。

成功响应：

{
  "success": true,
  "data": {
    "id": "run_123",
    "mode": "advanced",
    "status": "succeeded",
    "rewritten_text": "改写结果",
    "engine": "studio-advanced",
    "billing": {
      "input_chars": 4200,
      "billing_units": 2,
      "points_per_unit": 2,
      "charged_points": 4,
      "reference_id": "api:..."
    }
  },
  "error": null
}

有非空正文但上游标记质量降级时，status=degraded，正文照常返回且不退款。模型失败、空输出 或运行记录创建失败时，接口返回失败并调用现有幂等退款逻辑。

可直接运行的 Python（requests）示例：

import os
import uuid
import requests

base_url = os.environ["BASE_URL"]
api_key = os.environ["BANXING_API_KEY"]
payload = {
    "mode": "basic",
    "text": "这是一段需要降低 AI 痕迹的示例文本，请保持事实和段落结构不变。",
    "strength": 1,
}
headers = {
    "Authorization": f"Bearer {api_key}",
    "Idempotency-Key": f"python-{uuid.uuid4()}",
    "Content-Type": "application/json",
}
response = requests.post(f"{base_url}/v1/rewrites", json=payload,
                         headers=headers, timeout=300)
body = response.json()
if not response.ok or not body.get("success"):
    raise RuntimeError(f"HTTP {response.status_code}: {body.get('data', {}).get('code')} {body.get('error')}")
print(body["data"]["rewritten_text"])
print("charged:", body["data"]["billing"]["charged_points"])

可直接运行的 Node.js 18+ 示例（使用原生 fetch）：

const baseUrl = process.env.BASE_URL;
const apiKey = process.env.BANXING_API_KEY;
const response = await fetch(`${baseUrl}/v1/rewrites`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Idempotency-Key": `node-${crypto.randomUUID()}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ mode: "advanced", strength: 1,
    text: "请改写这段示例内容，保持原意并减少机械表达。" }),
});
const body = await response.json();
if (!response.ok || !body.success) throw new Error(`${response.status}: ${body.error}`);
console.log(body.data.rewritten_text, body.data.billing.charged_points);

n8n / Make 等自动化平台可使用同一 HTTP Request 节点：方法 POST，URL ${BASE_URL}/v1/rewrites，Header 为 Authorization: Bearer {{BANXING_API_KEY}}、 Idempotency-Key: {{$execution.id}}-{{$itemIndex}} 和 Content-Type: application/json， Body 选择 JSON 并传入 mode、text、strength。不要把 Key 放入共享工作流的公开输出。

3.3 异步降 AI 改写

创建任务：

curl --fail-with-body https://banxing.cc/v1/rewrite-jobs \
  -X POST \
  -H "Authorization: Bearer $BANXING_API_KEY" \
  -H "Idempotency-Key: order-20260831-0002" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "basic",
    "text": "需要处理的正文",
    "strength": 1
  }'

接口返回 202 Accepted：

{
  "success": true,
  "data": {
    "id": "job_550e8400e29b41d4a716446655440000",
    "mode": "basic",
    "status": "queued",
    "rewritten_text": null,
    "billing": null,
    "job_error": null,
    "created_at": "2026-08-31T10:00:00.000Z",
    "started_at": null,
    "completed_at": null,
    "urls": {
      "get": "/v1/rewrite-jobs/job_550e8400e29b41d4a716446655440000",
      "cancel": "/v1/rewrite-jobs/job_550e8400e29b41d4a716446655440000/cancel"
    }
  },
  "error": null
}

每隔 2～5 秒调用 GET /v1/rewrite-jobs/{id} 查询任务：

curl --fail-with-body \
  -H "Authorization: Bearer $BANXING_API_KEY" \
  https://banxing.cc/v1/rewrite-jobs/job_550e8400e29b41d4a716446655440000

状态为 succeeded 或 degraded 时，从 data.rewritten_text 读取改写结果。状态变化如下：

调用 POST /v1/rewrite-jobs/{id}/cancel 取消任务：

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer $BANXING_API_KEY" \
  https://banxing.cc/v1/rewrite-jobs/job_550e8400e29b41d4a716446655440000/cancel

已经完成的任务不会被取消。创建任务发生网络超时时，使用相同请求正文和 Idempotency-Key 重试；接口会返回同一个任务，不会重复创建或扣费。

每个 Key 最多同时保留 5 个、每个账号最多同时保留 20 个 queued 或 running 任务。 达到上限时返回 429 TOO_MANY_PENDING_JOBS；已有任务完成或取消后即可继续创建。任务及 改写结果保留 30 天，调用方应在任务完成后及时保存 rewritten_text。

Python 轮询示例：

import os
import time
import uuid
import requests

base_url = "https://banxing.cc"
headers = {
    "Authorization": f"Bearer {os.environ['BANXING_API_KEY']}",
    "Idempotency-Key": str(uuid.uuid4()),
}
created = requests.post(
    f"{base_url}/v1/rewrite-jobs",
    headers=headers,
    json={"mode": "basic", "text": "需要处理的正文", "strength": 1},
    timeout=30,
)
created.raise_for_status()
job = created.json()["data"]

while job["status"] in {"queued", "running"}:
    time.sleep(3)
    response = requests.get(
        f"{base_url}{job['urls']['get']}",
        headers={"Authorization": headers["Authorization"]},
        timeout=30,
    )
    response.raise_for_status()
    job = response.json()["data"]

if job["status"] not in {"succeeded", "degraded"}:
    raise RuntimeError(job["job_error"] or job["status"])
print(job["rewritten_text"])

3.4 幂等规则

执行接口必须提供 8～128 字符的 Idempotency-Key：

• 同一 API Key、同一幂等键、同一标准化请求：返回首次保存的响应，并带 Idempotent-Replayed: true。
• 同一幂等键用于不同请求：409 IDEMPOTENCY_CONFLICT。
• 首次请求仍在执行：409 IDEMPOTENCY_IN_PROGRESS。
• 权限或积分不足等执行前错误不固化幂等记录，修正账号状态后可用原键重试。
• 已进入模型执行的失败会退款并保存失败响应，重试不会再次调用模型或重复扣费。

重试决策：

3.5 余额和流水

GET /v1/credits
GET /v1/credit-ledger?page=1&limit=20
Authorization: Bearer bx_live_xxx

两者要求 credits:read。流水直接读取现有 credit_ledger，不会建立 API 专用余额。

3.6 接入步骤

1. 开通降 AI 并准备积分。
2. 在“个人设置 → API 接口”创建 Key，并保存在服务端。
3. 为每个业务订单生成唯一的 Idempotency-Key，调用 POST /v1/rewrites。
4. 从 data.rewritten_text 读取结果，从 data.billing 记录实际扣费。

4. 错误码

4.1 错误响应实例

所有错误都保持同一外层结构，客户端应优先判断 HTTP 状态和 data.code，不要依赖中文错误文本：

// 401：Key 无效、过期或已撤销
{
  "success": false,
  "data": { "code": "API_KEY_INVALID" },
  "error": "Invalid API key"
}

// 429：执行槽位已满；本次没有扣积分
{
  "success": false,
  "data": { "code": "PUBLIC_API_CONCURRENCY_LIMIT" },
  "error": "Public API concurrency limit reached"
}

// 502：已进入模型执行但上游失败；服务端已退款并固化失败结果
{
  "success": false,
  "data": { "code": "DEAI_UPSTREAM_FAILED", "id": "run_123" },
  "error": "DeAI upstream execution failed"
}

限流或并发拒绝时请读取 Retry-After。如需排查单次请求，请提供响应中的 data.id、 billing.reference_id（若有）及发生时间。

公开接口默认每个 Key 每分钟 30 次、每个来源 IP 每分钟 120 次。基础和高级改写分别有并发上限，达到上限时返回 429 PUBLIC_API_CONCURRENCY_LIMIT 和 Retry-After，请求不会扣积分；客户端按响应头等待后 使用原 Idempotency-Key 重试。

5. 安全

• API Key 只放在服务端的 Authorization: Bearer Header，不要放入浏览器代码、URL 或日志。
• 完整 Key 只在创建时显示一次；泄露后立即在网页端撤销并重新创建。
• 不要把用户正文写入公开日志；对账时使用响应中的 id 和 billing.reference_id。
• API 用户不能上传或切换模型凭证。