acedatacloud

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AceDataCloud Platform Management

AceDataCloud平台管理

Programmatically manage your AceDataCloud account: balances, usage records, API keys, services, orders, platform tokens, models, announcements and referral earnings — plus browse the public catalog & docs (service pricing, API specs, datasets, integrations, documentation search, model catalog) without a token.

This is the management / console API at

https://platform.acedata.cloud/api/v1

— the same surface the web console uses. It is different from the data-generation API at

api.acedata.cloud

(image / video / music / search generation).

通过编程方式管理您的AceDataCloud账户：余额、使用记录、API密钥、服务、订单、平台令牌、模型、公告与推荐收益 —— 此外无需令牌即可浏览公开目录与文档（服务定价、API规范、数据集、集成、文档搜索、模型目录）。

这是位于

https://platform.acedata.cloud/api/v1

的管理/控制台API —— 与Web控制台使用的是同一接口。它与位于

api.acedata.cloud

的数据生成API（图像/视频/音乐/搜索生成）不同。

Setup — use a PLATFORM token, not a service token

设置 —— 使用PLATFORM令牌，而非服务令牌

The management API is authenticated with a platform token (or a logged-in user token), not the per-service API token used for

api.acedata.cloud

Create one at platform.acedata.cloud/console/platform-tokens (or
```
POST /api/v1/platform-tokens/
```
). It starts with
```
platform-
```
and never expires.
Provide it one of two ways:
- Connector (recommended in studio / chat): install the AceDataCloud connector at auth.acedata.cloud/user/connections and paste the token once — the runtime injects
```
ACEDATACLOUD_PLATFORM_TOKEN
```
  into the sandbox automatically (this skill declares
```
connections: [acedatacloud]
```
  ).
- Local
  .env
  :

bash

ACEDATACLOUD_PLATFORM_TOKEN=platform-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

bash

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

A normal token only ever sees its own account data. A superuser token sees every user's data and is required for admin operations (announcements).

管理API通过平台令牌（或登录用户令牌）进行身份验证，而非用于

api.acedata.cloud

的按服务划分的API令牌。

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

bash

ACEDATACLOUD_PLATFORM_TOKEN=platform-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

bash

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

普通令牌仅能查看自身账户数据。超级用户令牌可查看所有用户的数据，是执行管理员操作（发布公告）所必需的。

CLI (preferred)

CLI（推荐方式）

The skill ships

scripts/acedatacloud.py

— a self-contained CLI (stdlib only) for the most common operations.

bash

ADC=$SKILL_DIR/scripts/acedatacloud.py

本技能附带了

scripts/acedatacloud.py

—— 一个独立的CLI工具（仅使用标准库），用于执行最常见的操作。

bash

ADC=$SKILL_DIR/scripts/acedatacloud.py

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

python3 $ADC balance # 查看各订阅服务的剩余额度 python3 $ADC services --search suno # 列出/搜索已订阅服务 python3 $ADC usage --days 7 # 查看近期API调用记录 python3 $ADC usage-summary --days 30 # 按日期+API汇总消费情况 python3 $ADC keys # 列出API密钥（凭证） python3 $ADC orders --state Finished # 查看充值订单 python3 $ADC tokens # 查看平台令牌 python3 $ADC models # 查看可用聊天模型 python3 $ADC distributions # 查看推荐状态+佣金历史

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

python3 $ADC get-service --service suno # 查看单个服务详情 python3 $ADC pricing --service suno # 查看单位、免费额度与成本 python3 $ADC apis --service suno # 查看某服务的API端点 python3 $ADC spec --path /suno/audios # 查看单个API的OpenAPI定义+成本 python3 $ADC datasets # 查看可下载数据集 python3 $ADC integrations # 查看第三方集成 python3 $ADC docs-search --query "suno lyrics" --lang en # 全文文档搜索 python3 $ADC docs-list # 浏览文档页面 python3 $ADC doc --id <document-uuid> # 查看单个文档的完整内容 python3 $ADC model-catalog --modality chat # 查看丰富的模型目录+额度定价 python3 $ADC model --model claude # 通过ID/名称查找模型

Safe write (require --yes to actually execute)

安全写入操作（需添加--yes参数才会实际执行）

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


Every command accepts `--json` for machine-readable output and `--token` to
override the env token. Without `--yes`, write commands print a dry-run preview
and exit without calling the API.

python3 $ADC send-announcement --title "..." --content "..." --yes


每个命令都支持`--json`参数以获取机器可读的输出，以及`--token`参数以覆盖环境变量中的令牌。如果不添加`--yes`参数，写入操作会打印试运行预览并退出，不会调用API。

Pagination

分页

List endpoints return

{ "count": <total>, "items": [ ... ] }

and accept

?limit=

and

?offset=

. (Note: some older docs say

results

; the live field is items
.)

列表接口返回

{ "count": <total>, "items": [ ... ] }

，并支持

?limit=

和

?offset=

参数。（注意：部分旧文档中写的是

results

；当前实际使用的字段是**

items

**。）

Endpoints reference

端点参考

Balance / subscriptions —

GET /applications/

余额/订阅服务 ——

GET /applications/

An Application is your subscription to one Service; its

remaining_amount

is your balance (in Credits) for that service.

bash

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

json

{
  "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"
    }
  ]
}

Filters:

service_id

scope

(

Individual

Global

user_id

(superuser only).

Application指您对某一服务的订阅；其

remaining_amount

字段是您该服务的余额（单位为Credits）。

bash

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

json

{
  "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

（仅超级用户可用）。

Usage records —

GET /usage/apis/

使用记录 ——

GET /usage/apis/

Per-request call records (status code, latency, credits deducted).

Filters:

api_id

application_id

status_code

created_at_from

created_at_to

user_id

(superuser only).

json

{
  "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"
    }
  ]
}

Spend aggregate —

GET /usage/apis/aggregate/?created_at_from=&created_at_to=

→

{ "items": [{ "date", "api_id", "amount" }], "total": <credits>, "apis": { "<id>": { "title" } } }

Status-code filter values —

GET /usage/apis/status-codes/

→

{ "items": [200, 400, 502] }

CSV export —

GET /usage/apis/export/?created_at_from=&created_at_to=

(downloads

usages.csv

)

按请求记录的调用详情（状态码、延迟、扣除的额度）。

筛选参数：

api_id

、

application_id

、

status_code

、

created_at_from

、

created_at_to

、

user_id

（仅超级用户可用）。

json

{
  "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

文件）

Services —

GET /services/

服务 ——

GET /services/

json

{ "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 } ] } ] }

json

{ "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 keys / credentials —

GET /credentials/

API密钥/凭证 ——

GET /credentials/

json

{ "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" } ] }

Create —

POST /credentials/

{ "application_id": "<app>", "name": "ci", "limited_amount": 100, "expired_at": "2026-12-31T00:00:00Z" }

→ returns the credential incl. the new

token

. Save it; it is shown in full only at creation.

Delete —
```
DELETE /credentials/{id}
```
→
```
204 No Content
```

Filters:

application_id

host

granted

(

true

false

user_id

(superuser).

To "rotate" a key, delete it and create a new one.

json

{ "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
```
（仅超级用户可用）。
如需“轮换”密钥，请先删除旧密钥再创建新密钥。

Orders (recharge) —

GET /orders/

订单（充值） ——

GET /orders/

json

{ "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

Create —

POST /orders/

{ "application_id": "<app>", "package_id": "<package>" }

Pay —

POST /orders/{id}/pay/

{ "pay_way": "Stripe" }

→ returns the order with a

pay_url

to open

Refresh status —
```
POST /orders/{id}/refresh/
```
(re-checks the PSP and updates
```
state
```
)

Filters:

state

pay_way

created_at_from

created_at_to

user_id

(superuser).

json

{ "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

创建 ——

POST /orders/

请求体

{ "application_id": "<app>", "package_id": "<package>" }

支付 ——
```
POST /orders/{id}/pay/
```
请求体
```
{ "pay_way": "Stripe" }
```
→ 返回包含
```
pay_url
```
的订单信息，打开该链接即可支付
刷新状态 ——
```
POST /orders/{id}/refresh/
```
（重新检查支付服务商状态并更新
```
state
```
字段）
筛选参数：
```
state
```
、
```
pay_way
```
、
```
created_at_from
```
、
```
created_at_to
```
、
```
user_id
```
（仅超级用户可用）。

Platform tokens —

GET /platform-tokens/

平台令牌 ——

GET /platform-tokens/

json

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

Create —
```
POST /platform-tokens/
```
→ returns the new token (starts with
```
platform-
```
)

Delete —

DELETE /platform-tokens/{id}/

→

204 No Content

json

{ "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

Models —

GET /models/

模型 ——

GET /models/

OpenAI-style (no pagination):

{ "object": "list", "data": [ { "id": "gpt-4.1", "label": "GPT-4.1", "owned_by": "openai", "type": "chat", "capabilities": ["vision"] } ] }

OpenAI风格（无分页）：

{ "object": "list", "data": [ { "id": "gpt-4.1", "label": "GPT-4.1", "owned_by": "openai", "type": "chat", "capabilities": ["vision"] } ] }

Catalog & docs (PUBLIC — no token required)

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

These work without auth (send the token if you have one; not required):

Service detail / pricing —
```
GET /services/?id=<uuid>
```
→
```
items[0]
```
(full:
```
cost
```
,
```
unit
```
,
```
free_amount
```
,
```
title
```
). The
```
services/?alias=
```
filter is ignored server-side, so resolve an alias by paging
```
services/
```
and matching
```
alias
```
client-side. The
```
services/{id}/
```
detail route is broken (500).
APIs —
```
GET /apis/?path=<path>
```
→ exactly one item with its OpenAPI
```
definition
```
+
```
cost
```
.
```
apis/?service_id=
```
is ignored server-side; filter by
```
service_id
```
client-side.
```
apis/{id}/
```
is broken (500).
Datasets / integrations —
```
GET /datasets/
```
,
```
GET /integrations/
```
.

Doc search —

GET /search/?query=<text>&lang=<code>

→

{ results: [ { id, alias, title, type, snippet, url } ] }

. The param is query
(not

keyword

Doc content —

GET /documents/?id=<uuid>

→

items[0].content

documents/{id}/

(id or slug) is broken (404).

Model catalog —

GET /models/catalog/

→

{ rates, modalities, count, items:[{ id, name, provider, modality, unit, capabilities, pricing:{ input_credits, output_credits, official_* } }] }

. Filter client-side.

这些接口无需身份验证即可使用（如有令牌也可携带；非必需）：

服务详情/定价 ——
```
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或别名）接口存在故障（返回404错误）。

模型目录 ——

GET /models/catalog/

→ 返回

{ rates, modalities, count, items:[{ id, name, provider, modality, unit, capabilities, pricing:{ input_credits, output_credits, official_* } }] }

。需在客户端筛选。

Announcements —

GET /announcements/

公告 ——

GET /announcements/

Public read:

{ "count": 20, "items": [ { "id", "title", "content", "translation_key", "published", "publish_at", "rank", "tags", "is_read" } ] }

Admin only (superuser token):

Publish —

POST /announcements/admin/

{ "title": "...", "content": "...", "rank": 5, "tags": ["product"], "published": true }

(

content

is Markdown; a zh-cn Translation row is created and other locales are auto-translated by a CronJob)

Edit / delete —
```
PUT
```
/
```
DELETE /announcements/admin/{id}
```

AI polish —

POST /announcements/admin/polish/

{ "title", "content" }

AI translate —

POST /announcements/admin/translate/

{ "translation_key" }

公开读取：

{ "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翻译条目，其他语言由定时任务自动翻译）
编辑/删除 ——
```
PUT
```
/
```
DELETE /announcements/admin/{id}
```

AI润色 ——

POST /announcements/admin/polish/

请求体

{ "title", "content" }

AI翻译 ——

POST /announcements/admin/translate/

请求体

{ "translation_key" }

Write-operation safety

写入操作安全注意事项

Creating/deleting keys, creating/paying orders, deleting platform tokens, and publishing announcements are irreversible or money-related. Always:

Confirm the exact target (
```
application_id
```
,
```
order_id
```
,
```
credential_id
```
) with the user before executing.
With the CLI, writes are dry-run unless
```
--yes
```
is passed.
Never print a full
```
token
```
value into shared logs — it grants account access.

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

在执行前与用户确认确切的目标（
```
application_id
```
、
```
order_id
```
、
```
credential_id
```
）。
使用CLI时，写入操作默认仅为试运行，需添加
```
--yes
```
参数才会实际执行。
切勿将完整的
```
token
```
值打印到共享日志中 —— 它会授予账户访问权限。

Gotchas

注意事项

Use the platform token (
```
ACEDATACLOUD_PLATFORM_TOKEN
```
), not the
```
api.acedata.cloud
```
service token — the latter returns 401 here.

remaining_amount

used_amount

amount

are in Credits, not USD. Convert with a service's package:

USD = Credits × (package.price / package.amount)

Newly created credential/platform tokens are returned in full only once — store them immediately.
Credential "rotate" is delete + recreate; there is no in-place rotate endpoint.
Announcement endpoints under
```
/admin/
```
require a superuser token; a normal token gets
```
403
```
.

MCP:
pip install mcp-acedatacloud
| Hosted:
https://mcp.acedata.cloud/mcp
| See all MCP servers. The MCP exposes these as tools (
acedatacloud_get_balance
,
acedatacloud_list_usage
,
acedatacloud_get_pricing
,
acedatacloud_search_docs
,
acedatacloud_get_api_spec
,
acedatacloud_create_credential
, …) with the same write-confirmation guard.

使用平台令牌（
```
ACEDATACLOUD_PLATFORM_TOKEN
```
），而非
```
api.acedata.cloud
```
的服务令牌 —— 后者在此处会返回401错误。

remaining_amount

used_amount

amount

的单位为Credits，而非美元。需通过服务套餐进行转换：

美元 = Credits × (套餐价格 / 套餐额度)

。

新创建的凭证/平台令牌仅会一次性完整返回 —— 请立即存储。
凭证“轮换”需先删除再创建；不存在原地轮换的接口。
```
/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
, …）暴露，同样带有写入确认防护。