@acedatacloud/sdk 2026.1009.1 → 2026.1012.0

package/README.md

@@ -1,9 +1,25 @@
 # AceDataCloud TypeScript SDK
 
-Official TypeScript/Node.js client for the [AceDataCloud API](https://platform.acedata.cloud).
+Official TypeScript/Node.js client for the [AceDataCloud API](https://platform.acedata.cloud?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=sdk_typescript_readme_platform).
 
 Requires Node.js 18+ (uses native `fetch`).
 
+## Get your Ace Data Cloud API key
+
+1. Open [Ace Data Cloud → Applications](https://platform.acedata.cloud/console/applications?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=sdk_typescript_readme_api_key). Sign in, or register an account first.
+2. Find **General application**. If it has not been created, choose **Initialize General Application**. A general key can use the services available to your account; a dedicated application's key is limited to its service. Check the required service/model access and [current pricing](https://platform.acedata.cloud/models?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=sdk_typescript_readme_pricing).
+3. Copy the **API Key** from the application card, or open **Keys / Manage Keys → Create** to create a separate key for this integration. Give it a recognizable name so you can revoke or rotate it independently.
+4. When creating a key, review **Expiration Time**, **Set Usage Limitation**, and **Allowed APIs**. Enable only the restrictions you need, allow the operations you will call, then click **Create** and copy the token from the key list. Task lookup does not grant permission to submit a generation. Confirm the application's balance can cover your first request; any trial allowance is whatever your account currently displays.
+5. Copy only the token value, without quotation marks, spaces, or `Bearer `. An API Key / API Token field expects this raw value; only a manually configured HTTP `Authorization` header needs the `Bearer ` prefix. A `platform-...` account-management token cannot replace a generation API key.
+
+![Copy an application API key or open Manage Keys](https://raw.githubusercontent.com/AceDataCloud/NanoBananaDify/2522b2f57210597af2db866445319334a1677a23/_assets/tutorial/get-api-key-en.png)
+
+![Create a separately named key with optional restrictions](https://raw.githubusercontent.com/AceDataCloud/NanoBananaDify/2522b2f57210597af2db866445319334a1677a23/_assets/tutorial/create-api-key-en.png)
+
+Save the key in the client's credential store or the environment variable shown below. Never put it in a prompt, shared workflow, screenshot, or Git commit. If authentication fails, check the full copied value, application/service access, expiration, usage limit, and balance before creating another key.
+
+Use this application key for API requests. SDK account-management methods require the separate credential described in their management documentation; do not interchange it with the API key. The optional x402 payment flow below is a separate way to pay for supported requests.
+
 ## Installation
 
 ```bash
@@ -139,6 +155,32 @@ The public model ID also works with `client.openai.images.generate(...)` and
 `client.openai.images.edit(...)`; those use the OpenAI-compatible fields
 (`image` for editing) and return response objects, not task handles.
 
+## Maestro Video Production
+
+Use the provider client to request one finished video in one language:
+
+```typescript
+const task = await client.maestro.generate({
+  prompt: 'Explain vector databases to beginners in 20 seconds',
+  langs: ['en'],
+  aspect: '9:16',
+  duration: 20,
+  scenario: 'narrated',
+});
+const result = await task.wait();
+```
+
+`langs` defaults to `['zh-cn']` and must contain exactly one language; create
+separate tasks for other languages. The completed result contains one video in
+`response.data.variants`. To revise a video, use `action: 'remix'`, `'edit'`, or
+`'extend'` with `refTaskId: task.id`.
+
+There is no quality tier: all videos use 1080p/30fps and target durations of
+5–300 seconds. Successful tasks cost **0.7 Credits per actual delivered second**,
+with integer billed seconds capped at the requested duration (falling back to
+that duration if it cannot be read). All scenarios, actions, and languages have
+the same rate; failed tasks and `/maestro/tasks` polling are free.
+
 ## Multi-Provider Support
 
 Image, video, and audio resources support a `provider` parameter to switch between services:

package/dist/index.js

@@ -1876,7 +1876,7 @@ var Maestro = class {
     this.transport = transport;
   }
   transport;
-  /** Call /maestro/videos. */
+  /** Maestro Videos */
   async generate(options) {
     const body = {};
     body["prompt"] = options.prompt;
@@ -1886,15 +1886,17 @@ var Maestro = class {
     body["langs"] = options.langs ?? ["zh-cn"];
     body["aspect"] = options.aspect ?? "9:16";
     body["duration"] = options.duration ?? 30;
-    body["quality"] = options.quality ?? "standard";
     body["scenario"] = options.scenario ?? "auto";
     body["style"] = options.style ?? "auto";
     body["voice"] = options.voice ?? "auto";
     for (const [key, value] of Object.entries(options)) {
-      if (!["action", "aspect", "async", "callbackUrl", "duration", "fileUrls", "langs", "maxWait", "pollInterval", "prompt", "quality", "refTaskId", "scenario", "style", "voice", "wait"].includes(key) && value !== void 0) {
+      if (!["action", "aspect", "async", "callbackUrl", "duration", "fileUrls", "langs", "maxWait", "pollInterval", "prompt", "refTaskId", "scenario", "style", "voice", "wait"].includes(key) && value !== void 0) {
         body[key] = value;
       }
     }
+    if (body["langs"].length !== 1) {
+      throw new Error("langs must contain exactly one item");
+    }
     if (options.callbackUrl !== void 0) body.callback_url = options.callbackUrl;
     body.async = options.async ?? true;
     const result = await this.transport.request("POST", "/maestro/videos", { json: body });