Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 0 additions & 62 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -248,68 +248,6 @@ Successful calls return `{"data": {...}}`. Errors return `{"error":{"code":"..."

`name` is always the Tool ID with dots replaced by underscores, which is exactly the MCP Tool name. Prices, provider names, provider URLs, and credentials are never part of a response.

## Contracts and limits

These rules apply identically to REST and MCP, because both protocols run through the same Executor.

### Authorization

An API key uses one of two access modes:

| Mode | Behavior |
|---|---|
| `all` | May call every business Tool |
| `restricted` | May call only the business Tools explicitly granted to the key |

Three Tools behave differently:

- `account.quota`, `usage.summary`, and `usage.history` are available to every authenticated key regardless of mode, and never consume balance or write a usage record.
- `document.result.get` cannot be granted on its own. A key reaches it only by holding `document.parsing` access, and each parsed document is readable only by the key that created it.

### Error codes

Business failures return a stable code. REST puts it in `error.code`; MCP sets `isError: true` and puts it in `structuredContent.code`. These are the only codes the service emits — any other internal condition is reported as `UPSTREAM_INVALID_RESPONSE`.

| Code | HTTP | Meaning |
|---|---:|---|
| `UNAUTHORIZED` | 401 | Missing, malformed, revoked, or expired API key |
| `TOOL_FORBIDDEN` | 403 | The key is authenticated but not entitled to this Tool |
| `TOOL_NOT_FOUND` | 404 | Unknown Tool ID, or the Tool is disabled at runtime |
| `DOCUMENT_RESULT_NOT_FOUND` | 404 | No parsed document with that ID exists for this key |
| `INVALID_ARGUMENTS` | 400 | Arguments failed schema or input validation |
| `LANGUAGE_UNAVAILABLE` | 400 | The requested subtitle or caption language is not available |
| `INSUFFICIENT_BALANCE` | 402 | Account balance or key spend limit cannot cover the call |
| `IDEMPOTENCY_CONFLICT` | 409 | The idempotency key was already used with different arguments |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | An identical request with the same idempotency key is still running |
| `TRANSCRIPT_UNAVAILABLE` | 422 | No usable existing caption track was found |
| `UPSTREAM_INVALID_RESPONSE` | 502 | The capability could not be completed |
| `UPSTREAM_TIMEOUT` | 504 | The capability did not complete in time |

Error messages are generic by design. Branch on `code`, never on `message`.

### Idempotency

REST reads `Idempotency-Key`; MCP reads `X-Idempotency-Key`. A key is retained for 24 hours and is scoped to the exact arguments it was first used with. Replaying a completed request returns the original result without charging again. Reusing a key with different arguments returns `IDEMPOTENCY_CONFLICT`.

### Request limits

| Protocol | Maximum request body | On exceed |
|---|---|---|
| REST | 2 MiB | `400 INVALID_ARGUMENTS` |
| MCP | 1 MiB | `413` with an empty body |

### Billing model

Failed, rejected, timed-out, and unauthorized calls are never charged. Most Tools are charged once per successful call. Three Tools are metered by consumed units and are charged for actual usage after the call succeeds:

| Tool | Billing unit | Cap per call |
|---|---|---|
| `document.parsing` | Page | 100 pages |
| `humanizer.text` | 1,000 words, rounded up | 20 units |
| `tiktok.audio_to_transcript` | Started minute | 10 minutes |

`document.result.get` is free and writes a zero-amount usage record. Account and usage Tools are free and write no usage record. Current unit prices are provided with your API key.

## Contributing

- [Contributing guide](CONTRIBUTING.md)
Expand Down
62 changes: 0 additions & 62 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -248,68 +248,6 @@ REST 包含一个发现 endpoint 和 23 个具体 Tool 调用 endpoint。使用

`name` 恒为 Tool ID 将点号替换为下划线的结果,也就是对应的 MCP Tool 名。价格、Provider 名称、Provider URL 和凭据不会出现在任何响应中。

## 合同与限制

以下规则对 REST 和 MCP 完全一致,因为两种协议共享同一个 Executor。

### 授权

API Key 使用两种访问模式之一:

| 模式 | 行为 |
|---|---|
| `all` | 可调用所有业务 Tool |
| `restricted` | 只能调用显式授予该 Key 的业务 Tool |

三个 Tool 的行为不同:

- `account.quota`、`usage.summary`、`usage.history` 对任何已认证 Key 均可用(与访问模式无关),不消耗余额,也不写 Usage 记录。
- `document.result.get` 不能单独授权。Key 只有在拥有 `document.parsing` 权限时才能访问它,且每份解析结果只对创建它的 Key 可见。

### 错误码

业务失败返回稳定的错误码。REST 放在 `error.code`,MCP 设置 `isError: true` 并放在 `structuredContent.code`。服务只会返回下列错误码,其他内部情况统一归并为 `UPSTREAM_INVALID_RESPONSE`。

| 错误码 | HTTP | 含义 |
|---|---:|---|
| `UNAUTHORIZED` | 401 | API Key 缺失、格式错误、已吊销或已过期 |
| `TOOL_FORBIDDEN` | 403 | Key 已认证但无此 Tool 权限 |
| `TOOL_NOT_FOUND` | 404 | Tool ID 不存在,或该 Tool 运行时已停用 |
| `DOCUMENT_RESULT_NOT_FOUND` | 404 | 当前 Key 下不存在该 ID 的解析结果 |
| `INVALID_ARGUMENTS` | 400 | 参数未通过 Schema 或输入校验 |
| `LANGUAGE_UNAVAILABLE` | 400 | 请求的字幕语言不可用 |
| `INSUFFICIENT_BALANCE` | 402 | 账户余额或 Key 消费上限不足以覆盖本次调用 |
| `IDEMPOTENCY_CONFLICT` | 409 | 该幂等键已用于参数不同的请求 |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | 相同幂等键的请求仍在执行中 |
| `TRANSCRIPT_UNAVAILABLE` | 422 | 未找到可用的已有字幕轨道 |
| `UPSTREAM_INVALID_RESPONSE` | 502 | 能力调用未能完成 |
| `UPSTREAM_TIMEOUT` | 504 | 能力调用超时 |

错误 `message` 有意保持通用。请基于 `code` 分支处理,不要解析 `message`。

### 幂等

REST 读取 `Idempotency-Key`,MCP 读取 `X-Idempotency-Key`。幂等键保留 24 小时,并与首次使用时的参数严格绑定。重放已完成的请求会返回原始结果且不重复计费;用相同键提交不同参数会返回 `IDEMPOTENCY_CONFLICT`。

### 请求限制

| 协议 | 请求体上限 | 超限响应 |
|---|---|---|
| REST | 2 MiB | `400 INVALID_ARGUMENTS` |
| MCP | 1 MiB | `413`,空响应体 |

### 计费模型

失败、被拒绝、超时和鉴权失败的调用一律不收费。多数 Tool 按成功调用计费一次。以下三个 Tool 按实际消耗单位计量,在调用成功后按实际用量结算:

| Tool | 计费单位 | 单次上限 |
|---|---|---|
| `document.parsing` | 页 | 100 页 |
| `humanizer.text` | 每 1,000 words,向上取整 | 20 个单位 |
| `tiktok.audio_to_transcript` | 起始分钟 | 10 分钟 |

`document.result.get` 免费,但写入零金额 Usage 记录。account 和 usage 类 Tool 免费且不写 Usage 记录。具体单位价格随 API Key 一并提供。

## 贡献

- [贡献指南](CONTRIBUTING.md)
Expand Down
Loading