API文档
创建白页网站,跟踪其进展,并从您的代码、无代码工具或简单地通过 AI 助手请求中下载文件。每个请求均为通过 HTTPS 的 JSON 格式。
工作原理
无论您如何连接,三个步骤:
- 创建 API 密钥 登录,在仪表板打开 API 密钥并创建一个密钥。它像您账户的密码一样,请保持私密。
- 申请站点 发送标题和语言,如果您愿意,还可以发送主题、受众和关键词。生成费用将从您的余额扣除,站点开始构建。
- 收集您的站点 通常几分钟内即可完成。检查状态,或当完成时让我们调用您的 URL,然后预览、编辑和下载文件。
选择您的连接方式
- 我使用 AI 助手 Claude、ChatGPT、Cursor 等可以为您创建并跟踪站点。
- 我写代码 三个 REST 请求,附带 curl、PHP、Node.js 和 Python 示例。
- 我使用无代码工具 任何能发送 HTTP 请求的工具,如 Zapier、Make 或 n8n,都可以执行同样的三个调用。
无代码工具:任何能发送 HTTP 请求的工具(Zapier、Make、n8n、电子表格脚本)都可以执行同样的调用。POST /sites 启动一个站点;GET /sites/{uuid} 在定时器上或使用 callback_url,告知您其完成状态。将 API 密钥放入 Authorization 头部。
关键术语
- 站点
- 一个生成的网站及其所有页面。通过 uuid 标识。
- 状态
- 构建中状态为 pending,准备完成则为 done,失败则为 error。失败的站点会被自动退款。
- API 密钥
- 证明请求来自您账户的秘密字符串。可在仪表板创建和撤销密钥。
- 余额
- 您账户中的预付款。创建站点时会从中预留生成费用。
- 回调
- 您提供的 URL,当一个站点完成时我们会调用一次,您无需一直检查。
- 幂等键
- 您附加给请求的标签,确保重复发送该请求不会创建或收费两次站点。
与 AI 助手一起使用
连接 AI 助手,只需说:“帮我用土耳其语创建一个牙科诊所的网站。”助手会在您的账户下调用同一 API。您保持控制权:创建站点消耗余额,好的助手会先询问您再操作。
您可以说的话题
- 我有多少余额,一站点费用是多少?
- 哪种设计套件适合面包店?
- 用英语为 Alder House(一个安静的海港旅馆)创建一个单页网站。
- 我的网站准备好了吗?请发送预览链接给我。
通过 MCP 连接(Claude、Cursor 等)
MCP 是助手用来调用外部工具的开放标准。将您的助手指向 MCP URL,并以 Bearer 令牌形式提供您的 API 密钥。
Claude Code
bash
claude mcp add --transport http whitepagekit https://whitepagekit.com/api/v1/mcp \
--header "Authorization: Bearer YOUR_API_KEY"Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"whitepagekit": {
"url": "https://whitepagekit.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer ${env:WPK_API_KEY}"
}
}
}
}Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"whitepagekit": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://whitepagekit.com/api/v1/mcp",
"--header", "Authorization:${WPK_AUTH}"],
"env": { "WPK_AUTH": "Bearer YOUR_API_KEY" }
}
}
}原始 JSON-RPC
curl
curl -X POST https://whitepagekit.com/api/v1/mcp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'Claude Desktop 通过 mcp-remote 桥接访问远程服务器,该桥接需要 Node.js。.
ChatGPT(自定义 GPT)
- 在 ChatGPT 中创建一个 GPT,打开配置并选择创建新操作。
- 选择从 URL 导入并粘贴 https://whitepagekit.com/api/v1/openapi.json?profile=assistant。此简化的 schema 仅包含六个助手工具。
- 在身份验证下选择 API 密钥,设置认证类型为 Bearer 并粘贴您的 API 密钥。
- ChatGPT 会请求您确认更改操作,以便您掌控所有会消耗余额的请求。
Schema URL
https://whitepagekit.com/api/v1/openapi.json?profile=assistantOpenAI API(MCP 工具)
Responses API 可以使用 MCP URL 作为远程工具。require_approval 用于人工审核。
Python
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="YOUR_MODEL",
tools=[{
"type": "mcp",
"server_label": "whitepagekit",
"server_url": "https://whitepagekit.com/api/v1/mcp",
"headers": {"Authorization": "Bearer YOUR_API_KEY"},
"require_approval": "always",
}],
input="What does one site cost, and which design kits suit a bakery?",
)
print(response.output_text)您自己的工具循环(功能调用)
如果您自己运行模型循环,可获取现成工具 schema,并针对匹配的 REST 端点执行每个工具调用。格式有 openai (Responses API)、openai-chat、anthropic 和 mcp。
curl
curl "https://whitepagekit.com/api/v1/ai-tools?format=openai" # or openai-chat, anthropic, mcp这六个工具
| 工具 | 它的功能 | REST 调用 | 费用 |
|---|---|---|---|
get_account |
显示你的余额以及一个站点的费用。 | GET /me |
免费 |
list_languages |
列出网站可以使用的语言。 | GET /languages |
免费 |
list_themes |
按主题或风格搜索设计套件。 | GET /themes |
免费 |
create_site |
开始生成网站并从余额中扣除生成费用。 | POST /sites |
使用余额 |
get_site |
显示一个网站:进度、预览链接和下载链接。 | GET /sites/{uuid} |
免费 |
list_sites |
列出你的站点,按最新顺序。 | GET /sites |
免费 |
把这些文档给任何 AI
此页面也可作为纯 Markdown 使用,适合粘贴到聊天或交给编程助手:
Markdown
https://whitepagekit.com/api/v1/docs.md你可以粘贴的提示
Prompt
You can build websites with the White Page Kit API. Read https://whitepagekit.com/api/v1/docs.md first.
My API key is in the environment variable WPK_API_KEY.
Check my balance and the price, then create a site for my dental clinic in Izmir, in Turkish,
wait until it is ready and send me the preview link.安全和费用
- 只有 create_site 会消耗余额。其他五个工具只是读取。
- 为助手使用单独的密钥。在仪表板中设置到期日期和速率限制,并可随时撤销。
- 助手不能删除站点、更改设置或处理支付:这些路由不作为工具暴露。
- 在 create_site 上设置 idempotency_key,确保重试不会重复收费。失败的生成会退款。
- 编辑页面、参考图片和 ZIP 下载保持在 REST API 和仪表盘中。
快速入门
三个调用让你从简要说明到可下载的网站。将 YOUR_API_KEY 替换为仪表盘中的密钥。
1. 开始生成
POST /sites 验证你的简要说明,从余额中预留生成费用并立即返回。
curl
curl -X POST https://whitepagekit.com/api/v1/sites \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-attempt-1" \
-d '{"title":"Alder House","lang":"en","sector":"guesthouse","keywords":"quiet stay, harbour","structure":"onepage"}'响应是 202 Accepted,附带新网站:
202 Accepted
{
"success": true,
"data": {
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"title": "Alder House",
"lang": "en",
"preview_url": null,
"download_url": null
}
}2. 轮询状态
每隔约 5–20 秒轮询 GET /sites/{uuid} 状态,直到状态为 done 或 error,或使用回调 URL 代替轮询。
curl
curl https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY"3. 下载文件
完成的网站将以 ZIP 格式下载。format 可为 multi 或 onepage;assets 可为 inline 或 external。
curl
curl -o site.zip \
-H "X-API-Key: YOUR_API_KEY" \
"https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000/download?format=multi&assets=inline"代码中的相同步骤
PHP
<?php
$ch = curl_init('https://whitepagekit.com/api/v1/sites');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WPK_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: order-1042-attempt-1',
],
CURLOPT_POSTFIELDS => json_encode(['title' => 'Alder House', 'lang' => 'en']),
]);
$site = json_decode(curl_exec($ch), true)['data'];
do {
sleep(5);
$ch = curl_init('https://whitepagekit.com/api/v1/sites/' . $site['uuid']);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('WPK_API_KEY')]]);
$site = json_decode(curl_exec($ch), true)['data'];
} while ($site['status'] === 'pending');Node.js
const headers = {
Authorization: `Bearer ${process.env.WPK_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'order-1042-attempt-1',
};
let { data: site } = await (await fetch('https://whitepagekit.com/api/v1/sites', {
method: 'POST', headers,
body: JSON.stringify({ title: 'Alder House', lang: 'en' }),
})).json();
while (site.status === 'pending') {
await new Promise((r) => setTimeout(r, 5000));
({ data: site } = await (await fetch(`https://whitepagekit.com/api/v1/sites/${site.uuid}`, { headers })).json());
}Python
import os, time, requests
headers = {"Authorization": f"Bearer {os.environ['WPK_API_KEY']}",
"Idempotency-Key": "order-1042-attempt-1"}
site = requests.post("https://whitepagekit.com/api/v1/sites", headers=headers,
json={"title": "Alder House", "lang": "en"}).json()["data"]
while site["status"] == "pending":
time.sleep(5)
site = requests.get(f"https://whitepagekit.com/api/v1/sites/{site['uuid']}", headers=headers).json()["data"]认证
除 OpenAPI 文档外,每个请求都需发送 API 密钥。请将密钥保存在服务器上,切勿将其放在浏览器代码或 URL 中。
- 请求头:Authorization: Bearer YOUR_API_KEY,或 X-API-Key: YOUR_API_KEY。
- 在仪表盘中创建、撤销和限速密钥。密钥可以设置过期时间和 IP 允许列表。
- 你只能看到自己的站点。属于其他账户的站点返回 404 not_found。
- 添加 ?lang=xx 或 Accept-Language 以本地化错误消息。
幂等性
POST /sites 请求时发送 Idempotency-Key(8–80 个字符:字母、数字、_ 和 -)。重复相同的密钥会返回原始站点,绝不会重复收费,因此超时后的重试是安全的。若生成失败,请用新密钥重试。
Webhook(回调)
将 callback_url 传递到 POST /sites(或设置账户 webhook),并在任务完成(site.completed)或失败(site.failed)时接收一次 JSON POST。
POST callback_url
{
"event": "site.completed",
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"status": "done",
"site_title": "Alder House",
"lang": "en",
"domain": null,
"created_at": "2026-01-15T09:30:00+00:00",
"preview_url": "https://whitepagekit.com/preview?uuid=550e8400-…"
}当账户拥有 webhook 密钥时,每个请求都会携带 X-Webhook-Signature: sha256=<hex>,这是原始体的 HMAC-SHA256。请在解析 JSON 之前进行验证,使用常量时间比较:
PHP
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $webhookSecret);
if (!hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '')) {
http_response_code(401);
exit;
}Node.js
import crypto from 'node:crypto';
const expected = 'sha256=' + crypto
.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
const received = req.get('x-webhook-signature') ?? '';
const ok = received.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));每个回调尝试一次,超时为10秒,不会重试。将其视为通知,并通过 GET /sites/{uuid} 进行对账。通过 uuid 和事件幂等地处理重复。拒绝私有网络目标。
错误
每个响应都使用信封。错误包含稳定的代码、本地化信息,以及对于验证错误,指出失败的字段。
JSON
{
"success": false,
"error": {
"code": "validation_error",
"message": "...",
"details": { "field": "title" }
}
}| HTTP | 错误代码 |
|---|---|
| 400 | validation_error, invalid_json, invalid_webhook_url |
| 401 | missing_api_key |
| 402 | insufficient_balance |
| 403 | api_disabled, invalid_api_key, forbidden |
| 404 | not_found, route_not_found |
| 405 | method_not_allowed |
| 409 | site_not_ready, conflict, edits_reset_required |
| 413 | payload_too_large |
| 415 | unsupported_media_type |
| 429 | rate_limited |
| 500 | internal_error, export_failed |
| 502 | generation_failed |
限制
| 限制 | 值 |
|---|---|
| 每个密钥请求数 | 默认每分钟60次(每密钥可配置,0 = 不限)。来自同一IP的重复无效密钥请求返回429,并带有 Retry-After。 |
| 请求体 | 2MB;POST /sites 带参考图像最大162MB;编辑器保存最大4MB。 |
| 参考图像 | 最多12张PNG、JPEG或WEBP图像(base64或data URL),每张最多10MB。 |
| 编辑页面内容 | HTML至多500,000字符,CSS至多100,000。脚本和事件处理器将被移除。 |
| 站点图像 | PNG、JPEG、WEBP或GIF,每张5MB,最多每站点200张。 |
| 站点标题 | 网站标题 1–200 字符。 |
编辑器 API
仪表盘编辑器所做的一切都适用于您的已完成网站:页面内容、页面和章节计划、样式、标题/主题/布局/结构、跟踪和图片。页面编辑会替换页面;DELETE 会恢复生成的页面。
curl
# Load, change and save a page
curl -H "X-API-Key: YOUR_API_KEY" \
"https://whitepagekit.com/api/v1/sites/UUID/editor?page=index"
curl -X PATCH https://whitepagekit.com/api/v1/sites/UUID/editor \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"page":"index","html":"<main>…</main>","css":""}'
# Restore the generated page
curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
"https://whitepagekit.com/api/v1/sites/UUID/editor?page=index"编辑需要一个已完成的网站(否则返回 409 site_not_ready)。在已编辑页面上更改主题、布局或结构会返回 409 edits_reset_required,除非 reset_edits 为 true。编辑是免费的。
端点参考
根据 OpenAPI 文档生成,因此始终与实时 API 匹配。路径相对于基础 URL。
账号
-
GET
/meGet the authenticated account
-
GET
/transactionsList account balance transactions
目录
-
GET
/languagesList enabled supported languages
-
GET
/themesList site themes
-
GET
/layoutsList enabled layouts
网站
-
GET
/sitesList the authenticated account's sites
-
POST
/sitesStart site generation
-
GET
/sites/{uuid}Get site status and refresh generation state
-
DELETE
/sites/{uuid}Delete a terminal site and its generated data — Pending, queued and running generation jobs cannot be deleted. Wait for done or error; active deletion returns 409 conflict without refunding or removing the job.
-
GET
/sites/{uuid}/downloadDownload a completed site archive
AI 和自动化
-
GET
/ai-toolsFunction-calling tool schemas — The same six tools the MCP endpoint offers, as JSON schemas for your own tool loop. format is openai (Responses API), openai-chat (Chat Completions), anthropic or mcp. Public; no response envelope.
-
GET
/docs.mdDocumentation as Markdown — The developer guide, endpoint reference and AI integration guide as one Markdown file, written for language models and quick copy-paste. Public.
-
POST
/mcpModel Context Protocol endpoint — MCP over Streamable HTTP (JSON-RPC 2.0, one JSON reply per POST). Methods: initialize, ping, tools/list, tools/call. Tools: get_account, list_languages, list_themes, create_site (paid), get_site, list_sites. Authenticate with the same API key; point an MCP client at this URL.
编辑器
-
GET
/sites/{uuid}/editorLoad a page for editing — Editor access for the site owner's API key; mirrors the dashboard editor. Only completed sites (409 site_not_ready otherwise).
-
PATCH
/sites/{uuid}/editorSave a page's edited content — Replaces the page content and CSS. html must be non-empty (use DELETE to restore the generated page); scripts, event handlers and javascript: URLs are removed, HTML is limited to 500000 and CSS to 100000 characters, request body to 4 MB. Returns the saved page as GET does.
-
DELETE
/sites/{uuid}/editorRestore a page's generated content — Discards the page's saved edits. Returns the regenerated page.
-
GET
/sites/{uuid}/editor/canvasGet editing canvas data — Stylesheet, Tailwind theme, body class, direction, section blocks, icons and sample copy an external visual editor needs to render the page like the dashboard editor.
-
GET
/sites/{uuid}/pagesGet the page and section plan — Returns structure, pages with their sections and edited flag, one-page sections and the sections available to add. Same payload as the dashboard.
-
POST
/sites/{uuid}/pagesSave the page and section plan — Body: pages (list of {slug, title, nav, sections}; the first page is index) and, for onepage sites, onepage_sections. Sections of pages with saved edits are locked in the dashboard; edited pages that are removed lose their edits. At most 12 pages.
-
GET
/sites/{uuid}/styleGet style overrides — Returns stored overrides, effective colors, fonts, radius and density, and the allowed font, radius and density values.
-
POST
/sites/{uuid}/styleSave or reset style overrides — Send style ({colors, fonts: {heading, body}, radius, density}) or reset=true to return to the theme.
-
GET
/sites/{uuid}/designGet site title, theme and layout — Returns site_title, title_suggestions, theme_variant, theme_mode, layout, structure and whether the site has saved edits.
-
POST
/sites/{uuid}/designChange site title, theme, mode, layout or structure — theme_variant, theme_mode, layout and structure are required; site_title (1-200 characters), apply_blueprint and reset_edits are optional. Changing theme, layout or structure while pages have saved edits returns 409 edits_reset_required unless reset_edits is true; renaming alone keeps edits.
-
GET
/sites/{uuid}/trackingGet tracking settings
-
POST
/sites/{uuid}/trackingSave tracking settings — Body: tracking {ga4_measurement_id, google_ads_id, google_ads_conversion_label, meta_pixel_id, privacy_policy_url, terms_url}. Applied to exports; an empty object removes all tracking.
-
GET
/sites/{uuid}/mediaList uploaded site images
-
POST
/sites/{uuid}/mediaUpload or delete site images — multipart/form-data with one or more files in files[] (PNG, JPEG, WEBP or GIF, 5 MB each, at most 200 images per site), or JSON {"action": "delete", "name": <name>}. Returns the updated list for uploads. 409 conflict when the per-site image limit is reached.
外部支付(仅管理员密钥)
-
GET
/payment-sitesList external payment sites owned by the admin API account — Admin role required; payment.manage permission alone is insufficient. Webhook secrets are never returned.
-
POST
/payment-sitesRegister an external payment site (admin only)
-
PATCH
/payment-sites/{id}Update an owned external payment site (admin only)
-
DELETE
/payment-sites/{id}Delete an owned external payment site (admin only) — Deletion is allowed only when the site has no orders. Sites with orders must be disabled instead.
-
GET
/paymentsList external orders owned by the admin API account
-
POST
/paymentsCreate external checkout or automatic subscription (admin only) — Server-to-server only. Separate from wallet top-ups: no White Page Kit balance, bonus or referral credit. Repeated idempotency key returns the original order; a different payload or reused external order ID conflicts. Provider uncertainty never starts a second checkout automatically.
-
GET
/payments/{uuid}Read owned external payment status (admin only)
-
POST
/payments/{uuid}/cancelCancel an owned subscription or locally close a pending one-time order (admin only) — Subscriptions stop future renewals. Pending one-time cancellation is a local close, not a refund; an already-open provider checkout may still accept payment. A late authenticated real payment remains recorded and notified. No payment is marked paid by a browser return.
-
POST
/payments/{uuid}/approveApprove funds received for an owned pending or locally cancelled bank transfer (admin only) — Manual confirmation of funds received, including a transfer arriving after local cancellation; never approves a Dodo or Enigmoss order and never credits White Page Kit balance.
描述来自 OpenAPI 文档并为英文。请求和响应模式在 schema 文件中。
现成集成
集成工具包是一个小型 PHP 应用,带有生成器表单、状态轮询、签名回调指导和完整的可视化编辑器,通过服务器端代理与此 API 通信。创建账号以获取密钥,然后查看每次生成的价格。