acedatacloud

# AceDataCloud Platform Management 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). ## Setup — use a PLATFORM token, not a service token 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`. 1. Create one at [platform.acedata.cloud/console/platform-tokens](https://platform.acedata.cloud/console/platform-tokens) (or `POST /api/v1/platform-tokens/`). It starts with `platform-` and never expires. 2. Provide it one of two ways: - **Connector (recommended in studio / chat):** install the **AceDataCloud** connector at [studio.acedata.cloud/console/connectors](https://studio.acedata.cloud/console/connectors) 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). ## CLI (preferred) The skill ships [`scripts/acedatacloud.py`](scripts/acedatacloud.py) — a self-contained CLI (stdlib only) for the most common operations. ```bash # $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 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 ``` 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. ## Pagination List endpoints return `{ "count": <total>, "items": [ ... ] }` and accept `?limit=` and `?offset=`. (Note: some older docs say `results`; the live field is **`items`**.) ## Endpoints reference ### Balance / subscriptions — `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). ### Usage records — `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`) ### 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 } ] } ] } ``` ### API keys / credentials — `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. ### Orders (recharge) — `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). ### 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` ### 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"] } ] }` ### 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,