acedatacloud

Files (2)

• SKILL.md
• acedatacloud.py · scripts/

SKILL.md (first lines)

# AceDataCloud Platform Management

Programmatically manage your AceDataCloud account: balances, usage records, API
keys, services, orders, platform tokens, models, announcements and referral
earnings, and manage article/video drafts, review threads and peer-reviewed blog publication through MCP / REST — 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).

### OAuth account access

OAuth access tokens authorize account-resource access; they are not model API Keys. OAuth consent does not create a Key, subscribe to a service, or add balance. For a third-party account connection:

1. Register the app at `https://auth.acedata.cloud/user/oauth-apps`. Read `available_scopes` from the authenticated `GET https://auth.acedata.cloud/api/v1/oauth2/applications/`, not the broader Discovery `scopes_supported` list. Request only registered permissions the user has: e.g., `profile:read credentials:read`, adding `credentials:write` only for confirmed Key changes and `offline_access` only if refresh is needed. Old `profile`, `email`, `phone`, and `platform` scopes are not accepted aliases; use explicit current scopes such as `profile:read` and `email:read`. The `account` selector is reserved for the designated official account MCP, not a third-party all-permissions scope.
2. Open `https://auth.acedata.cloud/oauth2/authorize` with `response_type=code`, `client_id`, the exact registered `redirect_uri`, space-separated `scope`, a fresh random `state`, and S256 PKCE. Public clients must use S256, not `plain`; keep the verifier in the application's own session. Verify callback state before exchanging the single-use code (valid for 10 minutes). Use `POST https://auth.acedata.cloud/oauth2/token` with form fields `grant_type=authorization_code`, `client_id`, `redirect_uri`, `code`, and `code_verifier`. Confidential clients also send server-side `client_secret` (`client_secret_post`, not HTTP Basic); never put a secret in a browser page. Read the actual granted `scope` and `expires_in`; no `id_token` is returned.
3. With the OAuth Bearer token, read `GET https://auth.acedata.cloud/api/v1/users/me`, then use its real `id` in `GET https://platform.acedata.cloud/api/v1/credentials/?user_id=<id>&limit=100&offset=0` if granted `credentials:read`. Read `items[*].token`, page with `offset`/`limit`, and choose a valid Key for the intended application/service rather than taking the first item. `user_id=me` is invalid. An empty list is not an authorization failure. Never display or log Keys, codes, tokens, or PKCE verifiers.
4. For a Studio website component using the current Studio account, configure the app ID and callback under Settings → Home → Website. Website and callback must share an HTTPS origin distinct from Studio; never configure a client secret. The page must implement `acedatacloud:oauth:ready`, `acedatacloud:oauth:init`, `acedatacloud:oauth:authorize`, and `acedatacloud:oauth:result`, validating the exact parent origin, parent window, and state; retain the verifier locally and exchange the returned code. This component requests `profile:read credentials:read`, not `offline_access` or blog permissions; each visitor must consent separately. It does not inject Studio's login token or a Key. Standard OAuth redirects do not require this message protocol or `embed=studio`/`embed_origin`; ordinary iframe first-login continuation has a known gap, so verify logged-out/expired sessions or use an independent page instead. On denial or `login_required`, restore a retryable connection state rather than looping authorization.
5. Refresh only if `offline_access` was granted, using the token endpoint with `grant_type=refresh_token` and the saved refresh token; retain the latest response. Refresh does not guarantee the old refresh token immediately becomes invalid. `POST https://auth.acedata.cloud/oauth2/revoke` with form field `token` currently returns HTTP 200 without immediate invalidation of issued JWTs. Clear your own saved connection state, but do not report that all tokens are revoked. Copied API Keys must be separately revoked or rotated in credential management.

The bundled CLI does not register OAuth apps or perform the browser/PKCE exchange. For `invalid_scope`, check the app's registered scopes, delegation restrictions, and user permissions rather than broadening access. Verify denial, state mismatch, expired/consumed code, missing scopes, no Keys, network failures, token expiry, and iframe account changes before relying on a connection.

## 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 (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
```

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

From AceDataCloud/Skills, Apache-2.0.

More from AceDataCloud/Skills