PXAnyAPI 文档
PXANY / API DOCUMENTATION

PXAny 公共 API

面向 Codex、AI Agent、服务端脚本和 PXAny Chrome 扩展的数据接口。 当前提供站点 Analytics、Serp 搜索代理、URL 重定向解析、URL 内容提取、 关键词搜索量、Ahrefs DR、Product Hunt、On Page SEO 检测以及外链发布工作流。

基础地址https://api.pxany.com/v1
数据格式HTTPS / JSON
鉴权方式Bearer API Key
PUBLIC ENDPOINTS

接口总览

以下是当前可直接调用的公共业务接口。管理后台内部路由/api/admin/* 不属于公共 API。

GET/v1/analytics/ga4GA4 流量、渠道和落地页数据需要密钥
GET/v1/analytics/ga4/eventsGA4 各事件的用户数和次数（实时查询，可按维度拆分）需要密钥
GET/v1/analytics/gscGSC 搜索词和页面数据需要密钥
GET/v1/serp通过私有 SerpAPI 账号池代理 Google 搜索需要密钥
GET/v1/trends复用 SerpAPI 账号池查询 Google Trends 趋势、地区热度及相关词需要密钥
GET/v1/ahrefs-domain-rating查询域名或 URL 的 Ahrefs Domain Rating需要密钥
GET/v1/aitdkAITDK domain traffic, Whois, and SEO event data需要密钥
GET/v1/product-hunt/daily-products拉取 Product Hunt 指定日期的全部产品和产品 URL需要密钥
GET/v1/url-redirect解析 HTTP(S) URL 的最终地址和完整跳转链需要密钥
POST/v1/url-content抓取指定 URL 并转换为 Markdown 内容需要密钥
POST/v1/sites创建标准站点需要密钥
GET/v1/sites/lookup按域名查询标准站点需要密钥
PATCH/v1/sites/{siteId}更新标准站点状态需要密钥
GET/v1/landing-pages读取站点内页 URL 结构与近 28 天 GSC 数据需要密钥
PATCH/v1/landing-pages/{pageId}更新内页上线 URL 与生命周期状态需要密钥
GET/v1/domains/check实时查询域名注册状态（RDAP / WHOIS）需要密钥
POST/v1/keyword-volumesGoogle Ads 关键词历史指标需要密钥
GET/POST/v1/chrome2cf/*PXAny 浏览器/扩展采集通道需要密钥
GET/POST/v1/publishing/deliveries/{id}Substack、Medium 与 Beehiiv 冻结文稿、私有配图与一次性发布许可需要密钥
GET/v1/extension/statusPXAny Chrome 扩展连接状态需要密钥
GET/POST/v1/on-page-seo-check/*检测扩展当前标签页，并按 page_id 读取关键词和历史报告需要密钥
GET/PATCH/v1/backlinks/settings外链库筛选组配置需要密钥
POST/v1/backlinks/directory-submissions/plan外链表单分析后生成 AI 填写计划需要密钥
POST/v1/backlinks/submission-guides/generate根据整页内容生成通用外链提交步骤和全部草稿需要密钥
POST/v1/backlinks/directory-submissions/rewrite外链表单单字段按自定义要求重新生成草稿需要密钥
POST/v1/backlinks/campaign-items/{itemId}/*博客评论任务准备、一次性提交许可、结果回写与人工继续需要密钥
GET/POST/PATCH/DELETE/v1/backlinks/*外链目标网站、任务创建、评论生成和结果回写需要密钥
访问边界

外部调用统一走 https://api.pxany.com/v1/*。 扩展不直接访问 Supabase，也不直接调用 Gemini。

AUTHENTICATION

身份鉴权

所有公共业务接口使用同一把私有密钥。请求头必须包含 Bearer Token。

HTTP 请求头
Authorization: Bearer <PXANY_API_KEY>

密钥只保存到服务端、Cloudflare Secret 或所有者本机环境。 示例、日志、文档和仓库中只允许出现占位符。

GET/v1/analytics/ga4 / /v1/analytics/gsc
需要密钥

站点 Analytics

从最近一次同步的数据中读取 GA4 或 GSC 报告。

查询参数

sitestring / 必填

已在 PXAny 中启用的标准站点域名。

daysinteger / 可选

1 到 90 的整数，默认 28。

cURL
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/analytics/ga4?site=<SITE_DOMAIN>&days=28"

curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/analytics/gsc?site=<SITE_DOMAIN>&days=28"
GA4 返回

包含 totals、dailySeries、channelBreakdown 和 topLandingPages。

GSC 返回

包含 totals、dailySeries、topQueries 和 topPages。

GET/v1/analytics/ga4/events
需要密钥

GA4 事件

用 PXAny 的 Google 服务账号实时查询 GA4 Data API，返回每个事件的 去重用户数（totalUsers）和触发次数 （eventCount），用于搭建转化漏斗。事件数据不进入每小时同步， 每次请求都会访问 GA4。时间范围截至 UTC 昨天，共 days 天。

查询参数

sitestring / 必填

已在 PXAny 中启用且配置了 GA4 的标准站点域名。

daysinteger / 可选

1 到 90 的整数，默认 28。

eventsstring / 可选

逗号分隔的事件名，最多 30 个；不传则返回全部事件。

breakdownstring / 可选

额外拆分维度，只能选一个：date、sessionDefaultChannelGroup、deviceCategory、country、landingPage，或customEvent:<参数名>。自定义维度必须先在 GA4 媒体资源中注册，否则返回 400。

cURL
curl --fail-with-body --get "https://api.pxany.com/v1/analytics/ga4/events" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  --data-urlencode "site=<SITE_DOMAIN>" \
  --data-urlencode "days=28" \
  --data-urlencode "events=page_view,offer_viewed,begin_checkout,purchase" \
  --data-urlencode "breakdown=customEvent:offer_surface"
200 返回

events 按用户数从高到低排列，用户数在每个事件内由 GA4 去重；breakdown.rows 是事件 × 维度值的明细，行数超过 10,000 时truncated 为 true。不要把拆分行的用户数相加当作事件总用户数。

JSON
{
  "source": "ga4",
  "site": {
    "id": 1,
    "slug": "example.com",
    "name": "Example",
    "domain": "example.com",
    "timezone": "UTC"
  },
  "range": {
    "days": 28,
    "start": "2026-10-09",
    "end": "2026-11-05"
  },
  "events": [
    {
      "eventName": "page_view",
      "totalUsers": 30251,
      "eventCount": 50918
    },
    {
      "eventName": "offer_viewed",
      "totalUsers": 2100,
      "eventCount": 4300
    },
    {
      "eventName": "begin_checkout",
      "totalUsers": 60,
      "eventCount": 75
    },
    {
      "eventName": "purchase",
      "totalUsers": 18,
      "eventCount": 20
    }
  ],
  "breakdown": {
    "dimension": "customEvent:offer_surface",
    "truncated": false,
    "rows": [
      {
        "eventName": "offer_viewed",
        "value": "pricing",
        "totalUsers": 900,
        "eventCount": 1500
      }
    ]
  },
  "generatedAt": "2026-11-06T08:00:00.000Z"
}
错误响应

400：参数不合法或自定义维度未注册；401：密钥无效；404：站点不存在或未配置 GA4； 502：GA4 Data API 请求失败。

JSON
{
  "type": "https://api.pxany.com/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "GA4 rejected breakdown customEvent:offer_surface. Custom dimensions must be registered in the GA4 property first.",
  "requestId": "example-request-id"
}
GET/v1/ahrefs-domain-rating
需要密钥

Ahrefs Domain Rating

查询域名或 URL 当前的 Ahrefs DR。

查询参数

targetstring / 必填

目标域名或 HTTP(S) URL，例如 example.com。

cURL
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/ahrefs-domain-rating?target=example.com"
GET/v1/aitdk
Requires API key

AITDK

Proxy the former Cloudflare aitdk Worker through PXAny. The default response parses AITDK SSE events and also includes the raw upstream stream text.

Query parameters

domainstring / required

Domain or HTTP(S) URL, for example htmltourl.com.

formatjson | sse / optional

Defaults to json. Use sse to stream the upstream event stream.

nonce / signature / timestampoptional

Omit these to let PXAny sign the upstream AITDK request with its stored API Account. Provide all three to forward a pre-signed request.

cURL
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/aitdk?domain=htmltourl.com"
Full parsed response
{
  "data": {
    "whois": {
      "domain": "htmltourl.com",
      "data": {
        "objectClassName": "domain",
        "handle": "3098391454_DOMAIN_COM-VRSN",
        "ldhName": "HTMLTOURL.COM",
        "links": [
          {
            "value": "https://rdap.verisign.com/com/v1/domain/HTMLTOURL.COM",
            "rel": "self",
            "href": "https://rdap.verisign.com/com/v1/domain/HTMLTOURL.COM",
            "type": "application/rdap+json"
          },
          {
            "value": "https://rdap.namecheap.com/domain/HTMLTOURL.COM",
            "rel": "related",
            "href": "https://rdap.namecheap.com/domain/HTMLTOURL.COM",
            "type": "application/rdap+json"
          }
        ],
        "status": ["client transfer prohibited"],
        "entities": [
          {
            "objectClassName": "entity",
            "handle": "1068",
            "roles": ["registrar"],
            "links": [
              {
                "href": "http://www.namecheap.com",
                "type": "text/html",
                "value": "https://rdap.namecheap.com/",
                "rel": "about"
              }
            ],
            "publicIds": [
              {
                "type": "IANA Registrar ID",
                "identifier": "1068"
              }
            ],
            "vcardArray": [
              "vcard",
              [
                ["version", {}, "text", "4.0"],
                ["fn", {}, "text", "NameCheap, Inc."]
              ]
            ],
            "entities": [
              {
                "objectClassName": "entity",
                "roles": ["abuse"],
                "vcardArray": [
                  "vcard",
                  [
                    ["version", {}, "text", "4.0"],
                    ["fn", {}, "text", ""],
                    ["tel", { "type": "voice" }, "uri", "tel:+1.6613102107"],
                    ["email", {}, "text", "abuse@namecheap.com"]
                  ]
                ]
              }
            ]
          }
        ],
        "events": [
          {
            "eventAction": "registration",
            "eventDate": "2026-05-11T19:37:13Z"
          },
          {
            "eventAction": "expiration",
            "eventDate": "2027-05-11T19:37:13Z"
          },
          {
            "eventAction": "last changed",
            "eventDate": "2026-05-11T20:07:52Z"
          },
          {
            "eventAction": "last update of RDAP database",
            "eventDate": "2026-07-21T01:30:35Z"
          }
        ],
        "secureDNS": {
          "delegationSigned": false
        },
        "nameservers": [
          {
            "objectClassName": "nameserver",
            "ldhName": "ROAN.NS.CLOUDFLARE.COM"
          },
          {
            "objectClassName": "nameserver",
            "ldhName": "VAL.NS.CLOUDFLARE.COM"
          }
        ],
        "rdapConformance": [
          "rdap_level_0",
          "icann_rdap_technical_implementation_guide_1",
          "icann_rdap_response_profile_1"
        ],
        "cached": 1785667400864
      }
    },
    "traffic": {
      "domain": "htmltourl.com",
      "data": {
        "hostname": "htmltourl.com",
        "title": "",
        "description": "",
        "cached": 1785667400862,
        "overview": {
          "bounceRate": "0.2031821140725134",
          "month": "6",
          "year": "2026",
          "pagePerVisit": "6.7623626864547965",
          "visits": "7268",
          "timeOnSite": "305.59707482219966",
          "hostname": "htmltourl.com",
          "globalRank": 2034642,
          "countryRank": 31298
        },
        "monthlyVisits": {
          "2026-02-01": 0,
          "2026-03-01": 0,
          "2026-04-01": 0,
          "2026-05-01": 0,
          "2026-06-01": 7268
        },
        "trafficSources": {
          "socialOrganic": 0,
          "socialPaid": 0,
          "mail": 0,
          "referrals": 0,
          "searchOrganic": 0,
          "searchPaid": 0,
          "direct": 0,
          "genAi": 0,
          "affiliate": 0,
          "displayAds": 0
        },
        "trafficSourceTrends": {
          "direct": {
            "2026-04-01": 0,
            "2026-05-01": 0,
            "2026-06-01": 0
          },
          "search": {
            "2026-04-01": 0,
            "2026-05-01": 0,
            "2026-06-01": 0
          },
          "social": {
            "2026-04-01": 0,
            "2026-05-01": 0,
            "2026-06-01": 0
          },
          "referrals": {
            "2026-04-01": 0,
            "2026-05-01": 0,
            "2026-06-01": 0
          },
          "paidReferrals": {
            "2026-04-01": 0,
            "2026-05-01": 0,
            "2026-06-01": 0
          },
          "mail": {
            "2026-04-01": 0,
            "2026-05-01": 0,
            "2026-06-01": 0
          },
          "other": {
            "2026-04-01": 0,
            "2026-05-01": 0,
            "2026-06-01": 0
          }
        },
        "topKeywords": [
          {
            "name": "convert html to url online free",
            "estimatedValue": 90,
            "volume": 340,
            "cpc": null
          },
          {
            "name": "htmltourl",
            "estimatedValue": 70,
            "volume": 160,
            "cpc": null
          },
          {
            "name": "permanent html code to website link converter free",
            "estimatedValue": 50,
            "volume": 240,
            "cpc": null
          },
          {
            "name": "html в url",
            "estimatedValue": 50,
            "volume": 60,
            "cpc": null
          },
          {
            "name": "html code to url converter",
            "estimatedValue": 40,
            "volume": 110,
            "cpc": null
          }
        ],
        "topRegions": [
          {
            "country": 356,
            "name": "India",
            "value": 0.6081085218092226
          },
          {
            "country": 840,
            "name": "United States",
            "value": 0.3630825938044913
          },
          {
            "country": 586,
            "name": "Pakistan",
            "value": 0.028808884386285635
          }
        ],
        "aiTraffic": {
          "trends": []
        }
      }
    },
    "complete": {
      "status": "DONE",
      "duration": 64
    }
  },
  "domain": "htmltourl.com",
  "fetchedAt": "2026-08-02T10:43:21.022Z",
  "ok": true,
  "raw": "event: whois\ndata: {...}\n\nevent: traffic\ndata: {...}\n\nevent: complete\ndata: {...}\n\n",
  "source": "aitdk",
  "status": 200
}
Server-side signing

Callers only need PXANY_API_KEY and domain. PXAny generates the AITDK nonce, timestamp, and signature on the server.

GET/v1/product-hunt/daily-products
需要密钥

Product Hunt

每天通过 Product Hunt 官方 v2 GraphQL API 拉取指定日期的全部产品， 重点返回每个产品的官网 URL。

查询参数

dateYYYY-MM-DD / 可选

要同步的日期；不传时使用当前 UTC 日期。接口会转换成当天00:00:00.000Z 到 23:59:59.999Z 的查询范围。

featuredboolean / 可选

不传时返回 Product Hunt API 在该日期范围内可见的全部 posts； 传 true 时只取 featured 产品。

cURL
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/product-hunt/daily-products?date=2026-08-01"
返回字段

每个产品包含 productUrl、productHuntUrl、name、slug、tagline、votesCount 和 commentsCount。

服务端密钥

Product Hunt developer token 保存在 API Accounts 的product_hunt账号中，调用方仍然只发送PXANY_API_KEY。

上游来源

该接口调用Product Hunt API v2的 GraphQL 入口；字段按官方 posts 查询封装，按 postedAfter / postedBefore过滤指定日期。

GET/v1/url-redirect
需要密钥

URL 重定向解析

跟随 HTTP 跳转和页面 Meta Refresh，返回最终网页地址、 规范化域名以及完整跳转链。

查询参数

urlstring / 必填

需要解析的 HTTP 或 HTTPS URL，最长 2048 个字符。 参数应进行 URL 编码。

cURL
curl --fail-with-body --get \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  --data-urlencode "url=https://httpbin.org/redirect/1" \
  "https://api.pxany.com/v1/url-redirect"
响应示例
{
  "canonical": null,
  "checkedAt": "2026-08-06T00:00:00.000Z",
  "contentType": "application/json",
  "domain": "httpbin.org",
  "finalUrl": "https://httpbin.org/get",
  "inputUrl": "https://httpbin.org/redirect/1",
  "loopDetected": false,
  "redirectCount": 1,
  "redirects": [
    {
      "durationMs": 1004,
      "from": "https://httpbin.org/redirect/1",
      "statusCode": 302,
      "to": "https://httpbin.org/get",
      "type": "http"
    }
  ],
  "server": "cloudflare",
  "statusCode": 200,
  "totalDurationMs": 1920,
  "warnings": [],
  "xRobotsTag": null
}

错误响应

400 / 401请求错误

URL 不合法、目标为本地地址，或者 API Key 无效。

429 / 502 / 503 / 504上游错误

直连目标或备用重定向服务限流、返回异常、不可用或请求超时。

鉴权和实现

调用方只发送 PXANY_API_KEY。PXAny 先在服务端直接跟踪 公开 HTTP(S) 跳转；直连请求失败或结果不可用时，再依次串行调用 RedirectCheck 和 Unshortened。优秀新站的 Product Hunt URL 解析也复用同一逻辑。

GET/v1/serp
需要密钥

Serp 搜索代理

通过 PXAny 私有 SerpAPI 账号池代理 Google 搜索。

查询参数

qstring / 必填

搜索词，不能为空。

gl / hl / start / num / safe可选

Google 地区、语言、分页、数量和安全搜索参数。

cURL
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/serp?q=best+espresso+beans&gl=us&hl=en&num=10&start=0&safe=off"
参数限制

请求中不能传 api_key、engine、output；这些字段由 PXAny 接管。

GET/v1/trends
需要密钥

Google Trends

复用 API Accounts 中启用的 SerpAPI 账号池，查询趋势曲线、地区热度、相关查询和相关主题。

请求头使用 Authorization: Bearer <PXANY_API_KEY>。PXAny 在服务端选择账号，固定 engine=google_trends 和 output=json。

查询参数

qstring / 必填

搜索词或 Topic ID，以英文逗号分隔；每项 1–100 个字符。TIMESERIES 支持 1–5 项，GEO_MAP 支持 2–5 项，其余类型只接受 1 项。

data_typestring / 默认 TIMESERIES

TIMESERIES：趋势曲线；GEO_MAP：多个词的地区对比；GEO_MAP_0：单个词的地区热度；RELATED_QUERIES：相关查询；RELATED_TOPICS：相关主题。

geo / date / hl可选

地区（如 US，空值为全球）、时间范围（如 today 12-m、now 7-d、all 或 yyyy-mm-dd yyyy-mm-dd）、语言（如 en、zh-cn）。省略时使用上游默认值；TIMESERIES 的多地区和多日期范围遵守上游规则。

tz / cat / gprop / region可选

时区偏移分钟数（-1439 到 1439）、Trends 类别 ID、搜索类型（空值为网页，或 images/news/froogle/youtube）、地区粒度（COUNTRY/REGION/DMA/CITY，仅地区热度类型使用）。具体组合由上游校验。

csv / include_low_search_volume / no_cacheboolean / 可选

仅接受 true 或 false。csv 将 CSV 结果作为数组放入 JSON；include_low_search_volume 用于地区热度；no_cache=true 同时跳过 PXAny 与 SerpAPI 缓存。

async可选 / 仅 false

当前仅支持同步请求。不能传 api_key、engine、output；其他查询参数透传给 SerpAPI。

手动请求：趋势对比与相关词
curl --fail-with-body --get "https://api.pxany.com/v1/trends" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  --data-urlencode "q=coffee,tea" \
  --data-urlencode "data_type=TIMESERIES" \
  --data-urlencode "geo=US" \
  --data-urlencode "date=today 12-m"

curl --fail-with-body --get "https://api.pxany.com/v1/trends" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  --data-urlencode "q=coffee" \
  --data-urlencode "data_type=RELATED_QUERIES"

响应示例

返回上游 JSON 和状态码。以下是结构示例，实际数据随 data_type 变化：趋势为 interest_over_time，地区对比为 compared_breakdown_by_region，单词地区为 interest_by_region，相关查询为 related_queries，相关主题为 related_topics。

200 JSON 结构示例
{
  "search_metadata": {
    "status": "Success"
  },
  "search_parameters": {
    "engine": "google_trends",
    "q": "coffee,tea",
    "data_type": "TIMESERIES",
    "geo": "US",
    "date": "today 12-m"
  },
  "interest_over_time": {
    "timeline_data": []
  }
}

所有响应附带 cache-control: no-store 和 x-request-id；上游响应另有 x-pxany-serp-account-id，表示本次账号或缓存来源账号。

错误响应

参数无效返回 400，PXAny 密钥缺失或错误返回 401，无启用账号返回 503，内部异常返回 500；这些本地错误使用 application/problem+json。上游错误保留原状态码和 JSON（例如 429 额度耗尽、502 网络失败）；调用方也应检查上游 error 和 search_metadata.status。

400 参数错误
{
  "type": "https://api.pxany.com/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "q is required.",
  "requestId": "example-request-id"
}
429 上游错误示例
{"error":"Searches quota exceeded"}
账号池与缓存

复用搜索接口的健康、额度及最近使用时间排序，遇到 401/402/403/429 或网络失败时换号重试。共享缓存存储可用时，成功结果缓存 1 小时，并与普通搜索隔离；缓存不可用时直接回源。参数说明见 SerpAPI 官方文档。

POST/v1/sites
需要密钥

创建标准站点

鉴权：Authorization: Bearer <PXANY_API_KEY>。复用后台标准站点创建逻辑，返回 201 JSON 和 Cache-Control: no-store。

JSON 请求体

name：必填非空字符串。domain：必填非空字符串，接受裸域名或 HTTPS URL，由现有站点模块规范化。

websiteUrl：domain 缺省时使用的字符串别名；同时传入时优先 domain。不单独存储，目标网址由规范化域名派生为 https://{domain}。

可选字段：cloudflareDeploymentUrl 为 HTTPS 部署 URL 字符串或 null；githubRepository 为 HTTPS GitHub 仓库 URL 字符串或 null；isPinned 为 boolean，默认 false；status 为 active 或 inactive，默认 active。

可选 Analytics：ga4PropertyId 为数字字符串或 null，允许 properties/ 前缀，拒绝 G- Measurement ID；reportEnabled 为 boolean，默认 true；syncEnabled 为 boolean，默认 false，启用时必须提供 GA4 Property ID；timezone 为字符串，默认 Asia/Shanghai。GSC 自动使用 sc-domain:域名，不接受 gscSiteUrl。

可选发布配置：productDescription（产品描述）、author（作者）、siteEmail（联系邮箱）、commentInstructions（外链评论要求）均为字符串或 null，去除首尾空白，空值保存为 null；anchorTexts 为字符串数组或换行/逗号分隔字符串，去除空白及重复项，默认空数组。省略的发布文本默认 null。不接受 logoUrl、websiteScreenshotUrl、shareImageUrl 或 profileMedia* 等自动媒体字段。

cURL
curl -X POST 'https://api.pxany.com/v1/sites' \
  -H 'Authorization: Bearer <PXANY_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Flying Broom AI","domain":"flyingbroomai.com","productDescription":"AI writing assistant","ga4PropertyId":"123456789","author":"Alex","siteEmail":"hello@example.com","anchorTexts":["AI writing","writing assistant"]}'
201 JSON
{
  "ok": true,
  "site": {
    "id": 1,
    "name": "Flying Broom AI",
    "domain": "flyingbroomai.com",
    "slug": "flyingbroomai.com",
    "status": "active",
    "isPinned": false,
    "cloudflareDeploymentUrl": null,
    "githubRepository": null,
    "domainRating": null,
    "domainRatingErrorMessage": null,
    "domainRatingFetchedAt": null,
    "domainRatingLicense": null,
    "productDescription": "AI writing assistant",
    "author": "Alex",
    "siteEmail": "hello@example.com",
    "commentInstructions": null,
    "anchorTexts": [
      "AI writing",
      "writing assistant"
    ],
    "ga4PropertyId": "123456789",
    "gscSiteUrl": "sc-domain:flyingbroomai.com",
    "lastSyncedAt": null,
    "logoUrl": "https://www.google.com/s2/favicons?domain=flyingbroomai.com&sz=128",
    "reportEnabled": true,
    "syncEnabled": false,
    "timezone": "Asia/Shanghai"
  }
}

错误：400 Invalid request（JSON 无效、字段缺失、类型或值无效）；401 缺少或无效 Bearer 密钥；409 域名已存在；500 内部错误。均使用 application/problem+json，包含 status、title、detail、requestId、type。重复创建不会新建站点。

409 JSON
{
  "status": 409,
  "title": "Conflict",
  "detail": "A site with this domain already exists.",
  "requestId": "example-request-id",
  "type": "https://api.pxany.com/errors/conflict"
}
GET/v1/sites/lookup
需要密钥

按域名查询标准站点

鉴权：Authorization: Bearer <PXANY_API_KEY>。必填查询参数 domain 接受域名或 HTTP(S) URL，去除协议、www、端口、路径及查询并转小写。结果包含 active 和 inactive 站点，返回 200 JSON，Cache-Control: no-store。

cURL
curl --get 'https://api.pxany.com/v1/sites/lookup' \
  -H 'Authorization: Bearer <PXANY_API_KEY>' \
  --data-urlencode 'domain=https://www.example.com/path'
200 JSON
{
  "site": {
    "id": 1,
    "name": "Example",
    "domain": "example.com",
    "status": "inactive"
  }
}

错误：400 域名缺失或无效；401 密钥无效；404 站点不存在；409 多条站点匹配；500 内部错误。错误使用 application/problem+json。

404 JSON
{
  "status": 404,
  "title": "Not found",
  "detail": "Site not found.",
  "requestId": "example-request-id",
  "type": "https://api.pxany.com/errors/not-found"
}
PATCH/v1/sites/{siteId}
需要密钥

更新标准站点状态

鉴权：Authorization: Bearer <PXANY_API_KEY>。路径参数 siteId 必须为正整数；JSON 请求体仅允许必填 status，值为 active 或 inactive。返回 200 JSON，Cache-Control: no-store。

cURL
curl -X PATCH 'https://api.pxany.com/v1/sites/1' \
  -H 'Authorization: Bearer <PXANY_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"status":"inactive"}'
200 JSON
{
  "site": {
    "id": 1,
    "name": "Example",
    "domain": "example.com",
    "status": "inactive"
  }
}

错误：400 ID 或请求体无效；401 密钥无效；404 站点不存在；500 内部错误。错误使用 application/problem+json。

404 JSON
{
  "status": 404,
  "title": "Not found",
  "detail": "Site not found.",
  "requestId": "example-request-id",
  "type": "https://api.pxany.com/errors/not-found"
}
GET/v1/landing-pages
需要密钥

读取站点内页 URL 结构

鉴权：Authorization: Bearer <PXANY_API_KEY>。必填查询参数 siteId 为正整数。只读，返回 200 JSON，Cache-Control: no-store。

返回该站已登记页面组成的 URL 树（深度优先，父页面为最近的已登记上级路径，/ 为首页根节点）。每个节点包含 pageId、url、path、depth、parentPageId、status（draft / published / indexed / ranking）、页面用途 pageType（ranking 排名页 / index 索引页 / other 其他页）、词群 groupId / groupName、coreKeyword、parentMismatch（词群上级与 URL 上级不一致）以及 gsc：近 28 天曝光、点击、按曝光加权的平均排名和前 5 个查询词，没有数据时为 null。排名页一定绑定词群；索引页默认不绑定（groupId 为 null），只有例外绑定时才有词群，此时要按排名页写内容；其他页不绑定词群。同一站点内一个关键词只属于一个页面。未绑定页面的词群列在 unboundGroups。Agent 选词、定 URL 和加内链时以此为准。

cURL
curl --get 'https://api.pxany.com/v1/landing-pages' \
  -H 'Authorization: Bearer <PXANY_API_KEY>' \
  --data-urlencode 'siteId=1'
200 JSON
{
  "site": {
    "id": 1,
    "domain": "example.com"
  },
  "nodes": [
    {
      "pageId": 10,
      "url": "/",
      "path": "/",
      "depth": 0,
      "parentPageId": null,
      "status": "ranking",
      "pageType": "ranking",
      "groupId": 1,
      "groupName": "home",
      "coreKeyword": "ai sticker maker",
      "parentMismatch": false,
      "gsc": {
        "impressions": 3200,
        "clicks": 85,
        "position": 12.4,
        "topQueries": [
          {
            "query": "ai sticker maker",
            "impressions": 1900,
            "clicks": 60,
            "position": 8.1
          }
        ]
      }
    },
    {
      "pageId": 11,
      "url": "/stickers",
      "path": "/stickers",
      "depth": 1,
      "parentPageId": 10,
      "status": "indexed",
      "pageType": "index",
      "groupId": null,
      "groupName": null,
      "coreKeyword": null,
      "parentMismatch": false,
      "gsc": null
    },
    {
      "pageId": 12,
      "url": "/stickers/cat",
      "path": "/stickers/cat",
      "depth": 2,
      "parentPageId": 11,
      "status": "draft",
      "pageType": "ranking",
      "groupId": 2,
      "groupName": "cat stickers",
      "coreKeyword": "cat stickers",
      "parentMismatch": false,
      "gsc": null
    }
  ],
  "unboundGroups": []
}

错误：400 siteId 缺失或无效；401 密钥无效；404 站点不存在；500 内部错误。错误使用 application/problem+json。

404 JSON
{
  "status": 404,
  "title": "Not found",
  "detail": "Site not found.",
  "requestId": "example-request-id",
  "type": "https://api.pxany.com/errors/not-found"
}
PATCH/v1/landing-pages/{pageId}
需要密钥

更新内页上线 URL 与状态

鉴权：Authorization: Bearer <PXANY_API_KEY>。路径参数 pageId 必须为正整数。JSON 请求体只允许 status 和 url，至少提供一个。用于 Codex / Agent 在页面上线后把页面标为 published 并写入线上地址。返回 200 JSON，Cache-Control: no-store。

status：draft、published、indexed 或 ranking。indexed 与 ranking 通常由每天一次的 GSC 判断自动推进（有曝光为 indexed，核心词平均排名进入前 30 为 ranking，只升不降，不改 draft）。url：站内相对路径或该站域名下的 http(s) 地址（忽略 www），统一保存为不带结尾斜杠的路径；属于其他站点返回 400，与本站其他页面重复返回 409。

cURL
curl -X PATCH 'https://api.pxany.com/v1/landing-pages/12' \
  -H 'Authorization: Bearer <PXANY_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"status":"published","url":"https://example.com/stickers/cat"}'
200 JSON
{
  "page": {
    "pageId": 12,
    "siteId": 1,
    "status": "published",
    "url": "/stickers/cat"
  }
}

错误：400 ID、请求体、状态或 URL 无效；401 密钥无效；404 页面不存在；409 本站已有页面使用该 URL；500 内部错误。错误使用 application/problem+json。

409 JSON
{
  "status": 409,
  "title": "Conflict",
  "detail": "Another page already uses /stickers/cat on this site.",
  "requestId": "example-request-id",
  "type": "https://api.pxany.com/errors/conflict"
}
GET/v1/domains/check
需要密钥

实时域名可用性查询

鉴权：Authorization: Bearer <PXANY_API_KEY>。返回不包装的 JSON 数组，Cache-Control: no-store；所有后缀并发查询。优先 RDAP，失败或不支持时通过 TCP 43 查询注册局 WHOIS。每次请求超时 8 秒并重试一次；仅 IANA RDAP 引导数据缓存 7 天。

查询参数

q 必填。完整域名只检查自身，支持 example.co.uk，tld 为第一个标签之后的部分；否则转小写并移除非 [a-z0-9-] 字符，例如 broom riding ai → broomridingai。标签必须为 1–63 字符，不能以连字符开头或结尾。

tlds 可选，逗号分隔，去掉首尾点，覆盖默认后缀并去重，支持 co.uk；完整域名忽略此参数。

默认后缀：com net org ai io app co me xyz dev tech tools tool online site website pro art video studio design photo photos pics gallery cc so to gg ly sh fm tv im vip fun lol live top cloud info biz us。

cURL
curl --get 'https://api.pxany.com/v1/domains/check' \
  -H 'Authorization: Bearer <PXANY_API_KEY>' \
  --data-urlencode 'q=broom riding ai' \
  --data-urlencode 'tlds=com,io,co.uk'
200 JSON
[
  {
    "domain": "example.com",
    "tld": "com",
    "status": "taken",
    "registered_at": "1995-08-14T04:00:00.000Z",
    "registrar": "Example Registrar",
    "source": "rdap"
  }
]

status 为 available / taken / unknown；registered_at 为 ISO UTC 日期或 null；registrar 为注册商或 null；source 为 rdap / whois / null。无法明确判定时返回 unknown，不猜测。查询可用不保证可以购买。

错误：400 参数无效，401 缺少或无效密钥，500 内部错误，均使用 application/problem+json。上游失败按域名返回 unknown（HTTP 200）。

400 JSON
{
  "detail": "q must produce a valid domain label of 1–63 characters, without leading or trailing hyphens.",
  "requestId": "example-request-id",
  "status": 400,
  "title": "Invalid request",
  "type": "https://api.pxany.com/errors/invalid-request"
}
POST/v1/url-content
需要密钥

URL 内容提取

抓取指定页面，并返回适合 Agent 消费的 Markdown 内容。遇到 Cloudflare 等验证页会返回 422，不会把验证页伪内容当作成功正文。

JSON 请求体

urlstring / 必填

需要抓取的 HTTP 或 HTTPS URL，最长 2048 个字符。

cURL
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/url-content" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://example.com"
  }'

该公共接口不会调用所有者 Chrome。仅 `/publishing` 的内部读取流程会在 Browser Run 被验证页拦截后，通过 Chrome2CF 进行人工可见的浏览器兜底。

POST/v1/keyword-volumes
需要密钥

关键词搜索量

生成 Google Ads 关键词历史指标和逐月搜索量。

JSON 请求体

keywordsstring[] / 必填

至少一个非空关键词，重复项会被移除。

geoTargetId / languageIdstring / 必填

Google Ads 地理位置和语言常量 ID；可使用 ALL。

keywordPlanNetwork / batchSize可选

网络类型和批量大小。

cURL
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/keyword-volumes" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "keywords": ["<KEYWORD_1>", "<KEYWORD_2>"],
    "geoTargetId": "<GEO_TARGET_ID>",
    "languageId": "<LANGUAGE_ID>",
    "keywordPlanNetwork": "GOOGLE_SEARCH",
    "batchSize": 100
  }'
GET / POST/v1/chrome2cf/*
需要密钥

chrome2cf 采集通道

PXAny 内置的浏览器/扩展采集通道。它负责连接 owner 侧 collector、排队任务和回收结果；当前支持 Semrush keyword_metrics、Google intitle 结果数，以及由 publishing 模块在用户手动确认或已开启的自动发布设置下派发的publishing.substack.publish.v1 / publishing.substack.verify.v1，以及 owner 自用的chatgpt 页面任务。旧的/semrush-keyword 网关路径已退役。

接口

GET /v1/chrome2cf/statuscollector 状态

返回当前 collector 连接状态和 Durable Object 队列计数。

GET /v1/chrome2cf/jobs/{jobId}任务查询

按任务 ID 查询 queued、running、succeeded 或 failed 状态。

POST /v1/chrome2cf/keyword-metricsSemrush 指标

提交 keyword_metrics 采集任务。PXAny 的 one-minute cron 会自动用它处理数据库里的 pending keyword jobs；这个接口主要用于手动验证 collector 链路。

POST /v1/chrome2cf/intitleGoogle intitle

提交 google_intitle 任务。collector 会新开一个后台标签页， 使用 intitle:"关键词" 执行 Google 精确短语搜索， 读取 Google 显示的近似结果数，然后关闭该任务标签页。新版扩展遇到 Google 人机验证或同意页时，会在后台保留原标签页，不切换当前页面，等待所有者手动完成；每秒检查页面一次，通过后继续查询。最多等待 20 分钟，超时保留标签页并返回失败，绝不把验证失败写成结果数 0。

POST /v1/chrome2cf/chatgptChatGPT 页面任务

接受 1–20,000 个字符的原始 prompt，每次在后台新建chatgpt.com 标签页和会话。结果可能包含文字、最多 4 张私有图片，或两者混合；拒绝文字也算正常文字输出。 任务必须轮询，queued/running 不含 success，只有存在可读取文字或成功保存图片时终态才为 success:true。

PUT/GET /v1/chrome2cf/jobs/{jobId}/images/{index}私有图片

扩展只上传 PNG、JPEG 或 WebP（每张不超过 16 MiB，索引 1–4）。下载始终需要 Bearer 密钥，不生成公开 URL。PUT 只验证任务仍在 running；终态结果和 GET 才验证图片输出引用。 部分图片失败会留在 warnings 中，只要仍有其他输出任务就算成功。

ChatGPT 参数、轮询与错误

prompt必填

去除首尾空白后必须为 1–20,000 个字符；发送时不追加“生成图片”等包装文字。

Idempotency-Key可选

1–128 个可打印 ASCII 字符。相同 Key 和提示词返回原任务；换提示词返回 409。服务端只保存 Key 的 SHA-256。

success终态字段

queued/running 不返回；succeeded 且至少有文字或图片为 true，失败或没有可用输出为 false。

chatgpt_login_required / chatgpt_captcha / chatgpt_request_blocked / chatgpt_rate_limited / chatgpt_page_changed / chatgpt_timeout稳定错误码

页面未登录、可见验证码、接口暂时拒绝、请求频率受限、页面结构变化、十分钟超时，以及图片捕获/上传失败都会以稳定 code 返回；接口拒绝或限流会暂停新 ChatGPT 任务十分钟，错误中不会包含提示词或页面全文。

ChatGPT 页面执行前提与边界

建议安装 pxany-extension/0.3.24，并由已连接的 owner collector 声明 chatgpt.page.v1。用户需要先在 Chrome 中自然登录 ChatGPT；登录或 CAPTCHA 时停止任务并保留诊断页，不尝试绕过。 插件在后台任务标签页中复用已登录页面的请求客户端。页面模块或响应结构变化可能返回 chatgpt_page_changed，不是官方 API SLA。

ChatGPT 会话请求在已登录页面内执行，页面凭据不传入 PXAny。文字和图片消耗用户自己的 ChatGPT 账户额度；PXAny 不承诺订阅额度可稳定变成第三方 API 配额。 API 调用者不会收到 Cookie、Token 或页面内部请求。

ChatGPT cURL
# 页面驱动的 ChatGPT 通用任务；提示词原样发送，不是 OpenAI 官方 API。
curl --fail-with-body -X POST "https://api.pxany.com/v1/chrome2cf/chatgpt" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: local-demo-001" \
  --data '{"prompt":"生成一段关于未来城市的简短介绍"}'

# 轮询 Location 或 pollUrl，直到 succeeded / failed。
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/chrome2cf/jobs/<CHATGPT_JOB_ID>"

# 图片结果通过同一个 Bearer 密钥下载，不能把 URL 当成公开地址。
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/chrome2cf/jobs/<CHATGPT_JOB_ID>/images/1" --output chatgpt-1.png
ChatGPT 终态响应
{
  "id": "chatgpt:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "object": "chrome2cf.chatgpt.task",
  "status": "succeeded",
  "success": true,
  "data": {
    "outputs": [
      {
        "type": "text",
        "text": "未来城市在清洁能源与立体交通中保持安静而高效。"
      },
      {
        "type": "image",
        "contentType": "image/png",
        "url": "https://api.pxany.com/v1/chrome2cf/jobs/chatgpt%3A0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef/images/1"
      }
    ],
    "warnings": [],
    "conversationUrl": "https://chatgpt.com/c/example-conversation"
  },
  "error": null,
  "createdAt": 1788240000000,
  "startedAt": 1788240000100,
  "finishedAt": 1788240012000,
  "pollUrl": "/v1/chrome2cf/jobs/chatgpt%3A0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

插件通过 PUT /v1/chrome2cf/jobs/{id}/images/{index} 上传图片，使用相同的 Bearer 鉴权。任务必须正在执行，index 为 1–4，Content-Type 为 image/png、image/jpeg 或 image/webp，请求体为图片二进制，最大 16 MiB。相同任务、序号、类型及完全相同的字节可重复上传以恢复丢失的确认响应；不同图片返回 409，已有文件不会被覆盖。成功响应包含 contentType、index、size；类型错误返回 415，超限返回 413，存储异常返回 503。

图片上传手动请求
curl -X PUT "https://api.pxany.com/v1/chrome2cf/jobs/chatgpt%3AEXAMPLE/images/1" -H "Authorization: Bearer YOUR_PXANY_API_KEY" -H "Content-Type: image/png" --data-binary @image.png
# 成功示例：{"contentType":"image/png","index":1,"size":1024}

intitle 参数与错误

keyword必填

1–200 个字符；接口会把它作为精确短语放入 intitle 查询。

400 / 401 / 404HTTP 错误

分别表示参数无效、Bearer 密钥无效和任务不存在。collector 离线、Google 超时、验证等待超时或页面无法解析会体现在任务的 failed 状态与 error 字段中。验证等待期间任务保持 running，data.progress 为 google_verification_required；通过后自动继续。

状态 cURL
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/chrome2cf/status"
状态响应
{
  "ok": true,
  "service": "pxany.chrome2cf",
  "status": {
    "activeCollector": {
      "connectedAt": 1785936000000,
      "nodeId": "collector-main",
      "status": "idle",
      "version": "1.0.0"
    },
    "queue": {
      "queued": 0,
      "running": 0,
      "succeeded": 12,
      "failed": 1
    }
  }
}
关键词任务 cURL
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/chrome2cf/keyword-metrics" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "keywords": ["ai website builder", "html to url"],
    "waitMs": 10000
  }'
关键词任务响应
{
  "id": "7e7d5d51-8a1f-4574-9c46-767c6f21f3fb",
  "action": "keyword_metrics",
  "status": "succeeded",
  "payload": {
    "keywords": ["ai website builder", "html to url"]
  },
  "data": {
    "data": [
      {
        "keyword": "ai website builder",
        "success": true,
        "volume": 2900,
        "kd": 47,
        "cpc": 3.21
      }
    ]
  },
  "error": null,
  "createdAt": 1785936000000,
  "updatedAt": 1785936001200,
  "startedAt": 1785936000100,
  "finishedAt": 1785936001200,
  "nodeId": "collector-main"
}
intitle cURL
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/chrome2cf/intitle" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "keyword": "ai website builder"
  }'
intitle 响应
{
  "id": "17374851-9658-4fa7-a152-5b2de63dbfeb",
  "action": "google_intitle",
  "status": "succeeded",
  "payload": {
    "keyword": "ai website builder"
  },
  "data": {
    "source": "google",
    "keyword": "ai website builder",
    "query": "intitle:\"ai website builder\"",
    "intitleCount": 12500,
    "resultStats": "About 12,500 results (0.31 seconds)",
    "searchUrl": "https://www.google.com/search?q=intitle%3A%22ai+website+builder%22&hl=en&filter=0&pws=0",
    "collectedAt": "2026-08-10T08:30:01.200Z"
  },
  "error": null,
  "createdAt": 1786350600000,
  "updatedAt": 1786350601200,
  "startedAt": 1786350600100,
  "finishedAt": 1786350601200,
  "nodeId": "pxany-extension"
}
GET / POST/v1/publishing/deliveries/{id}
需要密钥

Substack、Medium 与 Beehiiv 内容发布

通过 Chrome2CF 浏览器任务将后台已经冻结的素材发布到 Substack、Medium 个人主页或 Beehiiv 网页。可手动派发，也可由全局自动发布设置按当天排期派发；订阅邮件固定关闭且不发送 App 通知。插件接口只读取已经由后台派发的任务，没有公开的生成或发布触发接口。自动派发同样要求渠道能力、一次性提交许可及提交后的只读核验。后台操作统一在 内容发布。

鉴权、方法与参数

三个接口均发送 Authorization: Bearer <PXANY_API_KEY>，返回 Cache-Control: no-store。路径 id 是 PXAny Delivery UUID，不是渠道平台的远端 ID。

POST /v1/publishing/deliveries/{id}/startJSON

插件实际开始执行时提交精确 jobId。Delivery 此前保持 queued 且没有租约；成功后才变为 publishing、attempt 加一并开始十分钟租约。同一活动 jobId 可幂等重试，旧任务或不匹配任务返回 409。

GET /v1/publishing/deliveries/{id}冻结文稿

兼容读取活动中的冻结文稿。共同字段为标题、段落、来源 URL、publication 和三张有序私有图片。Medium 另有可选 subtitle、0–5 个 tags 与 paywall=false；Substack 省略这些字段。sendEmail 固定 false，audience 固定 everyone；不返回凭据、Cookie、原始资料快照或可变渠道配置。

GET /v1/publishing/deliveries/{id}/assets/{kind}图片字节

kind 固定为 cover、infographic 或 website_screenshot。成功响应是 image/png 或 image/jpeg，最大 8 MiB。插件后台携带 Bearer 下载后粘贴到相应渠道；不能把密钥放入 URL，也不能在公开文章中引用这个私有图片接口。

POST /v1/publishing/deliveries/{id}/checkpointJSON

必填 jobId 和 stage。stage=draft 时必填 draftId、draftUrl；stage=committing 使用已保存草稿；stage=confirmed 时必填 remoteId、remoteUrl。draft URL 必须是该 Delivery 对应渠道的草稿，public URL 必须是同一 publication 或 Medium 个人主页下的已公开文章；不接收任意脚本。

一次性许可与恢复

每个 checkpoint 必须匹配当前已派发任务。committing 检查任务所有权和十分钟租约，只有首次成功响应的 clickAllowed=true 才能点击一次。它不读取自动开关、发布日期或排期。重复请求返回 409；最终提交后只能核验，不重新领许可或点击；响应丢失、断线或超时也遵循这一边界。confirmed 必须基于实际公开页面、正文和图片核验，相同确认结果重复回报可成功。

发布配置按渠道定义字段，字段值从素材包选择。Substack 首次分发冻结标题、段落、来源网址，以及固定顺序的封面图、信息图、网站截图。Medium 个人主页首次分发还冻结 subtitle、0–5 tags 与 free paywall=false。三个渠道都要求三张图按 cover、infographic、website_screenshot 顺序完整；缺少任意一张都会阻止发布。

文稿 / 图片 cURL
# 用现有任务的真实 delivery ID 替换 <DELIVERY_ID>；这里只读取，不触发发布。
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/publishing/deliveries/<DELIVERY_ID>"

curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/publishing/deliveries/<DELIVERY_ID>/assets/infographic" --output infographic.png
文稿响应（直接 DTO）
{
  "id": "a390d5a5-f0fd-4bd8-97da-a69a9b6b292a",
  "jobId": "publishing:substack:a390d5a5-f0fd-4bd8-97da-a69a9b6b292a:1",
  "publicationUrl": "https://example.substack.com",
  "title": "A practical tool introduction",
  "paragraphs": [
    "A source-grounded introduction to the product."
  ],
  "sourceUrl": "https://example.com/product",
  "images": [
    {
      "kind": "cover",
      "path": "/v1/publishing/deliveries/a390d5a5-f0fd-4bd8-97da-a69a9b6b292a/assets/cover",
      "altText": "Product cover",
      "caption": ""
    },
    {
      "kind": "infographic",
      "path": "/v1/publishing/deliveries/a390d5a5-f0fd-4bd8-97da-a69a9b6b292a/assets/infographic",
      "altText": "Product workflow",
      "caption": "Key workflow"
    },
    {
      "kind": "website_screenshot",
      "path": "/v1/publishing/deliveries/a390d5a5-f0fd-4bd8-97da-a69a9b6b292a/assets/website_screenshot",
      "altText": "Product website",
      "caption": "Official website"
    }
  ],
  "contentPackage": {
    "title": "A practical tool introduction",
    "shortText": "完整独立短文，用于需要短内容的分发渠道；长文仍由 blocks 表示。",
    "excerpt": "A source-grounded introduction to the product.",
    "seoTitle": "A practical tool introduction",
    "seoDescription": "How this practical tool works and who it helps.",
    "socialShort": "A practical tool introduction in one minute.",
    "socialMedium": "A practical tool introduction with the key takeaways.",
    "tags": [
      "tools",
      "workflow"
    ],
    "blocks": [
      {
        "type": "heading",
        "level": 2,
        "text": "A practical tool introduction"
      }
    ],
    "images": [
      {
        "type": "cover",
        "slot": "cover",
        "prompt": "Editorial product illustration",
        "altText": "Product illustration",
        "caption": "Cover illustration"
      }
    ],
    "sourceUrl": "https://example.com/product",
    "sourceFetchedAt": "2026-08-30T00:00:00.000Z",
    "audio": [],
    "video": []
  },
  "draftId": null,
  "draftUrl": null,
  "commitStartedAt": null,
  "sendEmail": false,
  "audience": "everyone"
}

自动领取在数据库内原子检查同一目标、同一渠道所有素材版本的 Delivery 历史。前置配置或素材校验失败会持久化 failed Delivery（AUTOMATIC_VALIDATION_FAILED），下一分钟继续其他候选，修复后须手动发布。Cron 的 dispatched 包含 queued 与 publishing；queued/running 不代表文章已公开。Chrome2CF 全局最多同时运行 6 个任务，每种任务类型最多运行 1 个，其余按可执行 FIFO 排队；队首类型繁忙时不会阻塞其他空闲类型。状态接口只返回总数和 byLane 数量，不返回任务 payload。

checkpoint 手动模拟（有状态写入）
# 以下是手动模拟格式，只能对已分配的测试任务按真实进度调用。
# start：插件实际开始执行时才领取十分钟租约；同一 jobId 的响应丢失可安全重试。
curl --fail-with-body -X POST   "https://api.pxany.com/v1/publishing/deliveries/<DELIVERY_ID>/start"   -H "Authorization: Bearer $PXANY_API_KEY" -H "Content-Type: application/json"   --data '{"jobId":"publishing:substack:<DELIVERY_ID>:<ATTEMPT>"}'

# draft：草稿已创建且 ID/URL 已核对后保存。
curl --fail-with-body -X POST \
  "https://api.pxany.com/v1/publishing/deliveries/<DELIVERY_ID>/checkpoint" \
  -H "Authorization: Bearer $PXANY_API_KEY" -H "Content-Type: application/json" \
  --data '{"jobId":"publishing:substack:<DELIVERY_ID>:<ATTEMPT>","stage":"draft","draftId":"12345","draftUrl":"https://example.substack.com/publish/post/12345"}'

# committing：会消耗一次性提交许可。不要重复请求，不要配置 curl --retry。
curl --fail-with-body -X POST \
  "https://api.pxany.com/v1/publishing/deliveries/<DELIVERY_ID>/checkpoint" \
  -H "Authorization: Bearer $PXANY_API_KEY" -H "Content-Type: application/json" \
  --data '{"jobId":"publishing:substack:<DELIVERY_ID>:<ATTEMPT>","stage":"committing"}'

# confirmed：只有已实际核验公开文章、正文和配图后才能回报。
curl --fail-with-body -X POST \
  "https://api.pxany.com/v1/publishing/deliveries/<DELIVERY_ID>/checkpoint" \
  -H "Authorization: Bearer $PXANY_API_KEY" -H "Content-Type: application/json" \
  --data '{"jobId":"publishing:substack:<DELIVERY_ID>:<ATTEMPT>","stage":"confirmed","remoteId":"12345","remoteUrl":"https://example.substack.com/p/practical-tool"}'
checkpoint 200 响应
draft:      {"clickAllowed":false,"status":"publishing"}
committing: {"clickAllowed":true,"status":"publishing"}
confirmed:  {"clickAllowed":false,"status":"published"}

错误响应

400：非法 UUID、JSON、参数或 URL；401：缺失或错误 Bearer；404：文章或图片不存在；409：旧 job、租约过期、并发操作、状态冲突或许可已领取；503：数据库、图片存储或发布执行器暂不可用。响应使用 application/problem+json，包含 status、title、detail、requestId；发布业务错误还带安全 code，不返回凭据或第三方原始错误。

409 示例
{
  "type": "https://api.pxany.com/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "当前任务或文章状态不允许此操作，请刷新后重试；已提交的文章只能重新核验。",
  "code": "STATE_CONFLICT",
  "requestId": "example-request-id"
}

c2CF 发布动作

Beehiiv 文稿另含 subtitle、seoDescription、publishToEmail=false、platform="web" 和 displayThumbnailOnWeb=false；渠道由任务 action 确定，文稿不额外携带 channel 字段。发布器保存并读回三图正文，确认无邮件收件人数且关闭社区发布，再领取最终提交许可。Beehiiv draftId 是 UUID，草稿地址为 https://app.beehiiv.com/posts/<UUID>/edit，成功地址必须为配置的 publicationUrl 下的 /p/<slug>。

插件握手声明 capabilities=["publishing.substack.publish.v1","publishing.substack.verify.v1","publishing.medium.publish.v1","publishing.medium.verify.v1","publishing.beehiiv.publish.v1","publishing.beehiiv.verify.v1"]；缺失时需要更新插件。publish 动作执行准备与一次性提交；verify 动作只核验，不写编辑器、不提交。三个渠道动作共用现有 WebSocket，最长十分钟；最终提交后断线不会自动重排发布。

Worker 发给插件的任务（示例期限已过，不能直接执行）
{
  "action": "publishing.substack.publish.v1",
  "id": "publishing:substack:a390d5a5-f0fd-4bd8-97da-a69a9b6b292a:1",
  "payload": {
    "deliveryId": "a390d5a5-f0fd-4bd8-97da-a69a9b6b292a",
    "postId": "9b4769e5-b784-4a63-9b78-dab4b775d574",
    "channel": "substack",
    "deadline": "2026-09-23T01:10:00.000Z"
  }
}
Medium Worker 任务（示例期限已过，不能直接执行）
{
  "action": "publishing.medium.publish.v1",
  "id": "publishing:medium:a390d5a5-f0fd-4bd8-97da-a69a9b6b292a:1",
  "payload": {
    "deliveryId": "a390d5a5-f0fd-4bd8-97da-a69a9b6b292a",
    "postId": "9b4769e5-b784-4a63-9b78-dab4b775d574",
    "channel": "medium",
    "deadline": "2026-09-23T01:10:00.000Z"
  }
}

任务 ID 格式为 publishing:<channel>:<deliveryUUID>:<attempt>，payload 必含 deliveryId、postId、channel，以及 Hub 在实际派发时生成的 deadline。verify 使用相同 payload，分别改为 publishing.substack.verify.v1 、publishing.medium.verify.v1 或 publishing.beehiiv.verify.v1。收到任务后先调用 start，再读取配图和调用 checkpoint；start 只是执行握手，不是公开发布触发入口。

c2CF 手动查询
# 发布动作只能由 publishing 模块调度；没有公开的提交发布任务接口。
# 读取执行器能力和已有任务状态：
curl --fail-with-body -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/chrome2cf/status"
curl --fail-with-body -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/chrome2cf/jobs/publishing:substack:<DELIVERY_ID>:<ATTEMPT>"

后台接口

PATCH /api/admin/publishing/settings 保存素材语言、AI 提示词、全局自动发布开关及 Asia/Shanghai 每日开始时间；PATCH /api/admin/publishing/channels/{channel} 独立保存指定渠道地址、language 与素材字段映射，POST channels/{channel}/preview 只读预览该映射的内容。POST /api/admin/publishing/targets 只接受网站 url；targets/{id}/prepare 每次对账同一个持久化 ChatGPT 生成任务，失败不会自动重投，retry-generation 才能在版本 CAS 通过后解锁新 attempt；posts/{id}/regenerate 会在安全 Delivery 前重新生成素材。posts/{id}/deliveries/{channel}/publish 手动派发冻结 Delivery，deliveries/{id}/sync 只同步已有插件任务，deliveries/{id}/verify 只核验已有 commit_started_at 的不确定提交。每分钟 Cron 最多自动处理一个当天到期、素材已就绪且没有 Delivery 历史的渠道；失败或结果未知不会自动重试。后台使用管理员 Cookie；修改请求必须同源，不接受公开 API 密钥代替登录。

GET/v1/extension/status
需要密钥

PXAny Chrome 扩展状态

用于测试扩展与 PXAny API 的公共连接，并返回当前可用模块。 当前返回 backlinks、chrome2cf 和on-page-seo-check。

参数

无GET

仅需要 Bearer 鉴权。

cURL
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/extension/status"
响应示例
{
  "name": "PXAny",
  "status": "ok",
  "modules": ["backlinks", "chrome2cf", "on-page-seo-check"]
}
POST / GET/v1/on-page-seo-check/v4/*
需要密钥

插件页面检查 v4：上线前验收

使用自己的 PXAny 检测引擎，参考哥飞公开规则；未公开的逐项权重和公式采用 PXAny 补充规则，不调用哥飞 API。请求统一发送 Authorization: Bearer <PXANY_API_KEY>。

POST /v1/on-page-seo-check/v4/runs：传 pageId 或一个 keyword，二者互斥。手动关键词无需登记站点或页面，响应 pageId、siteId 为 null。两种模式都必须提交 snapshot：pageUrl、html、contentType、responseStatus、responseTimeMs。html 为当前渲染后 DOM，UTF-8 上限2MB。可选 snapshot.rendered 提交工具可见性/首屏位置和图片尺寸证据。

可选 evidence 包含 document、robots、sitemaps（最多5个）及 sitemapComplete、xRobotsTag。每个资源含 url、status、contentType、text、redirected、durationMs、contentEncoding、error。只接受同源URL；document地址须匹配当前页（忽略锚点），robots路径须为 /robots.txt。原始HTML上限2MB，辅助资源各256KB；服务端不请求这些地址，原始正文不写入历史。

调试模式可选传 targetUrl（完整正式 URL，含路径）；不传即真实模式。snapshot.pageUrl 与 evidence 仍保留实际预览地址，服务端不会请求 targetUrl。Canonical、相对链接解析、内外链、关键词 URL 和 Sitemap 包含关系按正式 URL 判断；robots 与 Sitemap 内容采集自预览站，声明的正式域名 Sitemap 路径映射到预览站读取。报告 crawl.targetUrl 标识调试模式，requestedUrl/finalUrl 仍是采集地址，手动历史按正式 URL + 核心词查询。HTTPS 标记待补查，调试报告不会判为可上线；HTTP 状态、响应时间和跳转仅代表预览页。

Sitemap自动识别同协议、同端口、同路径和同查询参数的www／裸域名版本。完整URL一致且robots已声明时得2/2分；仅www版本不同时显示「已找到对应页面（www版本不同）」并提示统一地址，按警告得1/2分，evidence显示检测URL和实际匹配URL。不会改写targetUrl，不把其他路径、子域名或协议当作同一页，也不声称已验证正式站跳转。调试采集可把上述两种域名声明的Sitemap路径映射到预览站，实际请求和提交证据仍严格同源。

核心词 URL 项检查审核地址的域名与路径，域名中的完整关键词连写也可命中。例如 astrocartography chart 与 https://astrocartographychart.net/ 对应时该项为2/2分；查询参数、片段、顶级域名不计入。证据显示完整审核 URL；调试时使用 targetUrl，不改写原始页面内容，也不自动放宽品牌词要求。

GET /v1/on-page-seo-check/v4/history：传 pageId，或 url + keyword。手动历史按当前URL与规范化核心词隔离；GET /v1/on-page-seo-check/v4/runs/{runId} 查看完整报告。成功分别返回201或200；400参数错误、401密钥无效、404页面/报告不存在、422缺少核心词或页面5xx、503数据库暂不可用。

评分为 round(earned / possible × 100)，再取最低封顶；unknown（待补查）与 not_applicable（确实不适用）不计有效满分。scores 显示 earned、possible、coverage、unknownChecks 和 acceptance（ready / fix_required / incomplete）。只要仍有待补查项就不能当作完整验收通过。分类显示 score、weight、applicableWeight，每个检查项含 earned、证据和整改建议。

词数封顶75/55/35，聚焦度封顶65/45/25；noindex、robots屏蔽、HTTP错误封顶20，CSR空壳封顶40为PXAny补充规则。单词密度3%–5%，多词密度仅展示，不重复计分。所有者自定义验收项「核心词 · 同词数密度排名」占6分：N个单词检查N-GRAM，完整核心词第1或并列第1得6分，其余0分并判需修改；相同次数并列，排名来自完整统计，榜单展示前15条。当前支持1–5词，超出标待补查。品牌候选未核验SERP，不自动放宽。相关/长尾仅提示，不计总分；KGR/KD、词族密度合计、main存在、文本代码比、重复标题等不再计分。旧路径保留v3契约，历史版本不同不比较涨跌。

手动关键词模拟请求
curl --fail-with-body 'https://api.pxany.com/v1/on-page-seo-check/v4/runs' \
  -H 'Authorization: Bearer <PXANY_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{"keyword":"passport photo maker","snapshot":{"pageUrl":"http://localhost:3000/","html":"<html><body><h1>Passport photo maker</h1></body></html>","contentType":"text/html","responseStatus":200,"responseTimeMs":100}}'
手动关键词历史
curl --get 'https://api.pxany.com/v1/on-page-seo-check/v4/history' -H 'Authorization: Bearer <PXANY_API_KEY>' --data-urlencode 'url=http://localhost:3000/' --data-urlencode 'keyword=passport photo maker'
响应字段节选
{"run":{"runId":42,"pageId":null,"focusKeyword":"passport photo maker","scoringVersion":"on-page-seo-check-v4","report":{"scores":{"raw":85,"final":75,"earned":85,"possible":100,"coverage":90,"unknownChecks":2,"acceptance":"fix_required","appliedCaps":[{"cap":75,"reason":"正文不足600词/字。"}]}}}}
GET / POST/v1/on-page-seo-check/*
需要密钥

On Page SEO Check

供 PXAny Chrome 扩展的独立 SEO 面板使用。扩展直接采集当前标签页渲染后的 DOM 快照，pageId 用于读取 1 个核心词、按搜索量排序的最多 5 个同义词； 其余关键词按搜索量排序，最多选 20 个作为长尾词检查。词群本身不受此检查数量限制。 当前页可以是 localhost、预览环境或任意 HTTP(S) URL，不要求与 page_id 登记域名一致，浏览器也不会接触 Supabase Service Role Key。

接口

POST /v1/on-page-seo-check/runs执行检测

JSON 请求体包含 pageId 和扩展当前标签页的snapshot。服务端直接分析该 DOM，不重新抓 URL，也不做域名限制； 成功返回 201 和完整报告，只有检测成功才写入历史。

GET /v1/on-page-seo-check/runs/{runId}单次报告

读取指定历史运行的完整评分、关键词分层、逐项结论和抓取统计。

GET /v1/on-page-seo-check/history?pageId=123历史趋势

返回最近 20 次摘要以及最新完整报告；从未检测时history 为空且 run 为 null。

评分与抓取

新报告使用 on-page-seo-check-v3 契约：核心词严格检查 Title、Description、H1、URL、开头和正文，并独立决定聚焦度封顶；同义词重点检查 H2/H3 与对应段落正文；长尾词只检查正文完整词组覆盖，不要求进入 TDK。 每个关键词同时返回 Google KGR、Semrush KGR、Semrush eKGR 和 Semrush KD 作为选词参考； 这四个数据库指标不参与页面聚焦度或总分计算，缺失时返回 null。densityRankings 返回正文 1–5 gram 的前 20 个连续词组及其出现次数、密度和名次；targetDensity 将核心词与同义词的精确词组密度合并为一个词族，长尾词不参与合并。 词族状态包含 missing、low、base、focused、high 和 stuffing_risk，其中 3%–5% 标记为 focused； 这些状态只用于诊断提示，不参与页面聚焦度或总分计算。 报告还包括 0–100 总分、正文词数/noindex 封顶、关键词分层对比、 7 类分类分和逐项整改建议。DOM 快照 UTF-8 体积上限 2 MB，原始快照不写入历史。 仅凭 DOM 无法可靠取得的跳转链、robots.txt、Sitemap 和 SSR/CSR 等技术项显示为 N/A， 不进入分类分母。

执行检测 cURL
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/on-page-seo-check/runs" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "pageId": 123,
    "snapshot": {
      "pageUrl": "http://localhost:3000/preview",
      "contentType": "text/html",
      "html": "<html><body>Current rendered page</body></html>",
      "responseStatus": 200,
      "responseTimeMs": 120
    }
  }'
历史记录 cURL
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/on-page-seo-check/history?pageId=123"
检测响应（字段节选）
{
  "run": {
    "runId": 42,
    "pageId": 123,
    "url": "https://example.com/tools/compress",
    "targetKeywords": ["image compressor", "compress image online"],
    "focusKeyword": "image compressor",
    "rawScore": 84,
    "finalScore": 75,
    "focusScore": 78,
    "grade": "pass",
    "wordCount": 512,
    "scoringVersion": "on-page-seo-check-v3",
    "createdAt": "2026-08-09T09:30:00.000Z",
    "report": {
      "version": "on-page-seo-check-v3",
      "scores": {
        "raw": 84,
        "final": 75,
        "focus": 78,
        "grade": "pass",
        "appliedCaps": [
          {"cap": 75, "reason": "Visible body content is below 600 words."}
        ]
      },
      "categories": [],
      "keywordFocus": [],
      "densityRankings": {
        "1": [{"phrase": "image", "count": 20, "density": 3.91, "rank": 1}],
        "2": [{"phrase": "image compressor", "count": 6, "density": 2.34, "rank": 1}],
        "3": [],
        "4": [],
        "5": []
      },
      "targetDensity": {
        "phrases": [
          {"phrase": "image compressor", "role": "core", "count": 6, "density": 2.34},
          {"phrase": "compress image online", "role": "related", "count": 2, "density": 1.17}
        ],
        "totalCount": 8,
        "totalDensity": 3.51,
        "status": "focused"
      },
      "checks": [],
      "crawl": {},
      "page": {},
      "stats": {},
      "generatedAt": "2026-08-09T09:30:00.000Z"
    }
  }
}
GET / POST / PATCH/v1/backlinks/*
需要密钥

外链发布工作流

供 PXAny Chrome 扩展使用。旧版单次评论生成仍只返回草稿；博客评论任务则由后台排期， 插件先检测页面、获取冻结文案和一次性提交许可，再回写公开、待审核或异常结果。 扩展不直接访问 Supabase 或 Gemini，异常时整个任务暂停并保留标签页等待人工继续。

接口列表

GET /v1/backlinks/sitesactive 网站

返回 PXAny 后台 status 为 active 的网站资料；网站地址由domain 计算，并返回可编辑的 anchorTexts、productDescription、websiteScreenshotUrl、shareImageUrl 和 logoUrl，供扩展只读显示、 预览，并在手动提交时复制或补齐。

PATCH /v1/backlinks/sites/{siteId}更新发布资料

请求体包含 websiteUrl、commenterName、commenterEmail、productDescription 和anchorTexts。图片地址不接受人工提交；PXAny 后台使用 Cloudflare 自动截图，并按 og:image、twitter:image、截图回退的顺序生成分享图。websiteUrl 可传完整 URL 或裸域名，PXAny 会保存归一化域名。

GET / PATCH /v1/backlinks/settings筛选组配置

读取或完整替换扩展外链库的筛选组列表。PATCH 需要提交完整的libraryFilterGroups 数组；每一组都包含稳定的id、展示用 label 和完整的filters 对象。filters 支持qualityScoreMin / qualityScoreMax表示 0-5 的人工关注度区间，也支持 DR、月流量、搜索/直接占比、任务状态、外链属性、付费属性、网站类型和外链方式。filters.tagIds 可选择多个自定义标签：满足其中任意一个标签，并同时满足其他条件。筛选组只保存查询条件，不直接添加外链。tags 是完整的标签列表，每项包含稳定的 id、可修改的 label 与已标记外链的 resourceIds；提交时不得重名、重 ID，也不能引用未知标签。省略 tags 会保留已有标签。数据库是唯一持久化来源。

两个方法都使用 Authorization: Bearer <PXANY_API_KEY>。成功返回 {"settings":{"libraryFilterGroups":[...]}}；请求体无效返回 400，密钥缺失或错误返回 401。手动模拟时先读取完整配置，再将修改后的完整列表提交：

标签手动请求示例
# 先读取并保留完整配置
curl "https://api.pxany.com/v1/backlinks/settings" -H "Authorization: Bearer <PXANY_API_KEY>"

# settings.json 包含完整 libraryFilterGroups 和 tags；标签示例：
# {"id":"new-site","label":"新站首发","resourceIds":[501]}
# 筛选组 filters 内添加 "tagIds":["new-site"]
curl -X PATCH "https://api.pxany.com/v1/backlinks/settings" -H "Authorization: Bearer <PXANY_API_KEY>" -H "Content-Type: application/json" --data-binary @settings.json
# 成功：{"settings":{"libraryFilterGroups":[...],"tags":[...]}}
# 无效标签、重复名称或未知标签引用返回 400 invalid_request；密钥错误返回 401。
GET /v1/backlinks/resources外链库

返回数据库中的外链资源列表，供 Chrome 扩展外链库筛选展示。可选传入siteId 查询参数；传入后每条资源会返回当前网站的publicationStatus 和 siteStatus。 列表按 qualityScore 从高到低返回；qualityScore 是 0-5 的人工关注度；0 代表未关注， 1-5 代表关注度递增，越高越适合优先处理。publicationStatus 只可能是 detecting、published、closed_unknown 或 null；对应提交记录的手动备注通过publicationRemark 返回。siteStatus只用于表示 unsuitable 排除状态。linkMethod 支持 blog_comment、resource_page、forum_post、directory_submission、content_edit、guest_blog、profile、qa_answer、social_profile 和 press_release。 无法归入标准方式时返回 other。siteType 还支持 podcast、marketplace、community 和other。

POST /v1/backlinks/resources单条创建
POST /v1/backlinks/resources/import批量导入
POST /v1/backlinks/resources/bulk-import导入别名

使用 Authorization: Bearer <PXANY_API_KEY>。JSON 接受数组或 {rows, siteId?, competitorDomain?}，CSV 使用 text/csv。最多 5000 行，未知列（如 externalLinks）忽略。行字段为 url、domain、siteType、linkMethod、linkFollow、loginRequired、paidRequired、language、anchorText、remark、qualityScore、siteId 或 siteIds、competitorDomain、pageAscore、competitorAnchor、competitorTarget、verified、signal、checkedAt、needsManualReview；CSV 支持对应 snake_case 及 SEMrush Source url、Page ascore、Source title、Target url、Anchor、Nofollow、First seen。

directory_submission 按去除 www 的域名去重，其他按规范化 URL 去重；已有字段只填空，赛道按资源、站点和竞争对手追加。GET 可通过 nicheSiteId 和 competitorDomain 筛选；PATCH /verification 的 niches 替换关联，addNiches 只填空并追加。资源返回 niches（含 competitorAnchor 和 competitorTarget）、verified、signal、checkedAt、needsManualReview。PATCH /verification 可更新验证字段。行号从 0 开始，部分行可能失败；响应中的 errors 和每行 reason 说明原因。资源已保存但赛道写入失败时，该行仍显示 created 或 merged 并附 reason，可重试。

JSON 与 CSV 导入示例
curl -X POST "https://api.pxany.com/v1/backlinks/resources/import" -H "Authorization: Bearer <PXANY_API_KEY>" -H "Content-Type: application/json" -d '{"siteId":1,"competitorDomain":"competitor.example","rows":[{"url":"https://publisher.example/post","siteType":"blog","linkMethod":"blog_comment","pageAscore":72,"competitorAnchor":"Example","competitorTarget":"https://competitor.example/"}]}'
curl -X POST "https://api.pxany.com/v1/backlinks/resources/import" -H "Authorization: Bearer <PXANY_API_KEY>" -H "Content-Type: text/csv" --data-binary $'url,site_id,competitor_domain,page_ascore,competitor_anchor,competitor_target
https://publisher.example/post,1,competitor.example,72,Example,https://competitor.example/'
# {"created":1,"merged":0,"skipped":0,"rows":[{"index":0,"url":"https://publisher.example/post","action":"created","resourceId":501}],"errors":[]}
# 无效请求返回 400；密钥错误返回 401。
PATCH /v1/backlinks/resources/{resourceId}修改资源地址

只修改外链资源的 url，用于 Chrome 扩展里人工把地址调整为更准确的规范 URL。 请求体必须包含绝对 http/https 地址；规范化后必须仍属于原资源的同一域名， 否则返回 400 application/problem+json。接口会移除 URL hash 和常见 tracking 参数，保留 DR、AITDK 流量、搜索占比、直接占比和更新时间等指标字段；如果规范 URL 已被另一条资源占用，当前编辑的资源作为最新数据保留。

GET /v1/backlinks/resources/{resourceId}/example真实发布案例

需要 Authorization: Bearer $PXANY_API_KEY；路径参数resourceId 必须是正整数。接口按资源域名读取一条最近采集的真实 Semrush 外链记录，返回同一行中的 sample_backlink_url、sample_anchor_text 和 sample_target_url，供 Chrome 扩展在资源地址下方展示来源页、锚文本和目标页。资源没有探索案例时返回{"example": null}；资源不存在返回 404，参数错误返回 400， API Key 缺失或无效返回 401。

DELETE /v1/backlinks/resources/{resourceId}删除资源

从外链库删除废弃资源。删除成功后返回被删除的resource；相关发布记录和站点资源状态会一并删除。 常用于 Chrome 扩展访问资源后确认页面已失效的场景。

GET /v1/backlinks/resources/{resourceId}/site-status跨项目处理结果

返回这条外链在各项目中的处理结果，供 Chrome 扩展项目下拉菜单展示detecting、published、closed_unknown 或 unsuitable。 没有处理记录的项目不会出现在 statuses 数组中。

PATCH /v1/backlinks/resources/{resourceId}/site-status设置或取消处理结果

需要 Authorization: Bearer $PXANY_API_KEY；路径参数resourceId 和请求体中的 siteId 必须是正整数。 请求体必须包含 siteId 和 status。status 支持 detecting、published、closed_unknown、unsuitable 或 null：前三者创建或更新 当前资源/网站的唯一发布记录；unsuitable 会删除这条发布记录， 并把资源从当前网站排除。可同时保存检测出的评论 URL、Follow 属性等字段。

closed_unknown 表示“已结束（无法核验）”：由你手动结束跟进，不计为已发布； 保留已有备注和提交证据，除非明确传入 remark 修改备注。关闭时忽略请求中的新核验字段。 没有历史投稿记录时不会补造已提交时间，发布记录的 submittedAt 为 null。 已结束的结果禁止继续生成、核验或重发，旧任务回执也不能改回待确认或已发布。 如需纠错，先明确传入 "status": null 清除，再重新登记结果；清除会删除当前记录及备注。

误选后传入 "status": null 可恢复未处理：原子删除当前资源与网站的 发布记录、排除记录及其中的任务备注，保留资源本身和其他网站的结果，不会删除外部真实文章。 成功返回的 resourceStatus.publicationStatus 和resourceStatus.siteStatus 均为 null；该网站也不再出现在GET site-status 的 statuses 中。 省略 status、参数无效或网站不存在/未启用返回 400，API Key 缺失或无效返回 401， 已结束结果未清除就直接改为待确认、已发布或不适合也返回 400； 资源不存在返回 404；错误体使用 application/problem+json。

PATCH /v1/backlinks/resources/{resourceId}/verification修改核验数据

只更新人工核验字段，包括 siteType、linkMethod、language、linkFollow、loginRequired、paidRequired、qualityScore、anchorText 和remark。除 qualityScore 会清空为 0 外， 其他字段传 null 或空字符串会清空为未知；接口会刷新verificationUpdatedAt。

POST /v1/backlinks/resources/{resourceId}/metrics/refresh刷新指标数据

触发一次 Ahrefs DR 和 AITDK 流量补数；成功后更新指标字段和metricsUpdatedAt，不修改核验字段。

POST /v1/backlinks/directory-submissions/plan外链表单 AI 填表规划

供 PXAny Chrome 扩展的“AI 分析当前页”调用。请求体包含siteId、resourceId 和内容脚本提取出的snapshot。每个下拉框、单选组和复选组都会把全部候选项的显示文字与实际 value key 交给 AI，AI 只能返回页面存在的 key。接口接受非博客评论外链资源；博客评论继续使用专用评论生成流程。返回可自动填写字段、 unresolved 字段和 warnings；不会创建或更新 publication 数据，也不会自动提交第三方表单。

POST /v1/backlinks/directory-submissions/rewrite外链表单单字段重写

请求体包含 siteId、resourceId、pageUrl、当前字段 control、原草稿assignment 和用户自定义 instruction。 支持 title/site_name、description、tags、category 和通用 selection；选择题只能返回当前页面存在的 option value key。URL、作者、邮箱等精确资料字段不能重写。

POST /v1/backlinks/publications/generate生成评论草稿

请求体包含 siteId 和当前页 pageContext；resourceId 可选。未提供资源时也会按当前页面内容调用 Gemini 返回评论 draft，但不会创建资源或保存检测结果；提供资源时仍要求 当前 URL 与 blog + blog_comment 记录完全匹配，手动提交后可通过 资源状态接口保存 detecting 或 published。

POST /v1/backlinks/campaign-items/{itemId}/prepare准备自动评论文档

仅供后台已经分派的插件任务调用。插件先打开真实页面并通过标准 WordPress 表单预检，再提交 pageContext；服务端只生成并固化一次 Gemini 评论草稿，重复请求返回同一份文档。

POST /v1/backlinks/campaign-items/{itemId}/checkpoint一次性提交许可与结果回写

stage=committing 原子领取一次性提交许可。服务端写入commitStartedAt 后，任何重连、重试或人工继续都只能核验， 不得再次点击提交。stage=result 回写 published、pending_moderation、verification_missing、unsupported 或 needs_attention。

POST /v1/backlinks/campaign-items/{itemId}/continue人工处理后继续

异常会暂停整个任务并保留插件标签页。所有者在页面完成登录、验证码或其他人工处理后， 从插件点击继续；接口只恢复原任务和原 Job ID，不创建新的盲目提交。

资源列表示例

cURL
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/backlinks/resources?siteId=1"
响应示例
{
  "resources": [
    {
      "id": 501,
      "url": "https://example.com/post",
      "domain": "example.com",
      "anchorText": "PXAny",
      "dr": 35,
      "aitdkMonthlyVisits": 7268,
      "aitdkSearchTrafficShare": 0.18,
      "aitdkDirectTrafficShare": 0.42,
      "aitdkCheckedAt": "2026-08-02T10:43:21.022Z",
      "metricsUpdatedAt": "2026-08-02T10:43:21.022Z",
      "siteType": "blog",
      "linkMethod": "blog_comment",
      "language": "en",
      "linkFollow": "nofollow",
      "loginRequired": null,
      "paidRequired": null,
      "remark": "Good contextual blog comment target.",
      "reviewStatus": "fulldata",
      "publicationStatus": "published",
      "publicationRemark": "您的产品计划于 2027 年 2 月 13 日发布。",
      "siteStatus": null,
      "siteStatusRemark": null,
      "siteStatusUpdatedAt": null,
      "verificationUpdatedAt": "2026-08-03T08:42:10.000Z"
    }
  ]
}
读取真实发布案例
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/backlinks/resources/501/example"
真实发布案例响应
{
  "example": {
    "backlinkUrl": "https://source.example/reviews/b2b-tools",
    "anchorText": "TrustRadius",
    "targetUrl": "https://trustradius.com/products/example"
  }
}
没有案例时的响应
{
  "example": null
}
修改资源地址
curl --fail-with-body \
  -X PATCH "https://api.pxany.com/v1/backlinks/resources/501" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/post?ref=directory"
  }'
修改地址响应
{
  "resource": {
    "id": 501,
    "url": "https://example.com/post?ref=directory",
    "domain": "example.com",
    "anchorText": "PXAny",
    "dr": 35,
    "aitdkMonthlyVisits": 7268,
    "aitdkSearchTrafficShare": 0.18,
    "aitdkDirectTrafficShare": 0.42,
    "aitdkCheckedAt": "2026-08-02T10:43:21.022Z",
    "metricsUpdatedAt": "2026-08-02T10:43:21.022Z",
    "siteType": "blog",
    "linkMethod": "blog_comment",
    "language": "en",
    "linkFollow": "nofollow",
    "loginRequired": null,
    "paidRequired": null,
    "publicationStatus": null,
    "publicationRemark": null,
    "remark": "Good contextual blog comment target.",
    "reviewStatus": "fulldata",
    "siteStatus": null,
    "siteStatusRemark": null,
    "siteStatusUpdatedAt": null,
    "verificationUpdatedAt": "2026-08-03T08:42:10.000Z"
  }
}
删除资源
curl --fail-with-body \
  -X DELETE "https://api.pxany.com/v1/backlinks/resources/501" \
  -H "Authorization: Bearer $PXANY_API_KEY"
删除响应
{
  "resource": {
    "id": 501,
    "url": "https://example.com/post",
    "domain": "example.com",
    "anchorText": "PXAny",
    "dr": 35,
    "aitdkMonthlyVisits": 7268,
    "aitdkSearchTrafficShare": 0.18,
    "aitdkDirectTrafficShare": 0.42,
    "aitdkCheckedAt": "2026-08-02T10:43:21.022Z",
    "metricsUpdatedAt": "2026-08-02T10:43:21.022Z",
    "siteType": "blog",
    "linkMethod": "blog_comment",
    "language": "en",
    "linkFollow": "dofollow",
    "loginRequired": false,
    "paidRequired": false,
    "publicationStatus": null,
    "publicationRemark": null,
    "remark": "Dead page removed from the Chrome extension.",
    "reviewStatus": "fulldata",
    "siteStatus": null,
    "siteStatusRemark": null,
    "siteStatusUpdatedAt": null,
    "verificationUpdatedAt": "2026-08-04T11:06:00.000Z"
  }
}
修改核验数据
curl --fail-with-body \
  -X PATCH "https://api.pxany.com/v1/backlinks/resources/501/verification" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "siteType": "blog",
    "linkMethod": "blog_comment",
    "language": "en",
    "linkFollow": "dofollow",
    "loginRequired": false,
    "paidRequired": false,
    "qualityScore": 4,
    "verified": true,
    "signal": "link found",
    "checkedAt": "2026-10-27T10:00:00Z",
    "needsManualReview": false,
    "anchorText": "PXAny",
    "remark": "Verified from the Chrome extension side panel."
  }'
修改核验响应
{
  "resource": {
    "id": 501,
    "url": "https://example.com/post",
    "domain": "example.com",
    "anchorText": "PXAny",
    "dr": 35,
    "aitdkMonthlyVisits": 7268,
    "aitdkSearchTrafficShare": 0.18,
    "aitdkDirectTrafficShare": 0.42,
    "aitdkCheckedAt": "2026-08-02T10:43:21.022Z",
    "metricsUpdatedAt": "2026-08-02T10:43:21.022Z",
    "siteType": "blog",
    "linkMethod": "blog_comment",
    "language": "en",
    "linkFollow": "dofollow",
    "loginRequired": false,
    "paidRequired": false,
    "publicationStatus": null,
    "publicationRemark": null,
    "remark": "Verified from the Chrome extension side panel.",
    "reviewStatus": "fulldata",
    "siteStatus": null,
    "siteStatusRemark": null,
    "siteStatusUpdatedAt": null,
    "verificationUpdatedAt": "2026-08-04T11:06:00.000Z"
  }
}
登记资源状态
curl --fail-with-body \
  -X PATCH "https://api.pxany.com/v1/backlinks/resources/501/site-status" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"siteId": 1, "status": "unsuitable", "remark": "Needs login to comment."}'
登记响应
{
  "resourceStatus": {
    "publicationStatus": null,
    "resourceId": 501,
    "siteId": 1,
    "siteStatus": "unsuitable"
  }
}
结束无法核验的结果，保留备注和提交证据
curl --fail-with-body \
  -X PATCH "https://api.pxany.com/v1/backlinks/resources/501/site-status" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"siteId": 1, "status": "closed_unknown"}'
结束响应
{"resourceStatus":{"publicationStatus":"closed_unknown","resourceId":501,"siteId":1,"siteStatus":null}}
取消处理结果，恢复未处理
curl --fail-with-body \
  -X PATCH "https://api.pxany.com/v1/backlinks/resources/501/site-status" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"siteId": 1, "status": null}'
取消处理结果响应
{
  "resourceStatus": {
    "publicationStatus": null,
    "resourceId": 501,
    "siteId": 1,
    "siteStatus": null
  }
}
读取跨项目处理结果
curl --fail-with-body \
  "https://api.pxany.com/v1/backlinks/resources/501/site-status" \
  -H "Authorization: Bearer $PXANY_API_KEY"
跨项目处理结果响应
{
  "statuses": [
    {
      "publicationStatus": "published",
      "resourceId": 501,
      "siteId": 1,
      "siteStatus": null
    },
    {
      "publicationStatus": null,
      "resourceId": 501,
      "siteId": 2,
      "siteStatus": "unsuitable"
    }
  ]
}
刷新指标数据
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/backlinks/resources/501/metrics/refresh" \
  -H "Authorization: Bearer $PXANY_API_KEY"
刷新指标响应
{
  "resource": {
    "id": 501,
    "url": "https://example.com/post",
    "domain": "example.com",
    "dr": 35,
    "aitdkMonthlyVisits": 7268,
    "aitdkSearchTrafficShare": 0.18,
    "aitdkDirectTrafficShare": 0.42,
    "aitdkCheckedAt": "2026-08-02T10:43:21.022Z",
    "metricsUpdatedAt": "2026-08-02T10:43:21.022Z",
    "siteType": "blog",
    "linkMethod": "blog_comment",
    "language": "en",
    "linkFollow": "nofollow",
    "loginRequired": null,
    "paidRequired": null,
    "publicationStatus": null,
    "publicationRemark": null,
    "reviewStatus": "fulldata",
    "siteStatus": null,
    "siteStatusRemark": null,
    "siteStatusUpdatedAt": null,
    "verificationUpdatedAt": "2026-08-03T08:42:10.000Z"
  }
}

自动博客评论执行接口

准备冻结文档
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/backlinks/campaign-items/<ITEM_UUID>/prepare" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "jobId": "backlink-comment:<ITEM_UUID>:1",
    "pageContext": { "pageUrl": "https://example.com/post", "pageTitle": "Example article" }
  }'
领取一次性提交许可
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/backlinks/campaign-items/<ITEM_UUID>/checkpoint" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "jobId": "backlink-comment:<ITEM_UUID>:1", "stage": "committing" }'
人工处理后继续
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/backlinks/campaign-items/<ITEM_UUID>/continue" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "jobId": "backlink-comment:<ITEM_UUID>:1" }'

这些请求用于手动模拟协议排查，不是创建任务的入口。任务在 PXAny 后台创建； 外部调用必须使用当前 item UUID 与当前 Job ID，否则返回 409。400 表示参数错误， 401 表示密钥错误，404 表示任务不存在，409 表示状态或 Job 冲突，503 表示生成服务暂不可用。

结果状态

detecting已提交，但需要稍后再次确认是否上线
published已确认外链上线
closed_unknown已结束（无法核验），不再跟进，不算发布成功
列出 active 网站
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/backlinks/sites"
active 网站响应
{
  "sites": [
    {
      "id": 1,
      "name": "PXAny",
      "domain": "pxany.com",
      "anchorTextCount": 3,
      "anchorTexts": ["PXAny", "AI website builder", "website generator"],
      "commenterName": "PXAny",
      "commenterEmail": "name@example.com",
      "logoUrl": "https://www.google.com/s2/favicons?domain=pxany.com&sz=128",
      "productDescription": "PXAny helps ship and operate AI-assisted websites.",
      "shareImageUrl": "https://pxany.com/images/og.png",
      "websiteScreenshotUrl": "https://pxany.com/images/screenshot.png",
      "websiteUrl": "https://pxany.com"
    }
  ]
}
修改站点发布资料
curl --fail-with-body \
  -X PATCH "https://api.pxany.com/v1/backlinks/sites/1" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "websiteUrl": "https://pxany.com",
    "commenterName": "PXAny",
    "commenterEmail": "name@example.com",
    "productDescription": "PXAny helps ship and operate AI-assisted websites.",
    "anchorTexts": ["PXAny", "AI website builder", "website generator"]
  }'
修改响应
{
  "site": {
    "id": 1,
    "name": "PXAny",
    "domain": "pxany.com",
    "anchorTextCount": 3,
    "anchorTexts": ["PXAny", "AI website builder", "website generator"],
    "commenterName": "PXAny",
    "commenterEmail": "name@example.com",
    "logoUrl": "https://www.google.com/s2/favicons?domain=pxany.com&sz=128",
    "productDescription": "PXAny helps ship and operate AI-assisted websites.",
    "shareImageUrl": "https://pxany.com/images/og.png",
    "websiteScreenshotUrl": "https://pxany.com/images/screenshot.png",
    "websiteUrl": "https://pxany.com"
  }
}
快捷筛选默认
curl --fail-with-body \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  "https://api.pxany.com/v1/backlinks/settings"

curl --fail-with-body \
  -X PATCH "https://api.pxany.com/v1/backlinks/settings" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "settings": {
      "libraryFilterGroups": [
        {
          "id": "directory",
          "label": "导航站",
          "filters": {
            "siteType": "directory",
            "linkMethod": "directory_submission",
            "drMin": "15",
            "usageStatuses": ["unused"],
            "drMax": "",
            "monthlyVisitsMin": "",
            "monthlyVisitsMax": "",
            "qualityScoreMin": "3",
            "qualityScoreMax": "5",
            "searchTrafficShareMin": "",
            "searchTrafficShareMax": "",
            "directTrafficShareMin": "",
            "directTrafficShareMax": "",
            "linkFollows": [],
            "paidStatuses": []
          }
        }
      ]
    }
  }'
快捷筛选响应
{
  "settings": {
    "libraryFilterGroups": [
      {
        "id": "directory",
        "label": "导航站",
        "filters": {
          "directTrafficShareMax": "",
          "directTrafficShareMin": "",
          "drMax": "",
          "drMin": "15",
          "linkFollows": [],
          "linkMethod": "directory_submission",
          "monthlyVisitsMax": "",
          "monthlyVisitsMin": "",
          "paidStatuses": [],
          "qualityScoreMax": "5",
          "qualityScoreMin": "3",
          "searchTrafficShareMax": "",
          "searchTrafficShareMin": "",
          "siteType": "directory",
          "usageStatuses": ["unused"]
        }
      },
      {
        "id": "blog_comment",
        "label": "博客评论",
        "filters": {
          "directTrafficShareMax": "",
          "directTrafficShareMin": "20",
          "drMax": "",
          "drMin": "10",
          "linkFollows": ["dofollow"],
          "linkMethod": "blog_comment",
          "monthlyVisitsMax": "",
          "monthlyVisitsMin": "1000",
          "paidStatuses": [],
          "qualityScoreMax": "",
          "qualityScoreMin": "",
          "searchTrafficShareMax": "",
          "searchTrafficShareMin": "20",
          "siteType": "blog",
          "usageStatuses": ["unused"]
        }
      }
    ]
  }
}
生成评论草稿
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/backlinks/publications/generate" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "siteId": 1,
    "resourceId": 501,
    "pageContext": {
      "pageUrl": "https://example.com/post",
      "pageTitle": "Example article",
      "pageDescription": "Short article description",
      "mainHeadings": ["Example heading"],
      "pageText": "Visible page summary"
    }
  }'
草稿响应
{
  "draft": {
    "generatedComment": "Natural comment with <a href=\"https://pxany.com\">PXAny</a>.",
    "pageContext": {
      "pageUrl": "https://example.com/post"
    },
    "resourceId": 501,
    "selectedAnchorText": "PXAny",
    "siteId": 1,
    "targetUrl": "https://pxany.com"
  }
}
标记为待确认
curl --fail-with-body \
  -X PATCH "https://api.pxany.com/v1/backlinks/resources/501/site-status" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "siteId": 1,
    "status": "detecting",
    "selectedAnchorText": "PXAny",
    "targetUrl": "https://pxany.com"
  }'
确认已发布
curl --fail-with-body \
  -X PATCH "https://api.pxany.com/v1/backlinks/resources/501/site-status" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "siteId": 1,
    "status": "published",
    "detectedCommentUrl": "https://example.com/post#comment-123",
    "detectedLinkFollow": "dofollow"
  }'
固定约束

第一版只支持手动提交。评论必须包含一个 HTML <a>链接，锚文本由后台站点发布资料按当前页面语境选择。扩展不会绕过 nofollow、ugc、 验证码或反垃圾机制。

BACKLINK SUBMISSION GUIDE

通用外链提交指南

POST /v1/backlinks/submission-guides/generate 使用 Authorization: Bearer <PXANY_API_KEY> 鉴权。 根据当前网页和已保存的网站资料，一次生成提交步骤、可编辑文案、页面依据和缺失资料。不要求页面存在表单，不按资源分类限制生成，不会发送、提交或修改发布状态。

必填参数：siteId 与 resourceId 为已有记录的正整数 ID；snapshot 包含页面 URL、标题、语言（可为 null）、完整可读正文、链接、字段元数据和读取警告。links 每项包含 label/url；fields 每项包含 label/type/required/maxLength/options，未限制长度时 maxLength 为 null。无链接、字段或警告时传空数组。 目标网站须启用。邮件、目录、论坛和个人资料等使用同一接口；支持用户打开外部提交入口后重新生成，服务端不会自行访问链接。

生成指南请求 cURL
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/backlinks/submission-guides/generate" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "siteId": 1,
    "resourceId": 501,
    "snapshot": {
      "pageUrl": "https://directory.example/submit",
      "pageTitle": "Recommend a tool",
      "language": "en",
      "text": "Email support@directory.example with your tool name, URL, category and one-sentence description.",
      "links": [{"label": "Email submissions", "url": "mailto:support@directory.example"}],
      "fields": [],
      "warnings": []
    }
  }'

手动模拟时，请将示例 ID、页面地址和快照替换为实际资源；Example Tool 的名称、网址与介绍仅为响应示例，实际生成读取所选网站资料。

指南成功响应
{
  "guide": {
    "summary": "页面通过邮件接收工具推荐，需要工具名称、网址、分类和一句话介绍。",
    "evidence": [
      "Email support@directory.example with your tool name, URL, category and one-sentence description."
    ],
    "steps": [
      {
        "title": "检查并发送推荐邮件",
        "instruction": "检查下列内容后发送到 support@directory.example。分类资料缺失，发送前请补充。",
        "contents": [
          {
            "label": "邮件主题",
            "text": "Tool recommendation: Example Tool"
          },
          {
            "label": "邮件正文",
            "text": "Hi team,\nI'd like to recommend Example Tool for your directory.\nWebsite: https://example-tool.test\nCategory: [please confirm]\nDescription: A tool for preparing product submission materials.\nThank you for reviewing it."
          }
        ],
        "completion": "邮件已发送后标记待确认；确认公开收录链接后才标记已发布。"
      }
    ],
    "missing": [
      "工具分类未在网站资料中提供，请确认后补充。"
    ],
    "warnings": [
      "指南只准备内容，不会代发邮件或自动修改发布状态。"
    ]
  }
}
指南错误响应
{
  "type": "https://api.pxany.com/errors/service-unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "AI guide generation is currently unavailable.",
  "requestId": "example-request-id"
}

返回 guide.summary/evidence/steps/missing/warnings。每步包含 title、instruction、contents 和 completion；contents 是 label/text 列表，文本保留换行。 无明确入口时可返回空步骤，并说明缺失信息。解释使用中文，提交文案遵循页面要求或页面语言。

限制、错误与隐私

请求体最多 100 KiB，页面快照序列化后最多 24,000 字符；链接最多 200 项、字段最多 100 项、每字段选项最多 100 项，其他字段长度限制见 OpenAPI。超限拒绝生成，不静默截断。 只分析当前已加载可读内容；无法读取的嵌入区域需要在 warnings 中说明。 400 表示参数不合法或快照超限；401 表示鉴权失败；404 表示站点不存在或未启用、资源不存在；503 表示 AI 不可用或输出校验失败；500 表示内部错误。 本接口会将页面可读内容、字段元数据及所选网站的发布资料交给 Workers AI；不要上传 Cookie、密码、隐藏字段或已有表单值。 扩展中的指南只暂存在当前浏览器会话，按网站、资源、标签页和 URL 隔离。现有评论与表单填写接口继续保留。

BACKLINK FORM PLAN

外链表单 AI 填表规划

POST /v1/backlinks/directory-submissions/plan 供 PXAny Chrome 扩展在“AI 分析当前页”流程中调用。请求体包含siteId、resourceId 和当前页面表单snapshot；原生下拉框、ARIA combobox、单选组和复选组都作为选择题。对于动态弹层，扩展会临时展开控件、从实际弹层读取 option label、value key、禁用状态、多选状态和 maxSelections，随后恢复原状态；AI 只可从本次读取到的启用 key 中选择。interaction 标识原生控件、动态 popup_selection、兼容 ARIA combobox 或文件上传；inspectionStatus: failed 的动态控件会直接返回人工处理，不猜测选项。文件上传会以 manualOnly 返回为人工步骤，扩展不会自动上传文件。响应中的选项标签由 PXAny 根据页面选项映射，接口接受非博客评论外链资源，博客评论继续使用专用评论生成流程；返回可自动填写字段、 unresolved 字段和 warnings。本接口不会创建或更新 publication 数据，也不会自动提交第三方表单。

规划请求 cURL
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/backlinks/directory-submissions/plan" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "siteId": 1,
    "resourceId": 501,
    "snapshot": {
      "pageUrl": "https://bestofai.com/submit-tool",
      "pageTitle": "Submit a Tool",
      "language": "en",
      "blockers": [],
      "forms": [
        {
          "formId": "pxany-form-1",
          "fingerprint": "pxany-5f98fdf",
          "instructions": [],
          "controls": [
            {
              "controlId": "pxany-form-1-input-1",
              "label": "Category",
              "name": "category",
              "tag": "input",
              "inputType": "checkbox",
              "autocomplete": null,
              "placeholder": null,
              "required": true,
              "maxLength": null,
              "minLength": null,
               "helpText": null,
               "hasValue": false,
               "multiple": true,
               "options": [
                { "disabled": false, "label": "AI Search", "value": "ai-search" },
                { "disabled": false, "label": "Writing", "value": "writing" },
                { "disabled": false, "label": "Productivity", "value": "productivity" }
              ]
            },
            {
              "controlId": "pxany-form-1-input-2",
              "label": "URL",
              "name": "url",
              "tag": "input",
              "inputType": "url",
              "autocomplete": "url",
              "placeholder": "https://example.com",
              "required": true,
              "maxLength": 255,
              "minLength": null,
              "helpText": "Use the public product URL.",
              "hasValue": false,
              "options": []
            },
            {
              "controlId": "pxany-form-1-textarea-5",
              "label": "Description",
              "name": "description",
              "tag": "textarea",
              "inputType": null,
              "autocomplete": null,
              "placeholder": null,
              "required": true,
              "maxLength": 160,
              "minLength": 40,
              "helpText": "Write a concise product description.",
              "hasValue": false,
              "options": []
            }
          ]
        }
      ]
    }
  }'
规划成功响应
{
  "plan": {
    "formId": "pxany-form-1",
    "fingerprint": "pxany-5f98fdf",
    "assignments": [
      {
        "controlId": "pxany-form-1-input-1",
        "label": "Category",
        "role": "category",
        "value": "ai-search",
        "values": ["ai-search", "writing"],
        "selectedOptions": [
          { "label": "AI Search", "value": "ai-search" },
          { "label": "Writing", "value": "writing" }
        ],
        "source": "ai",
        "confidence": "medium"
      },
      {
        "controlId": "pxany-form-1-input-2",
        "label": "URL",
        "role": "site_url",
        "value": "https://pxany.com",
        "values": ["https://pxany.com"],
        "source": "deterministic",
        "confidence": "high"
      },
      {
        "controlId": "pxany-form-1-textarea-5",
        "label": "Description",
        "role": "description",
        "value": "PXAny helps makers ship AI-assisted websites with reusable publishing workflows.",
        "values": ["PXAny helps makers ship AI-assisted websites with reusable publishing workflows."],
        "source": "ai",
        "confidence": "high"
      }
    ],
    "unresolved": [
      {
        "controlId": "pxany-form-1-input-9",
        "label": "Logo upload",
        "reason": "AI planning is unavailable for this field."
      }
    ],
    "warnings": ["Page blocker detected: file_upload."],
    "aiStatus": "used"
  }
}
规划错误响应
{
  "type": "https://api.pxany.com/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "Current page is outside the selected resource domain.",
  "requestId": "00000000-0000-0000-0000-000000000000"
}
单字段重写请求 cURL
curl --fail-with-body \
  -X POST "https://api.pxany.com/v1/backlinks/directory-submissions/rewrite" \
  -H "Authorization: Bearer $PXANY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "siteId": 1,
    "resourceId": 501,
    "pageUrl": "https://bestofai.com/submit-tool",
    "pageLanguage": "en",
    "instruction": "Make the slug shorter and more readable.",
    "assignment": {
      "controlId": "pxany-form-1-input-3",
      "label": "Title",
      "role": "site_name",
      "value": "how-old-do-i-look",
      "values": ["how-old-do-i-look"],
      "source": "ai",
      "confidence": "high"
    },
    "control": {
      "controlId": "pxany-form-1-input-3",
      "label": "Title",
      "name": "title",
      "tag": "input",
      "inputType": "text",
      "autocomplete": null,
      "placeholder": null,
      "required": true,
      "maxLength": 80,
      "minLength": null,
      "helpText": null,
      "hasValue": false,
      "options": []
    }
  }'
单字段重写成功响应
{
  "assignment": {
    "controlId": "pxany-form-1-input-3",
    "label": "Title",
    "role": "site_name",
    "value": "How Old Do I Look",
    "values": ["How Old Do I Look"],
    "source": "ai",
    "confidence": "high"
  }
}
单字段重写错误响应
{
  "type": "https://api.pxany.com/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "Exact profile fields cannot be AI rewritten.",
  "requestId": "00000000-0000-0000-0000-000000000000"
}
AI 生成与隐私

外链表单填表只把项目名称、URL、基础描述、anchor text 和字段结构发给 Workers AI；不发送作者、邮箱、Cookie、截图、网页正文或已有表单内容。 AI 用于生成/改写标题与描述、生成标签，并从页面全部合法选项中回答任意下拉框、单选组或复选组；AI 返回的是页面 option 的 value key，不是显示文字；单字段重写只会把 当前字段、原草稿和你的自定义要求发给 AI。URL、 作者和邮箱只使用 PXAny 保存的原值。AI 不可用或返回无效结构时， 确定性字段仍会填写，描述和标签会退回基础资料，无法可靠回答或 key 非法的选择题转为人工处理。 扩展会先展示可编辑草稿，只有点击“填写当前草稿”才回填页面，并且永远不会自动点击第三方提交按钮。

ERROR RESPONSES

错误响应

公共 API 默认使用 application/problem+json。 排查问题时保留响应头 x-request-id 和正文中的requestId。

错误结构
{
  "type": "https://api.pxany.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "A valid PXAny API key is required.",
  "requestId": "00000000-0000-0000-0000-000000000000"
}
400请求体或参数不合法
401API Key 缺失或无效
404目标记录不存在
503上游服务或必要资源不可用