# KazTool Agent API Quickstart

Muse users: [Public installation package and personal-account onboarding](https://www.kaztool.cn/agent/muse). Each user supplies their own securely stored credential and consumes their own allowance; registration does not automatically activate API access.

Updated: 2026-10-11. Public API contract: OpenAPI 1.2.0. Account provisioning, billing and conversion-engine identity are separate; always read the live contract and your own account's usage receipt.

Use KazTool when a user explicitly asks to convert Kazakh text between Cyrillic (`kk-Cyrl`) and Arabic/Tote (`kk-Arab`). This is writing-system conversion, not translation, language detection, grammar checking, or proofreading.

## Access

Sign in to the [KazTool connection center](https://www.kaztool.cn/agent) with your own account. API access requires an enabled API account explicitly bound to that login. If it is not enabled, use [API support](https://www.kaztool.cn/agent/support) to request manual activation with the account identifier shown in the connection center. Website membership and API character credits are separate. There is no anonymous API access or automatic API-account activation; do not share another user's key or quota.

For a program using REST, create a developer API key in the connection center. The full key is shown only once, expires after 30 days, and can be revoked there. Store it in a server-side secret manager or environment variable. Never put it in browser JavaScript, a URL, source control, logs, screenshots, or a prompt.

For a remote-MCP client, configure `https://api.kaztool.cn/mcp`. Use the client's supported OAuth authorization flow, or configure your own API key as a Bearer credential in its secure connection settings if that client supports this mode. The service publishes protected-resource metadata at `https://api.kaztool.cn/.well-known/oauth-protected-resource/mcp` and authorization-server metadata at `https://www.kaztool.cn/.well-known/oauth-authorization-server`. MCP/OAuth support varies by client; a working endpoint does not mean KazTool is preinstalled or listed in that client's marketplace. [Muse setup and acceptance](https://www.kaztool.cn/agent/muse.md) explains the same endpoints and account boundaries in Chinese.

## Tools and REST operations

| MCP tool | REST operation | Arguments |
| --- | --- | --- |
| `convert_kazakh_script` | `POST /v1/convert` | `text`, `source_script`, `target_script` |
| `batch_convert_kazakh_script` | `POST /v1/batch-convert` | `items`: 1–20 conversion objects, returned in the same order |
| `detect_kazakh_script` | `POST /v1/detect` | `text`; detects writing systems, not language or grammar |
| `get_kaztool_usage` | `GET /v1/usage` | MCP `{}`; REST GET has no JSON body |

An API key or OAuth connection identifies the account. Do not send an account ID or algorithm version in conversion parameters. The same account's keys and connections share its allowance.

## REST conversion

The complete, current contract is [`/openapi.json`](https://api.kaztool.cn/openapi.json). This example uses an existing provisioned key held by your server process:

```bash
export KAZTOOL_API_KEY='replace-with-a-key-from-your-secret-manager'

curl --fail-with-body --silent --show-error \
  https://api.kaztool.cn/v1/convert \
  -H "Authorization: Bearer ${KAZTOOL_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: replace-with-a-stable-random-key' \
  --data '{
    "text": "бірақ",
    "source_script": "kk-Cyrl",
    "target_script": "kk-Arab"
  }'
```

Use a new unpredictable idempotency key per logical conversion. For a safe retry of the exact same REST request, reuse its original key; do not reuse it with changed text or a changed engine version. Successful REST idempotency records are retained for 24 hours. An MCP tool call is a new call and is not automatically deduplicated.

A successful conversion response includes `converted_text`, `source_script`, `target_script`, `detected_script`, `characters`, `algorithm_version`, `warnings`, `request_id`, and a `usage` receipt. Display the returned text and preserve the warnings. Do not invent a confidence score or claim linguistic validation from a successful HTTP response.

For this owner-confirmed example, `converted_text` must be `ءبىراق`, beginning with U+0621. Reverse conversion returns `Бірақ` under the existing sentence-initial capitalization behavior. As verified on 2026-10-11, the independent API's engine identity is `sha256:704c442e46c90b1775ce36bf5a5dfb1762210d4fc45fe58f67c84a25c49229de`. This release includes the ten explicitly approved complete word forms; it does not infer new suffixes or certify every word. Future engine releases can have a different hash: compare the live `/v1/usage` identity with the conversion receipt and check release notes rather than silently discarding or rewriting output.

## Limits and usage

- One text: at most 20,000 Unicode code points, including spaces, punctuation, and line breaks.
- Batch: 1–20 items and at most 100,000 input code points total.
- A source script clearly inconsistent with the supplied `source_script` returns `422 SCRIPT_MISMATCH`. Mixed-script text is allowed and may return warnings.
- Successful conversion and batch calls consume the account's assigned character allowance. Detection consumes no character allowance, but it uses a request-rate slot. Failed requests do not consume character allowance; rate limits still apply.
- The current prepaid service reports `billing_enabled: true` and `plan: prepaid_characters`. Successful conversions use available trial characters first, then purchased character credits; no separate per-call payment is collected. A successful call can consume characters even when its input is entirely unmapped and its output is unchanged. Count all input code points, not just Kazakh letters or output length.
- `GET https://api.kaztool.cn/v1/usage` requires the `usage` scope and consumes no characters. Its flat response includes UTC-month counters, total `characters_remaining`, `trial_characters_remaining`, `paid_characters_remaining`, and `algorithm_version`. It has no `request_id` or nested `usage`. Trial eligibility and limits are account-managed; do not promise an automatic free grant to new users.
- Non-replayed conversion receipts include `usage.consumed_characters`, `usage.trial_characters`, and `usage.paid_characters`. An eligible REST replay reports zero consumption and `replayed: true`; its receipt has no trial/paid split. Detection consumes zero characters, while detection and usage queries still occupy rate-limit slots. `successful_requests` counts non-replayed conversion/detection/batch calls, not usage queries or each batch item.

## Character credits

Enabled, bound API accounts can purchase credits on the separate [KazTool API credits page](https://www.kaztool.cn/agent/credits). The package verified on 2026-10-11 is CNY 19.90 for 1,000,000 input characters, valid for 365 days after successful payment; it is a one-time purchase without automatic renewal. Confirm the current server-side offer and [service terms](https://www.kaztool.cn/agent/credits/terms) before payment. Purchased credits expire independently of the UTC monthly trial period; expired, refunded or frozen lots cannot be consumed. Contact [support](https://www.kaztool.cn/agent/support) for account activation or payment issues.

Website VIP does not supply API credits. Each customer's own account pays for its own consumption. This REST documentation describes the independent service; ChatGPT tools use existing account allowance and do not sell credits or provide checkout links inside their tool workflow.

Common error codes include `AUTHENTICATION_REQUIRED`, `INSUFFICIENT_SCOPE`, `SCRIPT_MISMATCH`, `TEXT_TOO_LARGE`, `BATCH_TOO_LARGE`, `RATE_LIMITED`, `QUOTA_EXCEEDED`, `IDEMPOTENCY_CONFLICT`, and `SERVICE_UNAVAILABLE`. See the OpenAPI contract for the full list and schemas.

## Privacy and trust

The API processes submitted text on KazTool servers and does not persist the source or converted text. It records account/key metadata, operation, character counts, time, engine version, and a keyed fingerprint for safe REST idempotency; it does not store raw API keys or conversion content. Your own application remains responsible for consent, transport security, access control, and any copies it keeps.

The detector identifies writing-system characters; it does not establish that text is Kazakh or validate spelling/grammar. Keep the API's `warnings` and `algorithm_version` with the result. KazTool's conversion rules have known linguistic review gaps; do not represent the service as 100% accurate or suitable for unsupervised publication without human review.

## Next steps

1. Check that your API account is enabled and note its current trial and prepaid allowance in the connection center or `/v1/usage`.
2. Connect one backend integration or one MCP client, then test a short, non-sensitive sample in each supported direction.
3. Compare output with a user-confirmed reference before using it in public or high-impact content.
4. Review aggregate usage and errors before inviting additional users. Do not send raw customer text to analytics or support logs.

API provisioning remains manual. Purchase, installation, authentication and a successful conversion are separate steps: verify an actual `request_id`, engine identity and the character-consumption receipt before declaring an integration working. A public endpoint or an MCP SDK test does not prove a Muse client has connected or that a plugin has been publicly listed.

## ChatGPT personal-account setup

For ChatGPT OAuth, use the [Chinese guide](https://www.kaztool.cn/agent/chatgpt) or [English guide](https://www.kaztool.cn/agent/chatgpt/en). Do not create or paste a developer API key for ChatGPT. Each connection uses the signed-in KazTool account and its existing allowance. Current account activation is manual; website membership and ChatGPT subscriptions are separate from API characters. An accessible guide does not prove directory approval or publication.