acedatacloud

AceDataCloud 平台管理

以编程方式管理你的 AceDataCloud 账户：余额、使用记录、API 密钥、服务、订单、平台令牌、模型、公告和推荐收益；通过 MCP / REST 管理文章 / 视频草稿、审核讨论串和同行评审后的博客发布 — 还可在无需令牌的情况下浏览公开目录和文档（服务定价、API 规范、数据集、集成、文档搜索、模型目录）。

这是 https://platform.acedata.cloud/api/v1 上的管理 / 控制台 API — 与 Web 控制台使用的是同一套接口。它与 api.acedata.cloud 上的数据生成 API（图像 / 视频 / 音乐 / 搜索生成）不同。

设置 — 使用平台令牌，而不是服务令牌

管理 API 使用平台令牌（或已登录用户令牌）进行身份验证，而不是用于 api.acedata.cloud 的每服务 API 令牌。

1. 在 platform.acedata.cloud/console/platform-tokens 创建一个（或使用 POST /api/v1/platform-tokens/）。令牌以 platform- 开头，永不过期。
2. 通过以下两种方式之一提供：
   • 连接器（推荐用于工作室 / 聊天）： 在 studio.acedata.cloud/console/connectors 安装 AceDataCloud 连接器，并粘贴一次令牌 — 运行时会自动将 ACEDATACLOUD_PLATFORM_TOKEN 注入沙盒（此技能声明了 connections: [acedatacloud]）。
   • 本地 .env：

ACEDATACLOUD_PLATFORM_TOKEN=platform-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -H "authorization: Bearer $ACEDATACLOUD_PLATFORM_TOKEN" \
  https://platform.acedata.cloud/api/v1/applications/

普通令牌只能访问自己的账户数据。超级用户令牌可以访问所有用户的数据，也是执行管理操作（公告）所必需的。

OAuth 账户访问

OAuth 访问令牌用于授权访问账户资源；它们不是模型 API Key。OAuth 授权不会创建 Key、订阅服务或增加余额。若要连接第三方账户：

1. 在 https://auth.acedata.cloud/user/oauth-apps 注册应用。请从经过身份验证的 GET https://auth.acedata.cloud/api/v1/oauth2/applications/ 读取 available_scopes，不要使用范围更广的 Discovery scopes_supported 列表。仅请求已注册且用户拥有的权限，例如 profile:read credentials:read；只有在确认要更改 Key 时才添加 credentials:write，只有需要刷新时才添加 offline_access。旧版 profile、email、phone 和 platform scope 不会被接受为别名；请使用明确的当前 scope，例如 profile:read 和 email:read。account 选择器仅供指定的官方账号 MCP 使用，不是第三方全权限 scope。
2. 打开 https://auth.acedata.cloud/oauth2/authorize，并设置 response_type=code、client_id、完全匹配的已注册 redirect_uri、以空格分隔的 scope、新生成的随机 state 以及 S256 PKCE。公共客户端必须使用 S256，而非 plain；请在应用自己的会话中保留 verifier。在交换一次性 code（有效期为 10 分钟）前，先验证回调 state。使用 POST https://auth.acedata.cloud/oauth2/token，并通过表单字段发送 grant_type=authorization_code、client_id、redirect_uri、code 和 code_verifier。机密客户端还要在服务端发送 client_secret（使用 client_secret_post，而非 HTTP Basic）；切勿将 secret 放在浏览器页面中。读取实际授予的 scope 和 expires_in；不会返回 id_token。
3. 使用 OAuth Bearer token 读取 GET https://auth.acedata.cloud/api/v1/users/me；如果已获授 credentials:read，再将其中真实的 id 用于 GET https://platform.acedata.cloud/api/v1/credentials/?user_id=<id>&limit=100&offset=0。读取 items[*].token，通过 offset/limit 翻页，并为预期的应用/服务选择有效 Key，而不要直接取第一项。user_id=me 无效。列表为空不代表授权失败。切勿显示或记录 Keys、code、token 或 PKCE verifier。
4. 对于使用当前 Studio 账号的 Studio 网站组件，请在 Settings → Home → Website 下配置应用 ID 和回调地址。网站和回调必须使用与 Studio 不同的 HTTPS 来源；切勿配置 client secret。页面必须实现 acedatacloud:oauth:ready、acedatacloud:oauth:init、acedatacloud:oauth:authorize 和 acedatacloud:oauth:result，验证完全匹配的父级来源、父窗口和 state；在本地保留 verifier，并交换返回的 code。此组件请求 profile:read credentials:read，不请求 offline_access 或博客权限；每位访客都必须单独同意。它不会注入 Studio 的登录 token 或 Key。标准 OAuth 重定向不需要此消息协议或 embed=studio/embed_origin；普通 iframe 首次登录后继续操作存在已知缺口，因此请验证已登出/会话过期的情况，或改用独立页面。遇到拒绝授权或 login_required 时，请恢复为可重试的连接状态，不要循环发起授权。
5. 仅在已获授 offline_access 时才使用 token 端点和已保存的 refresh token，通过 grant_type=refresh_token 刷新；请保留最新响应。刷新并不保证旧 refresh token 会立即失效。当前，POST https://auth.acedata.cloud/oauth2/revoke 携带表单字段 token 会返回 HTTP 200，但不会立即使已签发的 JWT 失效。请清除自己保存的连接状态，但不要声称所有 token 都已撤销。复制出的 API Key 必须在凭据管理中单独撤销或轮换。

捆绑的 CLI 不会注册 OAuth 应用，也不会执行浏览器/PKCE 交换。遇到 invalid_scope 时，请检查应用已注册的 scope、委派限制和用户权限，而不是扩大访问范围。在依赖连接前，请验证授权被拒、state 不匹配、code 过期/已使用、缺少 scope、无 Keys、网络故障、token 过期以及 iframe 账号变更等情况。

CLI（首选）

该技能提供 scripts/acedatacloud.py——一个独立的 CLI（仅使用标准库），用于执行最常见的操作。

# $SKILL_DIR can point at another skill loaded this turn — anchor on our own
# script (re-run this at the top of every fresh-shell Bash block).
ADC="$SKILL_DIR/scripts/acedatacloud.py"; [ -f "$ADC" ] || ADC=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/acedatacloud.py' 2>/dev/null | head -1)
[ -f "$ADC" ] || { echo "acedatacloud script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }

# Read
python3 $ADC balance                         # remaining credits per subscription
python3 $ADC services --search suno          # list/search subscribed services
python3 $ADC usage --days 7                   # recent API call records
python3 $ADC usage-summary --days 30          # spend aggregated by day + API
python3 $ADC keys                             # list API keys (credentials)
python3 $ADC orders --state Finished          # recharge orders
python3 $ADC tokens                           # platform tokens
python3 $ADC models                           # available chat models
python3 $ADC distributions                    # referral status + commission history

# Catalog & docs (PUBLIC — work without a token)
python3 $ADC get-service --service suno       # one service's detail
python3 $ADC pricing --service suno           # unit, free_amount and cost (dataset reference quotes when present)
python3 $ADC apis --service suno              # API endpoints for a service
python3 $ADC spec --path /suno/audios         # one API's OpenAPI definition + cost
python3 $ADC datasets                         # downloadable datasets
python3 $ADC integrations                     # third-party integrations
python3 $ADC docs-search --query "suno lyrics" --lang en   # full-text doc search
python3 $ADC docs-list                        # browse documentation pages
python3 $ADC doc --id <document-uuid>         # one doc's full content
python3 $ADC model-catalog --modality chat    # rich model catalog + credit pricing
python3 $ADC model --model claude             # look up a model by id/name

# Safe write (require --yes to actually execute)
python3 $ADC create-key  --application <app-id> --name "ci" --yes
python3 $ADC delete-key  --id <credential-id> --yes
python3 $ADC create-order --application <app-id> --package <package-id> --yes
python3 $ADC pay-order   --id <order-id> --pay-way Stripe --yes
python3 $ADC create-token --yes
python3 $ADC delete-token --id <token-id> --yes

# Admin (superuser token only)
python3 $ADC send-announcement --title "..." --content "..." --yes

每条命令都接受 --json，用于输出机器可读的数据；也接受 --token，用于覆盖环境变量中的令牌。若未指定 --yes，写入命令会打印试运行预览，然后退出，不会调用 API。

分页

列表端点返回 { "count": <total>, "items": [ ... ] }，并接受 ?limit= 和 ?offset=。（注意：一些较早的文档中写的是 results；实际字段是 items。）

端点参考

余额 / 订阅 — GET /applications/

Application 是你对一项 Service 的订阅；其 remaining_amount 是你在该服务中的余额，单位为 Credits。

curl -H "authorization: Bearer $ACEDATACLOUD_PLATFORM_TOKEN" \
  "https://platform.acedata.cloud/api/v1/applications/?limit=1"

{
  "count": 3,
  "items": [
    {
      "id": "e9f625f2-cbd5-4254-8264-cfadbd180428",
      "service_id": "f2b646d8-3cfd-46ef-969a-1ea9eebde329",
      "remaining_amount": 100.9,
      "used_amount": 1.1,
      "paid": false,
      "scope": "Global",
      "allow_consume_global": true,
      "expired_at": null,
      "type": "Usage"
    }
  ]
}

筛选条件：service_id、scope（Individual/Global）、user_id（仅限超级用户）。

使用记录 — GET /usage/apis/

逐次请求的调用记录（状态码、延迟、扣除的 Credits）。

筛选条件：api_id、application_id、status_code、created_at_from、created_at_to、user_id（仅限超级用户）。

{
  "count": 128,
  "items": [
    {
      "id": "c124684b-7188-4c3e-ad53-3fba5150b944",
      "api": { "title": "Suno Audios Generation API" },
      "status_code": 200,
      "original_amount": 0.55,
      "deducted_amount": 0.55,
      "trace_id": "…",
      "elapsed": 12.3,
      "created_at": "2026-06-28T09:15:44Z"
    }
  ]
}

• 支出汇总 — GET /usage/apis/aggregate/?created_at_from=&created_at_to= → { "items": [{ "date", "api_id", "amount" }], "total": <credits>, "apis": { "<id>": { "title" } } }
• 状态码筛选值 — GET /usage/apis/status-codes/ → { "items": [200, 400, 502] }
• CSV 导出 — GET /usage/apis/export/?created_at_from=&created_at_to=（下载 usages.csv）

服务 — GET /services/

{ "count": 215, "items": [ { "id": "…", "alias": "suno", "title": "Suno 音乐生成",
  "unit": "Credit", "free_amount": 0.0, "applied_count": 121733,
  "packages": [ { "id": "…", "type": "Usage", "price": 13.0, "amount": 100.0 } ] } ] }

API 密钥 / 凭证 — GET /credentials/

{ "count": 2, "items": [ { "id": "dae4899f-…", "name": "ci", "type": "Token",
  "token": "<secret>", "limited_amount": null, "used_amount": 1.1,
  "host": null, "created_at": "2026-06-28T09:15:44Z" } ] }

• 创建 — POST /credentials/ { "application_id": "<app>", "name": "ci", "limited_amount": 100, "expired_at": "2026-12-31T00:00:00Z" } → 返回包含新 token 的凭证。请保存；创建时才会完整显示该令牌。
• 删除 — DELETE /credentials/{id} → 204 No Content
• 筛选条件：application_id、host、granted（true/false）、user_id（超级用户）。
• 如需“轮换”密钥，请先删除，再创建一个新密钥。

订单（充值）— GET /orders/

{ "count": 12, "items": [ { "id": "17c10c9d-…", "application_id": "…",
  "package_id": "…", "description": "100 Credits", "price": 13.0,
  "state": "Finished", "pay_way": "Stripe", "pay_url": "<url>",
  "created_at": "2026-06-28T09:17:25Z" } ] }

• state ∈ Pending Paid Finished Expired Failed Refunded
• pay_way 包括 WechatPay、AliPay、Stripe、X402、PayPal、Reward 和 BankTransfer；具体可用方式取决于订单和支付配置。
• 创建 — POST /orders/ { "application_id": "<app>", "package_id": "<package>" }
• 支付 — POST /orders/{id}/pay/ { "pay_way": "Stripe" } → 返回包含待打开的 pay_url 的订单
• 刷新状态 — POST /orders/{id}/refresh/（重新检查 PSP 并更新 state）
• 筛选条件：state、pay_way、created_at_from、created_at_to、user_id（超级用户）。

银行转账

1. 以订单所有者身份进行身份验证。个人和企业账户无需企业验证即可使用 BankTransfer；匿名请求无法使用。境内 CNY 和国际 USD 转账都要求订单金额至少为 USD 300，具体还取决于支付渠道配置和套餐资格。
2. 在管理主机上读取 GET /api/v1/orders/{order_id}/payment-options/，检查当前转账渠道和最低金额。CLI 没有支付选项命令；请使用经过身份验证的 REST 接口，不要自行编造标志。不要公开内部渠道 / 服务商标识符。
3. 在执行 pay-order --id <order-id> --pay-way BankTransfer --yes 前，先与用户确认订单 ID、金额和可用渠道。仅使用该订单返回的支付说明；显示的 CNY 金额是权威金额，不应使用本地估算的汇率。支付响应并不能证明款项已到账：请重新读取订单，并确认其最终状态后再报告完成。

发票红冲与重新开票

1. 使用已认证的 GET /api/v1/orders/{order_id}/invoice/ 读取当前发票。CLI 没有发票命令。
2. 提交自动红字发票红冲后，发票仍会处于 Issued 状态；请检查 red_state 以了解进度。提交不代表已完成。在确认、开具红字发票或归档仍待处理时，请勿重新开票。
3. 只有在成功开具红字发票并完成归档，使原发票变为 Voided 且解除订单的开票限制后，才能重新开票。红冲失败或状态不确定时，必须由财务审核；请勿绕过限制。原发票仍保留在发票历史记录中。手动开具的发票必须先在税务／开票系统中作废或红冲，再由财务在平台中确认。

X402 网络选择

1. 选择网络前，先读取当前订单或 API 支付质询中的 accepts。Arbitrum One（官方 TypeScript/Python X402 客户端中的 arbitrum，链上使用的 CAIP-2 标识为 eip155:42161）仅有可选启用的代码支持，不保证生产环境可用。如果 accepts 中没有该网络，请勿尝试在该链上付款；页面功能开关不会启用未配置的服务端网络。
2. Arbitrum 仅支持使用原生 USDC（6 位小数）的 exact 付款，不支持桥接 USDC 或 upto。请使用返回的资产、收款方和 accepts[].maxAmountRequired；切勿硬编码金额或臆造付款参数。
3. 确认钱包支持目标链，且该链上有 USDC。同一个 EVM 地址在不同网络上的余额可能不同；Solana 地址不是 EVM USDC 地址。签名或付款前必须先获得确认；支持某网络不代表授权扣款。

X402 失败后的处理

1. 未携带 PAYMENT-SIGNATURE 的初始 HTTP 402 是支付质询，不代表付款失败。对于已签名付款的失败，请读取 extensions.acedatacloud.paymentError；切勿凭猜测构造钱包签名或收款方／资产地址。
2. 重新读取已认证的订单列表（orders --json）或 GET /api/v1/orders/{order_id}/。metadata.x402.last_error 和 metadata.x402.errors 会保留公开的 code、stage、retryable、charged 和 params；原因说明在 reason 中，时间记录在 timestamp 中。保留具体错误代码：insufficient_token_balance 表示所选网络上的 USDC 余额不足；invalid_signature 表示付款签名无效。重新读取后，请勿将任一错误替换为通用错误 payment_failed。
3. 只有明确显示 charged=false 才表示结算前已拒绝；若缺少 charged，则状态未知，不代表未扣款。再次付款前，请检查付款凭证。即使 retryable=true，Failed 订单也无法原地重试：解决钱包问题并获得确认后，再创建并支付新订单。
4. 仅向支持人员提供订单 ID 和公开错误代码。切勿记录或分享完整订单元数据、PAYMENT-SIGNATURE、钱包签名、授权负载或原始付款／RPC 诊断信息。

X402 ACE 回购与销毁证明

启用回购政策后，符合条件的 Base 主网 Circle USDC 和 Solana 主网 USDC 支付会将实际到账金额的 3% 用于购买并销毁 ACE，不会向钱包额外收费。充值只计入一次；将这些 Credits 用于 API 消费不会再次计入。历史折扣订单和旧政策下的订单不会自动追溯处理。每笔操作或每日的 USDC 回购没有固定上限；可用资金、市场报价和链上确认仍可能导致完成延迟。

1. 以订单所有者身份，在管理主机上读取经过身份验证的 GET /api/v1/orders/{order_id}/，并检查 ace_burn。CLI 仅列出订单，不提供订单详情或销毁命令；订单列表和匿名支付链接响应中不包含 ace_burn。如果该字段不存在或为 null，请勿推断订单符合条件，也不要伪造证明。
2. 区分支付收据（settlement_network、settlement_transaction）与异步 ACE 执行（execution_network）。Base 支付保留其 Base 收据；ACE 的购买与销毁发生在 Solana 上。Base 收据不是 Solana 销毁交易。请勿泄露运营方配置或内部资金详情。
3. 只有在 ace_burn.state=Completed 时，才能报告已验证的销毁完成，并使用实际返回的 swap_signature 和 burn_signature。Pending、Processing 或 Review 均不能证明销毁已完成，订单处于 Finished 状态也不能证明销毁已完成。Base 来源链的最终确认可能导致销毁延迟，但不会影响已入账的 Credits。重新读取同一订单以检查进度；请勿重复付款或创建另一笔订单来触发销毁。

平台令牌 — GET /platform-tokens/

{ "count": 2, "items": [ { "id": "efdccba4-…", "token": "<secret>",
  "expiration": null, "used_at": null, "created_at": "2026-06-28T06:29:02Z" } ] }

• 创建 — POST /platform-tokens/ → 返回新令牌（以 platform- 开头）
• 删除 — DELETE /platform-tokens/{id}/ → 204 No Content

模型 — GET /models/

OpenAI 风格（不分页）：{ "object": "list", "data": [ { "id": "gpt-4.1", "label": "GPT-4.1", "owned_by": "openai", "type": "chat", "capabilities": ["vision"] } ] }

目录与文档（公开 — 无需令牌）

无需身份验证即可使用（如果有令牌，可以发送；但并非必需）：

• 服务详情 / 定价 — GET /services/?id=<uuid> → items[0]（完整字段：cost、unit、 free_amount、title）。服务端会忽略 services/?alias= 筛选器，因此请分页读取 services/，并在客户端匹配 alias 以解析别名。services/{id}/ 详情路由不可用（500）。
• API — GET /apis/?path=<path> → 恰好返回一个条目，包含其 OpenAPI definition 和 cost。 服务端会忽略 apis/?service_id=；请在客户端按 service_id 筛选。apis/{id}/ 不可用（500）。
• 数据集 / 集成 — GET /datasets/、GET /integrations/。
• 文档搜索 — GET /search/?query=<text>&lang=<code> → { results: [ { id, alias, title, type, snippet, url } ] }。 参数为 query（不是 keyword）。
• 文档内容 — GET /documents/?id=<uuid> → items[0].content。documents/{id}/（id 或 slug）不可用（404）。
• 模型目录 — GET /models/catalog/ → { rates, modalities, count, items:[{ id, name, provider, modality, unit, capabilities, pricing:{ input_credits, output_credits, official_* } }] }。请在客户端筛选。

区域目录发现

1. 从调用方的环境中读取当前公共目录。使用 get-service --service <alias-or-uuid> --json 检查 available_regions、unavailable_regions、服务仅限聊天的 chat_unavailable_regions 以及仅限图像的 image_unavailable_regions。使用 apis --service <alias-or-uuid> --json、docs-list --json 或 doc --id <document-uuid> --json 查看 API／文档的区域字段。pricing 和 spec 摘要不包含这些字段。区域列表为空表示没有明确的区域规则，并不代表已获准访问。
2. 可见性取决于请求访客的 IP，而非显示语言或 ?country= 覆盖值。在中国大陆的目录视图中，带区域限制标记的 Claude 服务以及聊天 API／文档会被隐藏。混合 OpenAI、Gemini 和 Grok 服务会隐藏其聊天条目，但媒体可见性必须单独检查：在中国大陆，OpenAI 图像生成／编辑功能及相关指南也会被隐藏。不要根据 chat_unavailable_regions 或 image_unavailable_regions 隐藏整个服务；不相关的媒体条目仍遵循各自的规则。原始 REST／CLI 结果可能仍包含带标记的条目；展示选项时应应用其区域元数据，而不是将条目的存在视为可见。
3. 展示目录选项时应遵循当前公共结果。不要使用缓存的全局列表宣传在某个地区隐藏的聊天或图像，也不要将条目缺失／404 视为服务已下架或 API 访问权限已撤销的证据。这种展示筛选不会改变 API 路由或计费；调用服务前，应分别检查实际账户访问权限、密钥限制和当前价格。

数据集参考价格

1. 使用 get-service --service <alias-or-uuid> 查找所请求数据集对应的公共服务，并读取其当前元数据。仅限联系咨询的数据集属于目录条目，并非可自动购买的下载内容；缺少价格并不意味着数据免费。
2. 运行 pricing --service <alias-or-uuid> --json。对于 Dataset，CLI 在有相关信息时会包含 pricing_mode 和 reference_quote。这些源字段位于 Service 上的 metadata.pricing_mode 和 metadata.reference_quote，而非 Dataset 的 price 或 API 的 cost。
3. 如果 pricing_mode="contact_only" 且报价的 status="reference"，请使用所提供的 currency 和报价 unit，展示 min_amount–max_amount。CNY 金额的单位是元，不是 Credits 或 USD；full_package 表示整个套餐，tb 表示每 TB。上下限相同表示单一参考金额。不要应用 Credits 到 USD 的换算，也不要在未返回报价时编造报价。
4. 参考报价仅供参考：它不会创建购买 Package、保证交付，也不会授予下载或使用权。继续操作前，请与支持团队确认所需的版本、范围、格式、许可证和最终价格；不得根据参考报价调用 create-order 或 pay-order。

公告 — GET /announcements/

公开读取：{ "count": 20, "items": [ { "id", "title", "content", "translation_key", "published", "publish_at", "rank", "tags", "is_read" } ] }

仅限管理员（超级用户令牌）：

• 发布 — POST /announcements/admin/ { "title": "...", "content": "...", "rank": 5, "tags": ["product"], "published": true } （content 为 Markdown；系统会创建 zh-cn Translation 行，并通过 CronJob 自动翻译为其他语言）
• 编辑／删除 — PUT / DELETE /announcements/admin/{id}
• AI 润色 — POST /announcements/admin/polish/ { "title", "content" }
• AI 翻译 — POST /announcements/admin/translate/ { "translation_key" }

博客草稿、提交审核与发布（MCP / REST）

使用 mcp-acedatacloud 配合平台令牌或 Studio OAuth 连接。随附的 CLI 不支持博客命令；请使用 MCP 工具并检查其当前输入架构，不要臆造 CLI 标志。博客权限可以委派给非管理员账户；写入前请检查可用工具和权限范围。

权限	操作
blog:read	列出草稿并读取完整的编辑源内容
blog:write	创建、编辑和删除未发布的草稿；提交或撤回待审核内容
blog:read + blog:publish	批准或驳回已提交的版本，或在发布前撤回批准
blog:write + blog:publish	发布或安排发布已批准的草稿、取消发布，或删除已发布的文章

1. 确认目标文章和源语言（zh-cn 或 en）。使用当前编辑分类：product-updates、tech-sharing、product-recommendations 或 industry-insights（默认使用 tech-sharing）。如需自定义分类，请读取当前分类列表；不要猜测 slug。
2. 使用 acedatacloud_create_blog_draft 保存未发布的草稿，或使用 acedatacloud_update_blog_post 编辑草稿。使用 acedatacloud_get_blog_draft 读取完整源内容，包括标题、摘要、正文、分类、封面、content_type 和 video_url，并保留当前的 review_version 和 review_status。默认的 content_type="article" 要求正文非空，并会清除 video_url。对于 content_type="video"，请先上传目标视频，并使用其实际的 HTTPS video_url；正文可以为空，但标题和摘要仍为必填项。切勿伪造媒体 URL。封面需要 HTTPS cover_url 和非空的 cover_alt。如果发现的 MCP schema 缺少视频字段，请在确认后使用 POST /api/v1/blogs/admin/ 创建未发布的草稿，或使用 PATCH /api/v1/blogs/admin/{id}/ 编辑草稿；不要臆造 MCP 参数或 CLI 标志。
3. 在申请批准前，先将 draft 或 rejected 文章提交审核。使用 blog:write 时，在管理主机上向 /api/v1/blogs/admin/{id}/submit/ 发送 POST 请求，并附带 {"expected_version": CURRENT_REVIEW_VERSION}；确认 review_status="pending"。没有创建者的旧版草稿必须先由编辑保存。待审核文章无法编辑：向同一个 /submit/ 路由发送 DELETE 请求，并附带当前的 expected_version，以撤回审核申请；确认状态为 draft，然后编辑并重新提交。撤回待审核申请不同于撤回批准。
4. 另一位获授权的账号必须读取完整的待审核草稿（视频文章还须观看实际视频），并使用 acedatacloud_approve_blog_post 批准该确切版本。创建者不能批准自己的草稿。对于 REST 批准请求，向 /api/v1/blogs/admin/{id}/approval/ 发送 POST 请求，expected_version 必须与刚读取的 review_version 相同。审核者也可以改为向 /api/v1/blogs/admin/{id}/reject/ 发送 POST 请求，附带相同的 expected_version 和非空的 comment（最多 2,000 个字符）；如果当前版本上已有未解决的根审核线程，则可以省略 comment；确认 review_status="rejected"。读取 review_comment，修改并重新提交；再次审核前，请检查下方的审核线程。提交、撤回、批准或驳回时出现 409，表示草稿已更改：刷新并重新读取完整草稿后再重试。不要冒充审核者，也不要切换凭据来绕过这种职责分离。
5. 只有在 review_status="approved" 后，才能使用获授权账号调用 acedatacloud_publish_blog_post：发布者不能是审核者（创作者可在同伴批准后发布）。如需安排发布时间，请提供带时区的 publish_at；省略该参数则立即发布。在报告文章已公开上线前，请确认返回的状态和时间。
6. 对已审核公开内容的更改（包括标题、正文、分类、标签、slug、封面、content_type 或 video_url）会使批准失效，并递增 review_version。使用 acedatacloud_unpublish_blog_post 取消已发布文章的发布，再编辑、重新提交并取得新的同伴批准后，方可重新发布。文章未发布时，使用 acedatacloud_withdraw_blog_approval 撤销批准；已批准的文章会恢复为 draft。

审核讨论串（已认证 REST）

审核评论是私密的编辑反馈，不是公开的博客评论。使用管理主机和平台 Bearer 令牌。列出评论需要 blog:read；添加、回复和解决评论需要 blog:read，以及 blog:write 或 blog:publish。

1. 读取已保存的草稿和 GET /api/v1/blogs/admin/{id}/comments/。响应是包含嵌套 replies、锚点、review_version 和解决状态字段的根讨论串数组。将每个讨论串的版本与当前草稿进行比较；历史反馈无法证明某个选区仍与今天的文本匹配。
2. 预览并确认后，使用 POST /api/v1/blogs/admin/{id}/comments/ 添加根评论：发送当前的 expected_version、不为空且不超过 2,000 个字符的 body，以及不带偏移量或引文的 field="overall"。对于文本选区，使用 field="title"、"summary" 或 "content"，并提供 start_offset、end_offset 和完全一致的已保存 quote。偏移量按 UTF-16 代码单元计数，而非 Python 字符或 UTF-8 字节；起始位置包含在内，结束位置不包含在内，选区最多为 2,000 个代码单元。绝不要锚定到未保存的文本。如果返回 409，请刷新草稿并重新计算选区；如果引文不匹配，请重新读取已保存的源文本，不要猜测偏移量。
3. 使用 POST /api/v1/blogs/admin/{id}/comments/{comment_id}/replies/ 和 {"body":"REVIEW_REPLY"}（1–2,000 个非空字符）回复根讨论串。回复会保留根讨论串的审核版本；回复已解决的讨论串会重新打开。使用根评论 ID，而不是回复 ID。
4. 使用 PATCH /api/v1/blogs/admin/{id}/comments/{comment_id}/ 和 {"resolved":true} 或 {"resolved":false} 解决或重新打开根讨论串。回复和解决操作不需要 expected_version；发送前请重新读取讨论串，并确认其 ID 和预期操作。解决反馈并不代表草稿已获批准或发布；请保留上述同行评审工作流。

所有博客写入操作都需要预览并获得用户明确确认：未提供 confirm=true 时，MCP 工具只会返回试运行预览。上述 REST 审核路由会立即执行，且没有试运行标志：发送平台 Bearer 令牌前，请在本地预览方法、文章 ID 和请求正文，并获得确认。如果已发现的 MCP 工具架构支持该操作，请优先使用匹配的 MCP 工具；不要臆造提交/拒绝工具名称或 CLI 标志。执行前确认文章、版本和发布时间；预览成功并不能证明帖子已保存、已提交、已批准或已发布。如果缺少所需操作或权限，请停止并请求相应授权。

写入操作安全

创建/删除密钥、创建/支付订单、删除平台令牌，以及发布公告或博客均属于不可逆、涉及资金或公开可见的操作。务必：

1. 执行前与用户确认确切目标（application_id、order_id、credential_id）。
2. 使用 CLI 时，除非传入 --yes，否则写入操作均为试运行。
3. 绝不要在共享日志中打印完整的 token 值——它可授予账户访问权限。

注意事项

• 使用平台令牌（ACEDATACLOUD_PLATFORM_TOKEN），不要使用 api.acedata.cloud 服务令牌——后者在此处会返回 401。
• remaining_amount / used_amount / amount 的单位是 Credits，不是 USD。 使用服务的套餐进行换算：USD = Credits × (package.price / package.amount)。
• 新创建的凭证令牌/平台令牌只会完整返回一次——请立即保存。
• 凭证“轮换”实际上是删除并重新创建；没有原地轮换的端点。
• /admin/ 下的公告端点需要超级用户令牌；普通令牌会收到 403。

MCP： pip install mcp-acedatacloud | 托管地址：https://mcp.acedata.cloud/mcp | 查看所有 MCP 服务。MCP 会将这些功能作为工具公开（acedatacloud_get_balance、acedatacloud_list_usage、acedatacloud_get_pricing、acedatacloud_search_docs、acedatacloud_get_api_spec、acedatacloud_create_credential、……），并采用相同的写入确认保护机制。