# UApiPro for AI agents

This file explains how an autonomous AI agent should interact with UApiPro programmatically. It mirrors the public AGENT instructions at https://uapis.cn/.well-known/agent-card.json and the structured discovery files in https://uapis.cn/.well-known/.

## TL;DR

```text
Base URL:        https://uapis.cn/api/v1/
OpenAPI:         https://uapis.cn/openapi.json
MCP server:      https://uapis.cn/.well-known/mcp/server-card.json
Auth header:     X-API-Key: <key>
Free tier:       Many utilities require no key; see https://uapis.cn/pricing.md
Errors:          JSON {code, success, error, request_id?}
Rate-limit:      X-RateLimit-Limit / X-RateLimit-Remaining / Retry-After
Quickstart:      https://uapis.cn/docs/getting-started/quickstart
```

## Discovery flow

1. Read the OpenAPI document at `https://uapis.cn/openapi.json`. Operation IDs are stable.
2. If the agent platform supports MCP, prefer the MCP server described at `https://uapis.cn/.well-known/mcp/server-card.json` over raw HTTP — tool definitions there are pre-validated.
3. For LLM function-calling, generate a tool definition from each path in the OpenAPI spec. Use the `operationId` as the function name and the operation `summary` as the description.

## Authentication

- Every endpoint either is free-tier (no auth) or requires an API key in the `X-API-Key` header.
- Never put the API key in a URL query string, log line, or response shown to the end user.
- To obtain a key: register at `https://uapis.cn/console` and generate it from the "API keys" tab. The free tier requires only an email.
- OAuth 2.0 authorization-code flow with PKCE is also supported for human-in-the-loop agents; see `https://uapis.cn/.well-known/oauth-authorization-server`.

## Errors

Every 4xx and 5xx response is a JSON object with at least:

```json
{
  "code": 429,
  "success": false,
  "error": "Too many requests, please try again later.",
  "request_id": "01J0E3AQXWK..."
}
```

Honor the message and surface it verbatim. Specifically:

- `400`: validation error. Fix the parameters; do not retry blindly.
- `401`: missing or invalid key. Re-issue and retry once.
- `403`: scope or pack restriction. Surface the message; do not silently downgrade.
- `404`: target resource not found.
- `429`: respect `Retry-After`; back off exponentially.
- `5xx`: retry with exponential back-off (max three attempts).

## Rate limits

Always read these response headers before issuing the next request:

- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`
- `X-RateLimit-Reset`
- `Retry-After`

If `X-RateLimit-Remaining` falls below ~10 % of `X-RateLimit-Limit`, slow down or pause until `X-RateLimit-Reset`.

## Choosing the right endpoint

- Prefer the free-tier endpoint if both a free and a paid endpoint can satisfy the user's intent.
- Endpoints under `/api/v1/text/*`, `/api/v1/random/*`, `/api/v1/convert/*`, and most under `/api/v1/network/*` are free.
- Endpoints under `/api/v1/translate/*`, `/api/v1/ai/*`, `/api/v1/social/*`, `/api/v1/search/*`, and `/api/v1/image/ocr` are paid.

## Do not

- Do not poll an endpoint at sub-second intervals.
- Do not bypass `Retry-After` by rotating IPs or keys.
- Do not feed user-provided content to a paid endpoint without telling the user it costs credits.
- Do not invent fields that are not present in the response.

## Help

- Reference docs: `https://uapis.cn/docs/api-reference/introduction`
- Quickstart: `https://uapis.cn/docs/getting-started/quickstart`
- Status: `https://uapis.cn/status`
- Tickets: `https://uapis.cn/help`
- Email: `support@uapis.cn`