跳到内容
White page Kit
中文

API文档

创建白页网站,跟踪其进展,并从您的代码、无代码工具或简单地通过 AI 助手请求中下载文件。每个请求均为通过 HTTPS 的 JSON 格式。

工作原理

无论您如何连接,三个步骤:

  1. 创建 API 密钥 登录,在仪表板打开 API 密钥并创建一个密钥。它像您账户的密码一样,请保持私密。
  2. 申请站点 发送标题和语言,如果您愿意,还可以发送主题、受众和关键词。生成费用将从您的余额扣除,站点开始构建。
  3. 收集您的站点 通常几分钟内即可完成。检查状态,或当完成时让我们调用您的 URL,然后预览、编辑和下载文件。

选择您的连接方式

无代码工具:任何能发送 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)

  1. 在 ChatGPT 中创建一个 GPT,打开配置并选择创建新操作。
  2. 选择从 URL 导入并粘贴 https://whitepagekit.com/api/v1/openapi.json?profile=assistant。此简化的 schema 仅包含六个助手工具。
  3. 在身份验证下选择 API 密钥,设置认证类型为 Bearer 并粘贴您的 API 密钥。
  4. ChatGPT 会请求您确认更改操作,以便您掌控所有会消耗余额的请求。

Schema URL

https://whitepagekit.com/api/v1/openapi.json?profile=assistant

OpenAI 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 /me

    Get the authenticated account

  • GET /transactions

    List account balance transactions

目录

  • GET /languages

    List enabled supported languages

  • GET /themes

    List site themes

  • GET /layouts

    List enabled layouts

网站

  • GET /sites

    List the authenticated account's sites

  • POST /sites

    Start 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}/download

    Download a completed site archive

AI 和自动化

  • GET /ai-tools

    Function-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.md

    Documentation 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 /mcp

    Model 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}/editor

    Load 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}/editor

    Save 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}/editor

    Restore a page's generated content — Discards the page's saved edits. Returns the regenerated page.

  • GET /sites/{uuid}/editor/canvas

    Get 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}/pages

    Get 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}/pages

    Save 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}/style

    Get style overrides — Returns stored overrides, effective colors, fonts, radius and density, and the allowed font, radius and density values.

  • POST /sites/{uuid}/style

    Save or reset style overrides — Send style ({colors, fonts: {heading, body}, radius, density}) or reset=true to return to the theme.

  • GET /sites/{uuid}/design

    Get 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}/design

    Change 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}/tracking

    Get tracking settings

  • POST /sites/{uuid}/tracking

    Save 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}/media

    List uploaded site images

  • POST /sites/{uuid}/media

    Upload 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-sites

    List 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-sites

    Register 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 /payments

    List external orders owned by the admin API account

  • POST /payments

    Create 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}/cancel

    Cancel 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}/approve

    Approve 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 通信。创建账号以获取密钥,然后查看每次生成的价格。