@acedatacloud/sdk 2026.1011.0 → 2026.1018.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
@@ -165,6 +181,38 @@ 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.
 
+## Fish voice models
+
+`client.fish.model({ title, voices: audioUrl })` creates a reusable voice from a
+single publicly downloadable audio URL string, not an array or a multipart
+upload. Prefer a direct URL ending in `.mp3` or `.wav`. Successful creation
+returns the model object directly (HTTP 201); its `_id` can be used as
+`referenceId` in `client.fish.generate`.
+
+Created voices are stored publicly long-term and may be searched and used by
+other users. Omit `visibility`: passing `private` or `unlist` does not make the
+voice private. For temporary reference audio without creating a saved model,
+use `client.fish.generate({ text, references: [{ audio: audioUrl, text: transcript }] })`.
+
+`client.audio.listFishModels({ selfOnly: true, pageSize: 20, pageNumber: 1 })`
+lists voices created and saved through this platform by the calling account,
+including voices created with its other API tokens. This only filters the list;
+it does not restrict public use. Results are paginated in reverse creation order;
+`sortBy` supports `created_at` and `task_count`, and `authorId` can further filter
+them. Do not combine `selfOnly: true` with `titleLanguage`; that filter is for
+the public library. Responses contain `total`, `items`, and `has_more`;
+`has_more` is boolean for self queries and may be `null` for public-library queries.
+
+## File uploads
+
+`client.files.upload(fileBytes, { filename: 'photo.jpg' })` uses the
+management-plane account token, not a generation API key. Use a separate client
+configured with that token. Uploads return `file_url` and `mime`; use the returned
+URL rather than constructing one. The platform assigns an `uploads/<uuid>` path
+and preserves a safe filename extension. Supply a filename matching the actual
+content: MIME inference from the filename does not convert the file. The default
+single-file limit is 100 MB.
+
 ## Multi-Provider Support
 
 Image, video, and audio resources support a `provider` parameter to switch between services:

package/dist/index.d.mts

@@ -288,6 +288,7 @@ type AudioProvider = 'suno' | 'producer' | 'fish' | (string & {});
 declare class Audio {
     private transport;
     constructor(transport: Transport);
+    /** selfOnly filters this account's platform-created voices; it does not make them private. */
     listFishModels(opts?: {
         pageSize?: number;
         pageNumber?: number;

package/dist/index.d.ts

@@ -288,6 +288,7 @@ type AudioProvider = 'suno' | 'producer' | 'fish' | (string & {});
 declare class Audio {
     private transport;
     constructor(transport: Transport);
+    /** selfOnly filters this account's platform-created voices; it does not make them private. */
     listFishModels(opts?: {
         pageSize?: number;
         pageNumber?: number;

package/dist/index.js

@@ -730,6 +730,7 @@ var Audio = class {
     this.transport = transport;
   }
   transport;
+  /** selfOnly filters this account's platform-created voices; it does not make them private. */
   async listFishModels(opts = {}) {
     const { pageSize, pageNumber, title, tag, selfOnly, authorId, language, titleLanguage, sortBy } = opts;
     const params = {};