---

name: api-guide description: Set up an AceDataCloud API key, make a first request, and troubleshoot authentication, access, billing, and asynchronous tasks. Use before calling an AceDataCloud service for the first time. license: Apache-2.0 metadata: author: acedatacloud version: "1.1" compatibility: Requires an AceDataCloud account; get a service API key at https://platform.acedata.cloud/console/applications.

AceDataCloud API: from account to first result

This guide is the source for the existing @acedatacloud/api-guide ClawHub listing. A ClawHub login installs Skills; an AceDataCloud API key authorizes calls to api.acedata.cloud. They are different credentials.

1. Install the right Skill

Install the ClawHub CLI if needed, then install the service Skill you intend to use:

npm install -g clawhub
clawhub install @acedatacloud/suno
clawhub list

For a different first workflow, choose its Skill, such as clawhub install @acedatacloud/google-search. Verify that the publisher is @acedatacloud. The general API guide explains setup; the service Skill contains its exact request fields, models, and task endpoint.

2. Find or create your API key

1. Sign in at AceDataCloud → Applications. Create an account if needed.
2. Open General application; initialize it if prompted. Its API key can access multiple services enabled for your account. A service-specific application key is limited to that service. Check access, balance, and the current price of the service you want to call.
3. Copy an existing key, or select Manage Keys → Create. Name a new key (for example, OpenClaw), set expiration and restrictions if needed, and copy the key value from the application card or key list. If Allowed APIs is restricted, include every route needed for your first workflow. An asynchronous generation needs both the submit and task-query routes.

The illustrated repository guide shows where to copy a key and how to create a separate one. Copy only the key value. Do not include Bearer in the value, put it in a prompt, or commit it. A platform-... management token is for the separate account-management API, not for service generation, chat, or search.

3. Configure the key

On the OpenClaw Gateway host, add this line to ~/.openclaw/.env:

ACEDATACLOUD_API_TOKEN=your_api_key_here

Keep the file private with chmod 600 ~/.openclaw/.env, restart the Gateway, and start a new session. OpenClaw loads this global file even when the Gateway runs as a service. For a direct terminal test instead:

export ACEDATACLOUD_API_TOKEN="your_api_key_here"

4. Make one first request

This Google Search example returns a result without a separate task query. Check current service pricing first; API requests may be billable. The key must allow /serp/google:

curl -X POST https://api.acedata.cloud/serp/google \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"AceDataCloud","type":"search"}'

For image, video, or music generation, follow that service Skill's Quick Start. If a submission returns a task_id, save it and query the matching /tasks endpoint until the task is terminal. Use async: true where the service supports it; set callback_url only for a real public webhook that you own. Do not resubmit a pending generation merely to check it: a second submission can incur a second charge. See the task-polling guide.

5. Troubleshoot the first run

Symptom	Check
401	Key copied completely, not expired, and available to the running Gateway. Bearer belongs in the HTTP header, not the key value.
403	Service entitlement, key restrictions, and Allowed APIs. A content-moderation rejection may also be 403; read the response.
400	Exact endpoint, model, and JSON shape from the service Skill.
429	Reduce request rate or concurrency. Do not automatically retry a billable submit.
Pending, timeout, or 5xx	Query the original task or request history before submitting again.

The AceDataCloud account console shows balance and usage. Share a task or trace ID with support, never your API key. For service-specific examples, see @acedatacloud/suno, @acedatacloud/nano-banana, and @acedatacloud/ai-chat.