wavespeed 0.0.15 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 WaveSpeedAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,22 @@
-# WaveSpeed JavaScript/TypeScript Client
+<div align="center">
+  <a href="https://wavespeed.ai" target="_blank" rel="noopener noreferrer">
+    <img src="https://raw.githubusercontent.com/WaveSpeedAI/waverless/main/docs/images/wavespeed-dark-logo.png" alt="WaveSpeedAI logo" width="200"/>
+  </a>
 
-A JavaScript/TypeScript client for the WaveSpeed AI image generation API. This client is compatible with both JavaScript and TypeScript projects.
+  <h1>WaveSpeedAI JavaScript SDK</h1>
+
+  <p>
+    <strong>Official JavaScript/TypeScript SDK for the WaveSpeedAI inference platform</strong>
+  </p>
+
+  <p>
+    <a href="https://wavespeed.ai" target="_blank" rel="noopener noreferrer">🌐 Visit wavespeed.ai</a> •
+    <a href="https://wavespeed.ai/docs">📖 Documentation</a> •
+    <a href="https://github.com/WaveSpeedAI/wavespeed-javascript/issues">💬 Issues</a>
+  </p>
+</div>
+
+---
 
 ## Installation
 
@@ -8,185 +24,111 @@ A JavaScript/TypeScript client for the WaveSpeed AI image generation API. This c
 npm install wavespeed
 ```
 
-## Usage
+## API Client
 
-### JavaScript
+Run WaveSpeed AI models with a simple API:
 
 ```javascript
-const { WaveSpeed } = require('wavespeed');
-
-// Initialize the client with your API key
-const client = new WaveSpeed('YOUR_API_KEY');
-
-// Generate an image and wait for the result
-async function generateImage() {
-  const prediction = await client.run(
-    'wavespeed-ai/flux-dev',
-    {
-      prompt: 'A futuristic cityscape with flying cars and neon lights',
-      size: '1024*1024',
-      num_inference_steps: 28,
-      guidance_scale: 5.0,
-      num_images: 1,
-      seed: -1,
-      enable_safety_checker: true
-    }
-  );
-
-  // Print the generated image URLs
-  prediction.outputs.forEach((imgUrl, i) => {
-    console.log(`Image ${i+1}: ${imgUrl}`);
-  });
-}
-
-generateImage().catch(console.error);
-```
-
-### TypeScript
-
-```typescript
-import WaveSpeed from 'wavespeed';
+import wavespeed from 'wavespeed';
 
-// Initialize the client with your API key
-const client = new WaveSpeed('YOUR_API_KEY');
+const output = await wavespeed.run(
+  "wavespeed-ai/z-image/turbo",
+  { prompt: "Cat" }
+);
 
-// Generate an image and wait for the result
-async function generateImage(): Promise<void> {
-  const input: Record<string, any> = {
-    prompt: 'A futuristic cityscape with flying cars and neon lights',
-    size: '1024*1024',
-    num_inference_steps: 28,
-    guidance_scale: 5.0,
-    num_images: 1,
-    seed: -1,
-    enable_safety_checker: true
-  };
+console.log(output["outputs"][0]);  // Output URL
+```
 
-  const prediction = await client.run('wavespeed-ai/flux-dev', input);
+### Authentication
 
-  // Print the generated image URLs
-  prediction.outputs.forEach((imgUrl, i) => {
-    console.log(`Image ${i+1}: ${imgUrl}`);
-  });
-}
+Set your API key via environment variable (You can get your API key from [https://wavespeed.ai/accesskey](https://wavespeed.ai/accesskey)):
 
-generateImage().catch(console.error);
+```bash
+export WAVESPEED_API_KEY="your-api-key"
 ```
 
-### Manual Status Polling Example
-
-If you need more control over the polling process, you can use the `create` method and manually poll for status updates:
-
-```typescript
-import WaveSpeed from 'wavespeed';
-
-// Initialize the client with your API key
-const client = new WaveSpeed('YOUR_API_KEY');
-
-async function generateWithManualPolling(): Promise<void> {
-  // Create a prediction without waiting
-  const prediction = await client.create('wavespeed-ai/flux-dev', {
-    prompt: 'A beautiful mountain landscape at sunset',
-    size: '1024*1024',
-    num_inference_steps: 28,
-    guidance_scale: 5.0,
-    num_images: 1
-  });
-
-  console.log(`Prediction created with ID: ${prediction.id}`);
-  console.log(`Initial status: ${prediction.status}`);
-
-  // Manually poll for status updates
-  let currentPrediction = prediction;
-  
-  while (currentPrediction.status !== 'completed' && currentPrediction.status !== 'failed') {
-    console.log('Prediction still processing, checking again in 2 seconds...');
-    await new Promise(resolve => setTimeout(resolve, 2000));
-    
-    // Reload the prediction to get the latest status
-    currentPrediction = await currentPrediction.reload();
-    console.log(`Updated status: ${currentPrediction.status}`);
-  }
-  
-  if (currentPrediction.status === 'completed') {
-    console.log('Prediction completed successfully!');
-    currentPrediction.outputs.forEach((imgUrl, i) => {
-      console.log(`Image ${i+1}: ${imgUrl}`);
-    });
-  } else {
-    console.error(`Prediction failed: ${currentPrediction.error}`);
-  }
-}
+Or pass it directly:
 
-generateWithManualPolling().catch(console.error);
-```
+```javascript
+import { Client } from 'wavespeed';
 
-## API Reference
+const client = new Client("your-api-key");
+const output = await client.run("wavespeed-ai/z-image/turbo", { prompt: "Cat" });
+```
 
-### WaveSpeed Client
+### Options
 
-```typescript
-new WaveSpeed(apiKey?: string, options?: {
-  baseUrl?: string,
-  pollInterval?: number,
-  timeout?: number
-})
+```javascript
+const output = await wavespeed.run(
+  "wavespeed-ai/z-image/turbo",
+  { prompt: "Cat" },
+  {
+    timeout: 36000.0,       // Max wait time in seconds (default: 36000.0)
+    pollInterval: 1.0,      // Status check interval (default: 1.0)
+    enableSyncMode: false,  // Single request mode, no polling (default: false)
+  }
+);
 ```
 
-#### Parameters:
-- `apiKey` (string): Your WaveSpeed API key
-- `options` (object, optional):
-  - `baseUrl` (string): API base URL (default: 'https://api.wavespeed.ai/api/v2/')
-  - `pollInterval` (number): Interval in seconds for polling prediction status (default: 1)
-  - `timeout` (number): Timeout in seconds for API requests (default: 60)
+### Sync Mode
 
-### Methods
+Use `enableSyncMode: true` for a single request that waits for the result (no polling).
 
-#### run
+> **Note:** Not all models support sync mode. Check the model documentation for availability.
 
-```typescript
-run(modelId: string, input: Record<string, any>, options?: RequestOptions): Promise<Prediction>
+```javascript
+const output = await wavespeed.run(
+  "wavespeed-ai/z-image/turbo",
+  { prompt: "Cat" },
+  { enableSyncMode: true }
+);
 ```
 
-Generate an image and wait for the result.
+### Retry Configuration
+
+Configure retries at the client level:
 
-#### create
+```javascript
+import { Client } from 'wavespeed';
 
-```typescript
-create(modelId: string, input: Record<string, any>, options?: RequestOptions): Promise<Prediction>
+const client = new Client("your-api-key", {
+  maxRetries: 0,            // Task-level retries (default: 0)
+  maxConnectionRetries: 5,  // HTTP connection retries (default: 5)
+  retryInterval: 1.0,       // Base delay between retries in seconds (default: 1.0)
+});
 ```
 
-Create a prediction without waiting for it to complete.
+### Upload Files
 
-### Prediction Model
+Upload images, videos, or audio files:
 
-The Prediction object contains information about an image generation job:
+```javascript
+import wavespeed from 'wavespeed';
 
-```typescript
-prediction.id           // Unique ID of the prediction
-prediction.model        // Model ID used for the prediction
-prediction.status       // Status of the prediction (processing, completed, failed)
-prediction.input        // Input parameters used for the prediction
-prediction.outputs      // List of output image URLs
-prediction.urls.get     // URL to get the prediction status
-prediction.has_nsfw_contents // List of booleans indicating if each image has NSFW content
-prediction.created_at   // Creation timestamp
-prediction.error        // Error message (if any)
-prediction.executionTime // Time taken to execute the prediction in milliseconds
+const url = await wavespeed.upload("/path/to/image.png");
+console.log(url);
 ```
 
-#### Methods
+## Running Tests
+
+```bash
+# Run all tests
+npm test
 
-```typescript
-prediction.wait(): Promise<Prediction>  // Wait for the prediction to complete
-prediction.reload(): Promise<Prediction>  // Reload the prediction status
+# Run a single test file
+npm test -- tests/test_api.ts
+
+# Run a specific test
+npm test -- tests/test_api.ts -t "run success"
 ```
 
 ## Environment Variables
 
-- `WAVESPEED_API_KEY`: Your WaveSpeed API key
-- `WAVESPEED_POLL_INTERVAL`: Interval in seconds for polling prediction status (default: 1)
-- `WAVESPEED_TIMEOUT`: Timeout in seconds for API requests (default: 60)
+### API Client
+
+| Variable | Description |
+|----------|-------------|
+| `WAVESPEED_API_KEY` | WaveSpeed API key |
 
 ## License
 

package/dist/api/client.d.ts

@@ -0,0 +1,157 @@
+/**
+ * WaveSpeed API client implementation.
+ */
+/**
+ * Run options interface.
+ */
+export interface RunOptions {
+    timeout?: number;
+    pollInterval?: number;
+    enableSyncMode?: boolean;
+    maxRetries?: number;
+}
+/**
+ * WaveSpeed API client.
+ *
+ * Example:
+ *     const client = new Client("your-api-key");
+ *     const output = await client.run("wavespeed-ai/z-image/turbo", { prompt: "Cat" });
+ *
+ *     // With sync mode (single request, waits for result)
+ *     const output2 = await client.run("wavespeed-ai/z-image/turbo", { prompt: "Cat" }, { enableSyncMode: true });
+ *
+ *     // With retry
+ *     const output3 = await client.run("wavespeed-ai/z-image/turbo", { prompt: "Cat" }, { maxRetries: 3 });
+ */
+export declare class Client {
+    private apiKey;
+    private baseUrl;
+    readonly connectionTimeout: number;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    readonly maxConnectionRetries: number;
+    readonly retryInterval: number;
+    /**
+     * Initialize the client.
+     *
+     * Args:
+     *     apiKey: WaveSpeed API key. If not provided, uses wavespeed.config.api.apiKey.
+     *     options.baseUrl: Base URL for the API. If not provided, uses wavespeed.config.api.baseUrl.
+     *     options.connectionTimeout: Timeout for HTTP requests in seconds.
+     *     options.timeout: Total API call timeout in seconds.
+     *     options.maxRetries: Maximum number of retries for the entire operation.
+     *     options.maxConnectionRetries: Maximum retries for individual HTTP requests.
+     *     options.retryInterval: Base interval between retries in seconds.
+     */
+    constructor(apiKey?: string, options?: {
+        baseUrl?: string;
+        connectionTimeout?: number;
+        timeout?: number;
+        maxRetries?: number;
+        maxConnectionRetries?: number;
+        retryInterval?: number;
+    });
+    /**
+     * Get request headers with authentication.
+     */
+    private _getHeaders;
+    /**
+     * Submit a prediction request.
+     *
+     * Args:
+     *     model: Model identifier.
+     *     input: Input parameters.
+     *     enableSyncMode: If true, wait for result in single request.
+     *     timeout: Request timeout in seconds.
+     *
+     * Returns:
+     *     Tuple of [requestId, result]. In async mode, result is null.
+     *     In sync mode, requestId is null and result contains the response.
+     *
+     * Throws:
+     *     Error: If submission fails after retries.
+     */
+    private _submit;
+    /**
+     * Get prediction result.
+     *
+     * Args:
+     *     requestId: The prediction request ID.
+     *     timeout: Request timeout in seconds.
+     *
+     * Returns:
+     *     Full API response.
+     *
+     * Throws:
+     *     Error: If fetching result fails after retries.
+     */
+    private _getResult;
+    /**
+     * Wait for prediction to complete.
+     *
+     * Args:
+     *     requestId: The prediction request ID.
+     *     timeout: Maximum wait time in seconds (undefined = no timeout).
+     *     pollInterval: Time between polls in seconds.
+     *
+     * Returns:
+     *     Dict with "outputs" array.
+     *
+     * Throws:
+     *     Error: If prediction fails.
+     *     Error: If prediction times out.
+     */
+    private _wait;
+    /**
+     * Determine if an error is worth retrying at the task level.
+     *
+     * Args:
+     *     error: The exception to check.
+     *
+     * Returns:
+     *     True if the error is retryable.
+     */
+    private _isRetryableError;
+    /**
+     * Run a model and wait for the output.
+     *
+     * Args:
+     *     model: Model identifier (e.g., "wavespeed-ai/flux-dev").
+     *     input: Input parameters for the model.
+     *     options.timeout: Maximum time to wait for completion (undefined = no timeout).
+     *     options.pollInterval: Interval between status checks in seconds.
+     *     options.enableSyncMode: If true, use synchronous mode (single request).
+     *     options.maxRetries: Maximum task-level retries (overrides client setting).
+     *
+     * Returns:
+     *     Dict containing "outputs" array with model outputs.
+     *
+     * Throws:
+     *     Error: If API key is not configured.
+     *     Error: If the prediction fails.
+     *     Error: If the prediction times out.
+     */
+    run(model: string, input?: Record<string, any>, options?: RunOptions): Promise<Record<string, any>>;
+    /**
+     * Upload a file to WaveSpeed.
+     *
+     * Args:
+     *     file: File path string to upload.
+     *     options.timeout: Total API call timeout in seconds.
+     *
+     * Returns:
+     *     URL of the uploaded file.
+     *
+     * Throws:
+     *     Error: If API key is not configured.
+     *     Error: If file path does not exist.
+     *     Error: If upload fails.
+     *
+     * Example:
+     *     const url = await client.upload("/path/to/image.png");
+     *     console.log(url);
+     */
+    upload(file: string, options?: {
+        timeout?: number;
+    }): Promise<string>;
+}