# UApiPro > UApiPro is a free public API service platform that exposes 100+ stable REST APIs through a single uniform interface. It is operated at https://uapis.cn and is built for developers who need reliable, low-friction access to common API capabilities such as text processing, network utilities, social platform queries, image tools, translation, search, weather, and game data — all returning JSON over HTTPS. This file consolidates the full agent-relevant context (overview, capabilities, authentication, rate limits, error format, SDKs, and quick-start examples) so that AI agents can ingest the entire product surface in one HTTP request without crawling. --- ## What UApiPro is UApiPro provides a curated catalog of public REST APIs under https://uapis.cn/api/v1/. Each endpoint: - Returns JSON; successful payloads are endpoint-specific objects, and errors use the shared `{code, message, details?}` envelope documented below. - Supports CORS and HTTPS; no special preflight tricks required. - Has a documentation page under https://uapis.cn/docs/api-reference/ with parameters, example request, and example responses. - Is described once in the OpenAPI specification at https://uapis.cn/openapi.json. The free tier is genuinely free: the most common endpoints (IP info, hashing, base64, lunar/world time, programmer history, random images, AES, weather, etc.) work without any registration. Higher-cost endpoints (translation, OCR, Bilibili/QQ social queries, web search aggregation, async Markdown-to-PDF) consume credits from a pay-as-you-go pack purchased on the pricing page. ## Use cases - Bootstrap a hobby project that needs more than one external utility (IP, weather, QR code, hash) without integrating four separate vendors. - Add an AI agent skill: agents call the OpenAPI directly or use the official MCP server. - Prototype rate-limited demos for hackathons and tutorials. - Replace ad-hoc home-grown utilities (Markdown-to-PDF, image compression, AES encryption) with a hosted endpoint. ## Constraints - Fair-use rate limits apply to free-tier traffic; sustained automated traffic should buy a credit pack. - The free tier does not carry an SLA; production traffic that needs uptime guarantees should buy a credit pack. - Some endpoints (social platform queries, weather forecasts) are scoped to publicly accessible data and may be unavailable in certain regions. --- ## API surface (high-level) | Category | What it does | Example endpoints | |-------------|--------------------------------------------------------------------------------------------|-------------------| | Convert | JSON formatting, Unix-time conversions, structural transforms | `POST /api/v1/convert/json`, `GET /api/v1/convert/unixtime` | | Daily | Daily news image, programmer history, sayings | `GET /api/v1/daily/news-image`, `GET /api/v1/history/programmer/today`, `GET /api/v1/saying` | | Game | Minecraft player and server lookups, Steam profile summary, Epic free games | `GET /api/v1/game/minecraft/serverstatus`, `GET /api/v1/game/steam/summary`, `GET /api/v1/game/epic-free` | | Image | OCR, NSFW detection, compression, base64 conversion, QR code generation, Gravatar | `POST /api/v1/image/ocr`, `POST /api/v1/image/nsfw`, `POST /api/v1/image/compress`, `GET /api/v1/image/qrcode` | | Misc | Weather, hot-board feeds, lunar/world time, phone info, district lookup | `GET /api/v1/misc/weather`, `GET /api/v1/misc/hotboard`, `GET /api/v1/misc/worldtime`, `GET /api/v1/misc/phoneinfo` | | Network | IP geolocation, DNS, WHOIS, ICP query, URL status check | `GET /api/v1/network/ipinfo`, `GET /api/v1/network/dns`, `GET /api/v1/network/icp` | | Poem | Curated Chinese poetry lookup | `GET /api/v1/poem` | | Random | Random images, random strings | `GET /api/v1/random/image`, `GET /api/v1/random/string` | | Search | Aggregated web search returning structured JSON | `POST /api/v1/search/aggregate`, `GET /api/v1/search/engines` | | Sensitive | Sensitive-word and content-safety detection | `POST /api/v1/sensitive-word/analyze`, `GET /api/v1/sensitive-word/quick-check` | | Social | Public profile metadata for QQ, Bilibili, GitHub | `GET /api/v1/social/qq/userinfo`, `GET /api/v1/social/bilibili/userinfo`, `GET /api/v1/github/repo` | | Status | Per-key usage and rate-limit introspection | `GET /api/v1/status/usage`, `GET /api/v1/status/ratelimit` | | Text | AES-128/192/256, Base64, MD5, Markdown-to-PDF, ASCII conversion, sensitive-word detection | `POST /api/v1/text/aes/encrypt`, `POST /api/v1/text/aes/decrypt`, `GET /api/v1/text/md5`, `POST /api/v1/text/markdown-to-pdf` | | Translate | Standard translation, streaming translation, AI-assisted translation | `POST /api/v1/translate/text`, `POST /api/v1/translate/stream`, `POST /api/v1/ai/translate` | | WebParse | Page metadata extraction, image extraction, async Markdown extraction | `GET /api/v1/webparse/metadata`, `GET /api/v1/webparse/extractimages`, `POST /api/v1/web/tomarkdown/async` | The complete enumeration with parameters, schemas, and response examples lives in the OpenAPI spec at https://uapis.cn/openapi.json. Every documentation page also has a plain Markdown alternate: append `.md` to the docs URL and request it directly. Examples: - English guide Markdown: https://uapis.cn/en/docs/getting-started/migration-guide.md - Chinese/default API page Markdown: https://uapis.cn/docs/api-reference/get-history-programmer-today.md --- ## Authentication UApiPro authenticates API keys as Bearer tokens: send `Authorization: Bearer ` (keys start with `uapi-`). The `X-API-Key` header is accepted as a legacy alternative for compatibility. Free-tier endpoints do not require a key; paid endpoints reject unauthenticated requests with HTTP 401. ```bash curl -H "Authorization: Bearer $UAPI_API_KEY" \ "https://uapis.cn/api/v1/translate/text" \ -X POST \ -H "Content-Type: application/json" \ -d '{"text":"Hello, world.","to_lang":"zh"}' ``` To obtain a key: 1. Sign in at https://uapis.cn/console. 2. Open the "API keys" tab and click "Generate new key". 3. Copy the value and store it in your secret manager. Keys are not shown again. OAuth 2.0 metadata is published at https://uapis.cn/.well-known/oauth-authorization-server and protected-resource metadata at https://uapis.cn/.well-known/oauth-protected-resource. Supported flows are `authorization_code` (with PKCE), `refresh_token`, and `client_credentials`. The minimal required scope to call any UApiPro endpoint is `uapi:call`. For self-hosted bots that sign requests via RFC 9421, publish your Ed25519 public key at `/.well-known/http-message-signatures-directory` on your own domain. --- ## Errors 4xx and 5xx responses are JSON. The standard shape is: ```json { "code": "SERVICE_BUSY", "message": "Too many requests, please try again later.", "details": {} } ``` - `code` is a machine-readable **string** (e.g. `INVALID_PARAMETER`, `UNAUTHORIZED`, `INTERNAL_SERVER_ERROR`, `SERVICE_BUSY`). - `message` is the human-readable text; surface it verbatim. - `details` is optional structured context. - The request id is returned in the `X-Request-ID` **response header**, not in the body; quote it in support tickets. - Some billing and rate-limit paths return a legacy variant with a numeric `code` and/or an `error` field; read `code` first, fall back to `error`, and use `message` for display. | Status | Meaning | Recovery | |--------|----------------------------------------|----------| | 400 | Bad request / validation error | Inspect `message`, fix parameters | | 401 | Missing or invalid API key | Re-issue key, retry once | | 402 | Insufficient credits | Buy a pack; do not retry | | 403 | API key lacks permission for endpoint | Upgrade pack or remove restriction | | 404 | Resource not found (e.g. unknown user) | Verify input | | 429 | Rate limit exceeded | Honor `Retry-After`; back off exponentially | | 5xx | Server error | Retry with exponential back-off (max 3 attempts) | All endpoints return rate-limit headers that agents should honor before issuing the next request: - `RateLimit-Policy` — aggregated quota/rate policy entries. - `RateLimit` — aggregated remaining state with reset times. - `X-RateLimit-Limit` / `X-RateLimit-Remaining` — legacy single-value views of the first policy entry. - `Retry-After` — seconds to wait before retrying (set on 429 and 503). --- ## Rate limits Free tier traffic is governed by per-IP and per-key limits documented at https://uapis.cn/docs/getting-started/fair-use-and-rate-limiting. As a rule of thumb: - Burst limit: 30 requests per 10 seconds per IP. - Sustained limit: a few thousand requests per day for the most common free endpoints. - Paid packs raise both burst and sustained limits proportional to the pack tier. Recommended client behavior: ```text 1. Read X-RateLimit-Remaining after each response. 2. If the remaining value drops below ~10% of the limit, slow down. 3. On 429, sleep for `Retry-After` seconds (or 1s if the header is missing) and retry once. 4. After two consecutive 429s, switch to exponential back-off starting at 5s. ``` --- ## Quickstart ```bash # 1. Free request, no auth. curl 'https://uapis.cn/api/v1/network/myip' # 2. Free POST. curl 'https://uapis.cn/api/v1/text/base64/encode' \ -H 'Content-Type: application/json' \ -d '{"text":"hello"}' # 3. Paid request with an API key (Bearer token). curl 'https://uapis.cn/api/v1/translate/text' \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $UAPI_API_KEY" \ -d '{"text":"Simplicity is the ultimate sophistication.","to_lang":"zh"}' ``` ```typescript // Using the official TypeScript SDK. import { UapiClient } from "@uapi/sdk"; const client = new UapiClient({ apiKey: process.env.UAPI_API_KEY }); const result = await client.network.myip(); console.log(result.data.ip, result.data.country); ``` ```python # Using the official Python SDK. from uapi import UapiClient client = UapiClient(api_key=os.environ["UAPI_API_KEY"]) weather = client.misc.weather(city="北京") print(weather.data["temperature"]) ``` --- ## SDKs | Language | Package / Import | Repository | |-----------------|-------------------------------------------------|------------| | TypeScript / JS | `@uapi/sdk` (`npm install @uapi/sdk`) | https://github.com/AxT-Team/uapi-sdk-typescript | | Python | `uapi-sdk` (`pip install uapi-sdk`) | https://github.com/AxT-Team/uapi-sdk-python | | Go | `github.com/AxT-Team/uapi-sdk-go` | https://github.com/AxT-Team/uapi-sdk-go | | Java | Maven coordinates in repo README | https://github.com/AxT-Team/uapi-sdk-java | | PHP | Composer package in repo README | https://github.com/AxT-Team/uapi-sdk-php | | C# / .NET | NuGet package in repo README | https://github.com/AxT-Team/uapi-sdk-csharp | | C++ | Header-only / CMake instructions in repo README | https://github.com/AxT-Team/uapi-sdk-cpp | | Rust | Crate in repo README | https://github.com/AxT-Team/uapi-sdk-rust | | Browser JS | Drop-in `