# Forma API — Complete Documentation ## Overview Forma is an AI-friendly WeChat article typesetting API. It converts Markdown to themed HTML optimized for WeChat Official Account articles. Base URL: `https://forma.quickext.com/api/v1` ## POST /api/v1/render Render Markdown content to WeChat-themed HTML. ### Request ```json { "content": "# Article Title\n\nYour markdown content here...", "format": "markdown", "theme": "swiss" } ``` | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | content | string | Yes | — | Markdown content to render | | format | string | No | "markdown" | Input format. Currently only "markdown" | | theme | string | No | "swiss" | Theme ID (see GET /themes) | ### Maximum Size 10 MB per request. ### Success Response (200) ```json { "success": true, "data": { "html": "

Article Title

\n

Your content...

", "css": "#forma { ... }", "meta": { "wordCount": 1200, "readingTimeMinutes": 3 } }, "theme": { "id": "swiss", "name": "克莱因笔记" } } ``` ### Error Responses **400 Validation Error:** ```json { "success": false, "error": { "type": "https://forma.quickext.com/docs/errors#validation", "code": "VALIDATION_ERROR", "message": "content: content is required", "doc_url": "https://forma.quickext.com/docs/ai-guide" } } ``` **413 Content Too Large:** ```json { "success": false, "error": { "type": "https://forma.quickext.com/docs/errors#validation", "code": "VALIDATION_ERROR", "message": "Content exceeds max size of 10MB" } } ``` **500 Server Error:** ```json { "success": false, "error": { "type": "https://forma.quickext.com/docs/errors#server", "code": "SERVER_ERROR", "message": "Render failed" } } ``` ## GET /api/v1/health Health check endpoint. ### Response (200) ```json { "status": "ok", "version": "0.1.0", "timestamp": "2026-06-06T12:00:00.000Z" } ``` ## GET /api/v1/themes List available themes. ### Response (200) ```json { "themes": [ { "id": "swiss", "name": "克莱因笔记" }, { "id": "evolution-cat", "name": "蓝调书房" }, { "id": "default", "name": "素白信笺" }, { "id": "暖纸", "name": "旧纸书摘" } ] } ``` ## Theme Descriptions - **swiss** (克莱因笔记): Klein-blue minimalist. Counter-numbered H2 headings, em-dash list markers, ultra-light H1. Best for structured essays and technical writing. - **evolution-cat** (蓝调书房): Warm blue reading room aesthetic. Serif body, indigo headings, soft background. Best for narrative articles and personal essays. - **default** (素白信笺): Clean white letter paper. Classic sans-serif, balanced spacing, subtle decorative elements. Best for general-purpose articles. - **暖纸** (旧纸书摘): Vintage warm paper. Sepia tones, serif typography, aged-paper texture. Best for literary content and nostalgic pieces. ## Using the Rendered Output The API returns `html` and `css` separately. To create a complete WeChat-compatible article: 1. Wrap `html` in a `
` container 2. Include `css` in a `
{{html}}
``` ## Rate Limits - 60 requests per minute per IP - 1000 requests per hour per IP ## Authentication The public API does not require authentication. It is designed for AI agent consumption. ## Versioning API version is in the URL path (`/api/v1/`). Breaking changes will increment the version number.