{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"KazTool Agent API","version":"1.2.0","description":"Kazakh Cyrillic ↔ Arabic/Tote script conversion. Script detection is not language identification. No translation, OCR, document-layout or spelling claims. Trial-first prepaid character metering; no automatic renewal or per-call monetary charge. Successful conversion input code points, including whitespace, consume allowance. Detection consumes zero characters from version 1.1.0. Existing historical usage is retained. An old detection idempotency key from the previous policy returns 409 during its 24-hour retention window; conversion replay semantics remain unchanged."},"servers":[{"url":"https://api.kaztool.cn"}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"KazTool API key"}},"schemas":{"ConvertRequest":{"type":"object","additionalProperties":false,"required":["text","source_script","target_script"],"properties":{"text":{"type":"string","maxLength":20000,"description":"Input Unicode code points, including whitespace, newlines and unsupported-script characters. An emoji code point counts once; grapheme clusters may contain multiple code points. Empty text is allowed. Unpaired UTF-16 surrogates are rejected. Text is processed on KazTool servers and is not persisted by this API."},"source_script":{"type":"string","enum":["kk-Cyrl","kk-Arab"]},"target_script":{"type":"string","enum":["kk-Cyrl","kk-Arab"],"description":"Must differ from source_script; this cross-field rule is checked by the service."}},"description":"Explicit Cyrillic ↔ Arabic/Tote script conversion, not language translation or proofreading. Source and target must differ. A clear detected source conflict returns 422; mixed and undetermined inputs remain allowed. The JSON Schema does not establish language identity or cross-field semantic consistency."},"DetectRequest":{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","maxLength":20000,"description":"Input Unicode code points, including whitespace, newlines and unsupported-script characters. An emoji code point counts once; grapheme clusters may contain multiple code points. Empty text is allowed. Unpaired UTF-16 surrogates are rejected. Text is processed on KazTool servers and is not persisted by this API."}}},"BatchConvertRequest":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["text","source_script","target_script"],"properties":{"text":{"type":"string","maxLength":20000,"description":"Input Unicode code points, including whitespace, newlines and unsupported-script characters. An emoji code point counts once; grapheme clusters may contain multiple code points. Empty text is allowed. Unpaired UTF-16 surrogates are rejected. Text is processed on KazTool servers and is not persisted by this API."},"source_script":{"type":"string","enum":["kk-Cyrl","kk-Arab"]},"target_script":{"type":"string","enum":["kk-Cyrl","kk-Arab"],"description":"Must differ from source_script; this cross-field rule is checked by the service."}},"description":"Explicit Cyrillic ↔ Arabic/Tote script conversion, not language translation or proofreading. Source and target must differ. A clear detected source conflict returns 422; mixed and undetermined inputs remain allowed. The JSON Schema does not establish language identity or cross-field semantic consistency."}}},"description":"The sum of all input Unicode code points must not exceed 100000; this aggregate limit is enforced by the service. Each input retains its own explicit source/target direction."},"SingleOperationUsage":{"description":"Successful input code points consumed from the enabled account allowance. No per-call monetary charge. Replays use the original request ID, recompute the same pinned engine output, and consume zero characters.","oneOf":[{"type":"object","additionalProperties":false,"required":["consumed_characters","billing_enabled","plan","paid_characters","trial_characters","replayed","period_start"],"properties":{"consumed_characters":{"type":"integer","minimum":0,"maximum":20000},"billing_enabled":{"type":"boolean","const":true},"plan":{"type":"string","const":"prepaid_characters"},"paid_characters":{"type":"integer","minimum":0,"maximum":20000},"trial_characters":{"type":"integer","minimum":0,"maximum":20000},"replayed":{"type":"boolean","const":false},"period_start":{"type":"string","format":"date-time","pattern":"Z$","description":"UTC timestamp."}}},{"type":"object","additionalProperties":false,"required":["consumed_characters","billing_enabled","plan","replayed","original_period_start"],"properties":{"consumed_characters":{"type":"integer","const":0},"billing_enabled":{"type":"boolean","const":true},"plan":{"type":"string","const":"prepaid_characters"},"replayed":{"type":"boolean","const":true},"original_period_start":{"type":"string","format":"date-time","pattern":"Z$","description":"UTC timestamp."}}}]},"DetectionUsage":{"description":"Successful input code points consumed from the enabled account allowance. No per-call monetary charge. Replays use the original request ID, recompute the same pinned engine output, and consume zero characters.","oneOf":[{"type":"object","additionalProperties":false,"required":["consumed_characters","billing_enabled","plan","paid_characters","trial_characters","replayed","period_start"],"properties":{"consumed_characters":{"type":"integer","minimum":0,"maximum":0},"billing_enabled":{"type":"boolean","const":true},"plan":{"type":"string","const":"prepaid_characters"},"paid_characters":{"type":"integer","minimum":0,"maximum":0},"trial_characters":{"type":"integer","minimum":0,"maximum":0},"replayed":{"type":"boolean","const":false},"period_start":{"type":"string","format":"date-time","pattern":"Z$","description":"UTC timestamp."}}},{"type":"object","additionalProperties":false,"required":["consumed_characters","billing_enabled","plan","replayed","original_period_start"],"properties":{"consumed_characters":{"type":"integer","const":0},"billing_enabled":{"type":"boolean","const":true},"plan":{"type":"string","const":"prepaid_characters"},"replayed":{"type":"boolean","const":true},"original_period_start":{"type":"string","format":"date-time","pattern":"Z$","description":"UTC timestamp."}}}]},"BatchOperationUsage":{"description":"Successful input code points consumed from the enabled account allowance. No per-call monetary charge. Replays use the original request ID, recompute the same pinned engine output, and consume zero characters.","oneOf":[{"type":"object","additionalProperties":false,"required":["consumed_characters","billing_enabled","plan","paid_characters","trial_characters","replayed","period_start"],"properties":{"consumed_characters":{"type":"integer","minimum":0,"maximum":100000},"billing_enabled":{"type":"boolean","const":true},"plan":{"type":"string","const":"prepaid_characters"},"paid_characters":{"type":"integer","minimum":0,"maximum":100000},"trial_characters":{"type":"integer","minimum":0,"maximum":100000},"replayed":{"type":"boolean","const":false},"period_start":{"type":"string","format":"date-time","pattern":"Z$","description":"UTC timestamp."}}},{"type":"object","additionalProperties":false,"required":["consumed_characters","billing_enabled","plan","replayed","original_period_start"],"properties":{"consumed_characters":{"type":"integer","const":0},"billing_enabled":{"type":"boolean","const":true},"plan":{"type":"string","const":"prepaid_characters"},"replayed":{"type":"boolean","const":true},"original_period_start":{"type":"string","format":"date-time","pattern":"Z$","description":"UTC timestamp."}}}]},"ConversionResult":{"type":"object","additionalProperties":false,"required":["converted_text","source_script","target_script","detected_script","characters","algorithm_version","warnings"],"properties":{"converted_text":{"type":"string","description":"Converted output; its length can differ from input and does not determine consumed characters."},"source_script":{"type":"string","enum":["kk-Cyrl","kk-Arab"]},"target_script":{"type":"string","enum":["kk-Cyrl","kk-Arab"],"description":"Different from source_script. Direction is validated by the service, not by comparing JSON Schema fields."},"detected_script":{"type":"string","enum":["kk-Cyrl","kk-Arab","mixed","undetermined"]},"characters":{"type":"integer","minimum":0,"maximum":20000,"description":"Input Unicode code points, including whitespace."},"algorithm_version":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$","description":"SHA-256 identity of the pinned private engine artifact actually used."},"warnings":{"type":"array","minItems":2,"uniqueItems":true,"items":{"type":"string","enum":["SCRIPT_DETECTION_IS_NOT_LANGUAGE_VERIFICATION","MIXED_SCRIPTS","NO_SUPPORTED_SCRIPT_LETTERS","SCRIPT_CONVERSION_IS_NOT_TRANSLATION_OR_PROOFREADING"]},"allOf":[{"contains":{"const":"SCRIPT_DETECTION_IS_NOT_LANGUAGE_VERIFICATION"}},{"contains":{"const":"SCRIPT_CONVERSION_IS_NOT_TRANSLATION_OR_PROOFREADING"}}]}},"description":"One conversion result. Batch items have no separate request_id or usage fields; those belong to the batch."},"ConvertResponse":{"type":"object","additionalProperties":false,"required":["converted_text","source_script","target_script","detected_script","characters","algorithm_version","warnings","request_id","usage"],"properties":{"converted_text":{"type":"string","description":"Converted output; its length can differ from input and does not determine consumed characters."},"source_script":{"type":"string","enum":["kk-Cyrl","kk-Arab"]},"target_script":{"type":"string","enum":["kk-Cyrl","kk-Arab"],"description":"Different from source_script. Direction is validated by the service, not by comparing JSON Schema fields."},"detected_script":{"type":"string","enum":["kk-Cyrl","kk-Arab","mixed","undetermined"]},"characters":{"type":"integer","minimum":0,"maximum":20000,"description":"Input Unicode code points, including whitespace."},"algorithm_version":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$","description":"SHA-256 identity of the pinned private engine artifact actually used."},"warnings":{"type":"array","minItems":2,"uniqueItems":true,"items":{"type":"string","enum":["SCRIPT_DETECTION_IS_NOT_LANGUAGE_VERIFICATION","MIXED_SCRIPTS","NO_SUPPORTED_SCRIPT_LETTERS","SCRIPT_CONVERSION_IS_NOT_TRANSLATION_OR_PROOFREADING"]},"allOf":[{"contains":{"const":"SCRIPT_DETECTION_IS_NOT_LANGUAGE_VERIFICATION"}},{"contains":{"const":"SCRIPT_CONVERSION_IS_NOT_TRANSLATION_OR_PROOFREADING"}}]},"request_id":{"type":"string","format":"uuid"},"usage":{"$ref":"#/components/schemas/SingleOperationUsage"}}},"DetectionResponse":{"type":"object","additionalProperties":false,"required":["script","characters","script_counts","warnings","algorithm_version","request_id","usage"],"properties":{"script":{"type":"string","enum":["kk-Cyrl","kk-Arab","mixed","undetermined"]},"characters":{"type":"integer","minimum":0,"maximum":20000},"script_counts":{"type":"object","additionalProperties":false,"required":["cyrillic","arabic"],"properties":{"cyrillic":{"type":"integer","minimum":0,"maximum":20000},"arabic":{"type":"integer","minimum":0,"maximum":20000}}},"warnings":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["SCRIPT_DETECTION_IS_NOT_LANGUAGE_VERIFICATION","MIXED_SCRIPTS","NO_SUPPORTED_SCRIPT_LETTERS"]},"contains":{"const":"SCRIPT_DETECTION_IS_NOT_LANGUAGE_VERIFICATION"}},"algorithm_version":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$","description":"SHA-256 identity of the pinned private engine artifact actually used."},"request_id":{"type":"string","format":"uuid"},"usage":{"$ref":"#/components/schemas/DetectionUsage"}}},"BatchConvertResponse":{"type":"object","additionalProperties":false,"required":["results","characters","algorithm_version","request_id","usage"],"properties":{"results":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/ConversionResult"},"description":"One result for every input, in the same order."},"characters":{"type":"integer","minimum":0,"maximum":100000,"description":"Sum of input Unicode code points across the whole batch, including whitespace."},"algorithm_version":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$","description":"SHA-256 identity of the pinned private engine artifact actually used."},"request_id":{"type":"string","format":"uuid"},"usage":{"$ref":"#/components/schemas/BatchOperationUsage"}}},"UsageResponse":{"type":"object","additionalProperties":false,"required":["period_start","period_end","character_limit","characters_used","characters_remaining","successful_requests","plan","billing_enabled","algorithm_version","trial_characters_remaining","paid_characters_remaining"],"properties":{"period_start":{"type":"string","format":"date-time","pattern":"Z$","description":"UTC timestamp."},"period_end":{"type":"string","format":"date-time","pattern":"Z$","description":"UTC timestamp."},"character_limit":{"type":"integer","minimum":0,"maximum":9007199254740991},"characters_used":{"type":"integer","minimum":0,"maximum":9007199254740991},"characters_remaining":{"type":"integer","minimum":0,"maximum":9007199254740991},"successful_requests":{"type":"integer","minimum":0,"maximum":9007199254740991},"plan":{"type":"string","const":"prepaid_characters"},"billing_enabled":{"type":"boolean","const":true},"algorithm_version":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$","description":"SHA-256 identity of the pinned private engine artifact actually used."},"trial_characters_remaining":{"type":"integer","minimum":0,"maximum":9007199254740991},"paid_characters_remaining":{"type":"integer","minimum":0,"maximum":9007199254740991}},"description":"Account totals for the UTC calendar month. successful_requests counts completed non-replay convert/detect/batch requests, not individual batch items or usage reads. Character counters measure Unicode code point allowance, not money. This response has no request_id or nested usage object."},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST","AUTHENTICATION_REQUIRED","INSUFFICIENT_SCOPE","ORIGIN_REJECTED","NOT_FOUND","METHOD_NOT_ALLOWED","IDEMPOTENCY_CONFLICT","TEXT_TOO_LARGE","BATCH_TOO_LARGE","CONTENT_TYPE_REJECTED","SCRIPT_MISMATCH","RATE_LIMITED","QUOTA_EXCEEDED","SERVICE_UNAVAILABLE"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}},"Error400":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}},"Error401":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTHENTICATION_REQUIRED"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}},"Error403":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["INSUFFICIENT_SCOPE","ORIGIN_REJECTED"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}},"Error404":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["NOT_FOUND"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}},"Error405":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["METHOD_NOT_ALLOWED"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}},"Error409":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["IDEMPOTENCY_CONFLICT"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}},"Error413":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["TEXT_TOO_LARGE","BATCH_TOO_LARGE"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}},"Error415":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["CONTENT_TYPE_REJECTED"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}},"Error422":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["SCRIPT_MISMATCH"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}},"Error429":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["RATE_LIMITED","QUOTA_EXCEEDED"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}},"Error503":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["SERVICE_UNAVAILABLE"]},"message":{"type":"string","minLength":1}}},"request_id":{"type":"string","format":"uuid"}}}}},"paths":{"/v1/convert":{"post":{"operationId":"convert_kazakh_script","description":"Convert 传统哈萨克文（阿拉伯字母／托特叶文） / төте жазу / Kazakh Arabic script and Cyrillic with the pinned KazTool engine and kk-CN convention. 历史搜索别名：新疆哈萨克文、托特文、老哈萨克文。 Explicit direction is required; this converts writing systems and does not translate languages or proofread.","security":[{"ApiKey":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"Optional REST replay protection for 24 hours, scoped to the account across its API keys. The same operation, input and pinned engine are required; otherwise 409. Replays still consume a rate-limit slot but do not consume more characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertRequest"}}}},"responses":{"200":{"description":"Successful result and character-consumption receipt. Detection consumes zero characters; conversion uses the account allowance. See usage for trial and prepaid consumption when enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertResponse"}}}},"400":{"description":"INVALID_REQUEST. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"AUTHENTICATION_REQUIRED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"INSUFFICIENT_SCOPE or ORIGIN_REJECTED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"NOT_FOUND. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"405":{"description":"METHOD_NOT_ALLOWED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error405"}}}},"409":{"description":"IDEMPOTENCY_CONFLICT. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error409"}}}},"413":{"description":"TEXT_TOO_LARGE or BATCH_TOO_LARGE. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error413"}}}},"415":{"description":"CONTENT_TYPE_REJECTED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error415"}}}},"422":{"description":"SCRIPT_MISMATCH. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error422"}}}},"429":{"description":"RATE_LIMITED or QUOTA_EXCEEDED. Safe error code and request_id; submitted text and credentials are not echoed.","headers":{"Retry-After":{"description":"Wait at least this many seconds before retrying. Exhausted character allowance requires available credits or an operator-managed allowance renewal.","schema":{"type":"integer","const":60}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error429"}}}},"503":{"description":"SERVICE_UNAVAILABLE. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error503"}}}}}}},"/v1/detect":{"post":{"operationId":"detect_kazakh_script","description":"Count Unicode Cyrillic and Arabic letters and identify their script. Does not consume character allowance; request-rate limits still apply. Convert directly when direction is known. Returns mixed or undetermined when appropriate. This is not Kazakh language verification, spelling validation, or a confidence estimate.","security":[{"ApiKey":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"Optional REST replay protection for 24 hours, scoped to the account across its API keys. The same operation, input and pinned engine are required; otherwise 409. Replays still consume a rate-limit slot but do not consume more characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectRequest"}}}},"responses":{"200":{"description":"Successful result and character-consumption receipt. Detection consumes zero characters; conversion uses the account allowance. See usage for trial and prepaid consumption when enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectionResponse"}}}},"400":{"description":"INVALID_REQUEST. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"AUTHENTICATION_REQUIRED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"INSUFFICIENT_SCOPE or ORIGIN_REJECTED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"NOT_FOUND. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"405":{"description":"METHOD_NOT_ALLOWED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error405"}}}},"409":{"description":"IDEMPOTENCY_CONFLICT. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error409"}}}},"413":{"description":"TEXT_TOO_LARGE or BATCH_TOO_LARGE. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error413"}}}},"415":{"description":"CONTENT_TYPE_REJECTED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error415"}}}},"429":{"description":"RATE_LIMITED or QUOTA_EXCEEDED. Safe error code and request_id; submitted text and credentials are not echoed.","headers":{"Retry-After":{"description":"Wait at least this many seconds before retrying. Exhausted character allowance requires available credits or an operator-managed allowance renewal.","schema":{"type":"integer","const":60}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error429"}}}},"503":{"description":"SERVICE_UNAVAILABLE. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error503"}}}}}}},"/v1/batch-convert":{"post":{"operationId":"batch_convert_kazakh_script","description":"Convert up to 20 inputs in order, with at most 100000 input Unicode code points in total. The entire batch succeeds and consumes allowance, or no character allowance is consumed. No OCR or document layout conversion is performed.","security":[{"ApiKey":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$"},"description":"Optional REST replay protection for 24 hours, scoped to the account across its API keys. The same operation, input and pinned engine are required; otherwise 409. Replays still consume a rate-limit slot but do not consume more characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchConvertRequest"}}}},"responses":{"200":{"description":"Successful result and character-consumption receipt. Detection consumes zero characters; conversion uses the account allowance. See usage for trial and prepaid consumption when enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchConvertResponse"}}}},"400":{"description":"INVALID_REQUEST. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"AUTHENTICATION_REQUIRED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"INSUFFICIENT_SCOPE or ORIGIN_REJECTED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"NOT_FOUND. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"405":{"description":"METHOD_NOT_ALLOWED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error405"}}}},"409":{"description":"IDEMPOTENCY_CONFLICT. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error409"}}}},"413":{"description":"TEXT_TOO_LARGE or BATCH_TOO_LARGE. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error413"}}}},"415":{"description":"CONTENT_TYPE_REJECTED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error415"}}}},"422":{"description":"SCRIPT_MISMATCH. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error422"}}}},"429":{"description":"RATE_LIMITED or QUOTA_EXCEEDED. Safe error code and request_id; submitted text and credentials are not echoed.","headers":{"Retry-After":{"description":"Wait at least this many seconds before retrying. Exhausted character allowance requires available credits or an operator-managed allowance renewal.","schema":{"type":"integer","const":60}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error429"}}}},"503":{"description":"SERVICE_UNAVAILABLE. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error503"}}}}}}},"/v1/usage":{"get":{"operationId":"get_kaztool_usage","description":"Read this account’s current allowance and UTC calendar-month usage, shared by its API keys and OAuth connections. The response reports billing_enabled, plan and, when enabled, remaining trial and prepaid characters. This request consumes a rate-limit slot but no characters and has no JSON request body.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Current account allowance and usage. This read consumes no characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"400":{"description":"INVALID_REQUEST. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"AUTHENTICATION_REQUIRED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"INSUFFICIENT_SCOPE or ORIGIN_REJECTED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"NOT_FOUND. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"405":{"description":"METHOD_NOT_ALLOWED. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error405"}}}},"429":{"description":"RATE_LIMITED or QUOTA_EXCEEDED. Safe error code and request_id; submitted text and credentials are not echoed.","headers":{"Retry-After":{"description":"Wait at least this many seconds before retrying. Exhausted character allowance requires available credits or an operator-managed allowance renewal.","schema":{"type":"integer","const":60}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error429"}}}},"503":{"description":"SERVICE_UNAVAILABLE. Safe error code and request_id; submitted text and credentials are not echoed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error503"}}}}}}}}}