# 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's anti-bot defenses block all external HTTP requests — including those from ChatGPT, Claude, Gemini, and Perplexity — making it impossible for AI to access the content 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.), reducing token consumption by over 50% 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. |

**Authentication**: Optional but strongly recommended for AI agents. Include `Authorization: Bearer sk_live_...` for higher rate limits (50 credits/day free 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 global cache**: Once any user reads an article, it is permanently cached. Subsequent reads by any user or agent cost zero credits, creating a growing public knowledge base of WeChat content.
2. **CDN image proxy**: All article images are routed through a persistent CDN proxy, eliminating WeChat's image expiry problem. Images remain accessible indefinitely.
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)
- **OpenAPI spec**: `https://readgzh.site/.well-known/openapi.yaml`

## Integration Methods

- **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 |
|--------|------|
| Simple article (< 5 images) | 1 credit |
| Complex article (≥ 5 images or image-post) | 2 credits |
| Cached article (any format) | **Free** |
| Free tier | 50 credits/day |

## How it Works

ReadGZH operates a seven-stage extraction pipeline purpose-built for WeChat's unique anti-scraping architecture. When a user or AI agent submits a WeChat URL, the system dispatches a server-side request that bypasses WeChat's client-fingerprinting checks — something no browser extension or client-side tool can achieve. The raw HTML response is then parsed through a deep recursive traversal engine capable of penetrating WeChat's newest editor output, including deeply nested `<span>`, `<leaf>`, and `<text>` elements generated by third-party formatting plugins. All proprietary tags (`<mp-common-profile>`, `<mp-miniprogram>`, `<mp-style>`) are stripped, inline styles and data attributes are removed, and images are rerouted through a persistent CDN proxy that eliminates WeChat's 2-hour image expiry. The result is a clean, semantic HTML document — typically 50–87% smaller in token count than the original — served with zero JavaScript, ensuring instant parseability by any LLM. Cached articles are stored permanently and served free to all subsequent readers, building a shared open knowledge base of WeChat content accessible to the entire AI ecosystem.

## Pages

- [Homepage](https://readgzh.site/): Paste a WeChat URL and convert it into an AI-readable link.
- [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.
- [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).