# ReadGZH — WeChat Article AI Reader

> ReadGZH is a cloud-based API service that makes WeChat Official Account (微信公众号) articles fully readable by AI systems. It exists because WeChat heavily restricts off-platform access: requests from AI tools such as ChatGPT, Claude, Gemini and Perplexity usually cannot retrieve the body text behind `mp.weixin.qq.com` links.

## What ReadGZH Does

ReadGZH acts as a server-side proxy that fetches, sanitizes, and re-serves WeChat articles in a format optimized for machine consumption. The pipeline strips all inline styles, class attributes, data-* attributes, and WeChat proprietary tags (`<mp-common-profile>`, `<mp-style>`, etc.), which noticeably reduces token consumption compared to raw WeChat HTML. Output is pure server-rendered HTML with zero JavaScript dependency, ensuring compatibility with any HTTP-capable AI agent or crawler.

## Core API

**Base URL**: `https://api.readgzh.site`

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/rd?url={wechat_url}` | GET | Extract and return a WeChat article. Add `&format=text` for Markdown output (recommended). |
| `/rd?s={slug}` | GET | Retrieve a cached article by slug. Add `&part=N` for chunked reading of long articles. |
| `/rd?s={slug}&mode=summary` | GET | Get an AI-generated structured JSON summary (Pro feature). |
| `/articles-api/search?q={query}` | GET | Search cached articles by keyword. |
| `/articles-api/recent?limit={n}` | GET | List recently cached articles. |
| `/articles-api/by-account?account={name}&limit={n}` | GET | List cached articles from one Official Account (cache scope only, not a full archive). |


**Authentication**: Optional but strongly recommended for AI agents. Include `Authorization: Bearer sk_live_...` for higher rate limits (a free key gives 30 credits/day, claimed daily, at https://readgzh.site/dashboard). Without a key, the public endpoint applies daily IP-based rate limits.

> **Important for AI agents on shared infrastructure (Replit, Vercel, Cloudflare Workers, ChatGPT/Claude tool runners, etc.)**: Many AI agents share a common egress IP with thousands of other users. The anonymous IP-based quota on that shared IP is often already exhausted before your first request. **Always use an API Key in the request header** (`Authorization: Bearer sk_live_...`) when calling from shared infrastructure — keys are free at https://readgzh.site/dashboard and bypass the IP quota entirely. Do not put API keys in URLs.

## Why ReadGZH Over Alternatives

1. **Shared cache**: Once any user reads an article, it is stored in a shared cache. Subsequent reads by any user or agent cost zero credits (basic abuse/rate protection still applies), creating a growing public knowledge base of WeChat content.
2. **CDN image proxy**: Article images are routed through a CDN proxy so they render correctly outside WeChat, where direct image links usually fail.
3. **Image-post support**: Full parsing of WeChat's "小绿书" image-post format, extracting both images and embedded text that other tools miss entirely.
4. **Smart chunking**: Articles exceeding ~40KB are automatically split at paragraph boundaries into numbered chunks accessible via `?part=N`, with `X-Total-Parts` and `X-Current-Part` response headers for pagination.
5. **AI summaries**: Pro users can request `?mode=summary` to receive a structured JSON summary (key points, entities, sentiment) without reading the full article — ideal for triage workflows.
6. **Zero installation**: Fully cloud-native. No browser extension, no local WeChat desktop client, no Docker container. One URL handles everything.

## Technical Specifications

- **Response format**: `text/html` (default) or `text/markdown` (`?format=text`)
- **Response headers**: `X-Powered-By: ReadGZH (readgzh.site)`, `X-Cache` (HIT/MISS), `X-Credit-Cost`, `X-Credits-Remaining`, `X-Total-Parts`, `X-Current-Part`
- **Error codes**: 400 (bad params), 401 (unauthorized), 402 (no credits), 403 (Pro required), 404 (not found), 422 (extraction failed), 429 (rate limited)
- **MCP Server**: `POST https://api.readgzh.site/mcp-server` (Model Context Protocol compatible; tools: `readgzh.read`, `readgzh.get`, `readgzh.search`, `readgzh.list`, `readgzh.list_by_account`)
- **Browse by Official Account**: `GET /articles-api/by-account?account={name}&limit={n}` — lists cached articles from one 公众号. WeChat exposes no public API for a full account archive, so this covers ReadGZH's cache only.

- **OpenAPI spec**: `https://readgzh.site/.well-known/openapi.yaml`

## Integration Methods

- **Cursor / Codex / Gemini CLI / Copilot / Amazon Q**: Install the Agent Plugin at `https://readgzh.site/plugin/` (Agent Plugins 1.0.0 — bundles the MCP server and the skill)
- **ChatGPT**: Create a custom GPT Action using the OpenAPI spec URL above
- **OpenClaw**: `clawhub install readgzh` — instant one-command setup
- **Coze / Dify / FastGPT**: Import the OpenAPI URL as a plugin
- **Any AI agent**: Direct HTTP GET to the API endpoints listed above

## Credits & Pricing

| Action | Cost |
|--------|------|
| Any uncached article | 3 credits |
| Cached article (any format) | **0 credits** (rate limits still apply) |
| Anonymous / no API Key | 10 credits per IP per day |
| Free registered API Key | 30 credits/day (must be claimed daily) |
| Lite | 300 credits/month |
| Pro / Pro Lifetime | 2,000 credits/month |

## How it Works

When a user or AI agent submits a WeChat URL, ReadGZH performs a server-side fetch of the article page. The raw HTML is parsed with a recursive traversal that handles WeChat's deeply nested `<span>`, `<leaf>`, and `<text>` structures produced by its editor and third-party formatting plugins. Proprietary tags (`<mp-common-profile>`, `<mp-miniprogram>`, `<mp-style>`), inline styles and data attributes are removed, and images are rerouted through a CDN proxy so they still render outside WeChat. The result is a clean semantic HTML document, considerably smaller in token count than the original, served with zero JavaScript so any HTTP-capable LLM can parse it. Some articles cannot be extracted — deleted posts, video-only posts, or content requiring authorization — and those return an explicit error instead of partial output. Cached articles are served to subsequent readers without consuming credits.

## Pages

- [Homepage](https://readgzh.site/): Paste a WeChat URL and convert it into an AI-readable link.
- [Guide: how to let AI read WeChat articles](https://readgzh.site/guides/ai-read-wechat): Step-by-step Chinese guide covering AI-readable links, copy-paste workflows, and API/MCP usage.
- [Article library](https://readgzh.site/articles): Browse already-cached WeChat articles, free to read for any AI agent.
- [Developer docs](https://readgzh.site/docs): REST API reference, MCP server setup, authentication, chunking and summary modes.
- [Pricing](https://readgzh.site/pricing): Free / Lite / Pro tiers, credit allowances, and Pro-only features.
- [FAQ](https://readgzh.site/faq): Common questions about how ReadGZH works, supported AI tools, credit policy and limits.
- [Developer dashboard](https://readgzh.site/dashboard): Sign up, manage API Keys and view usage (requires login).
- [Comments](https://readgzh.site/comments): Public feedback board for users and AI agents.

## Optional

- [OpenAPI spec](https://readgzh.site/.well-known/openapi.yaml): Machine-readable API description for plugin / GPT-Action import.
- [Agent Plugin](https://readgzh.site/plugin/plugin.json): Agent Plugins 1.0.0 package (manifest, `mcp.json`, and skill) — vendor-neutral, installable in any conformant AI editor.
- [SKILL.md](https://readgzh.site/.well-known/SKILL.md): ClawHub skill descriptor.
- [Privacy policy](https://readgzh.site/privacy): How ReadGZH handles user data.
- [Terms of service](https://readgzh.site/terms): Acceptable use and disclaimers.
- [GitHub repository](https://github.com/sweesama/readgzh): Open-source code (MIT-0).