# speedpix-javascript

**Repository Path**: aliyun/speedpix-javascript

## Basic Information

- **Project Name**: speedpix-javascript
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpeedPix JavaScript SDK

Official JavaScript SDK for SpeedPix API (AIGC Service Lab), supporting Node.js and browser environments.

## 📚 About AIGC Service Lab

AIGC Service Lab (智作工坊) is an AIGC generation service launched by Alibaba Cloud Education, primarily providing efficient AIGC (Artificial Intelligence Generated Content) PAAS services for pan-education and design business enterprises.

### 🎯 Core Features
- **Text-to-Image**: Generate high-quality images from text descriptions
- **Image-to-Image**: Style transfer or content transformation based on input images
- **Text-to-Video**: Convert text descriptions into dynamic video content
- **Image-to-Video**: Transform static images into dynamic videos

### 🔧 Technical Support
- Supports **Tongyi Wanxiang** and open-source **Stable Diffusion** models
- Provides both **WEB UI** and **ComfyUI** modes
- Integrates Alibaba Cloud's strict **content security detection service**
- Supports custom interface deployment and permission management

### 📖 Documentation
- [AIGC Service Lab Documentation](https://help.aliyun.com/document_detail/2804197.html)
- [Product Overview](https://help.aliyun.com/document_detail/2804199.html)
- [AIGC Service Lab Console](https://eduplatform-sp.console.aliyun.com/)

---

## Installation

```bash
npm install speedpix
```

## Configuration

Two configuration methods are available:

### Method 1: Environment Variables (Recommended)

```bash
export SPEEDPIX_ENDPOINT=your-endpoint.com  # Optional, defaults to https://openai.edu-aliyun.com
export SPEEDPIX_APP_KEY=your-app-key        # Required
export SPEEDPIX_APP_SECRET=your-app-secret  # Required
```

```javascript
// Auto-load from environment variables
const client = new SpeedPix();
```

### Method 2: Constructor Parameters

```javascript
// Explicit configuration
const client = new SpeedPix({
  endpoint: "your-endpoint.com",
  appKey: "your-app-key",
  appSecret: "your-app-secret"
});
```

## Quick Start

### Simplest Usage

> **Note: Environment variables can be set optionally**
> ```bash
> export SPEEDPIX_ENDPOINT=your-endpoint.com  # Optional, defaults to https://openai.edu-aliyun.com
> export SPEEDPIX_APP_KEY=your-app-key        # Required
> export SPEEDPIX_APP_SECRET=your-app-secret  # Required
> ```

```javascript
const speedpix = require("speedpix");

// Run workflow (using default client, auto-loads from env vars)
const output = await speedpix.run("workflow-id", {
  input: {
    prompt: "A cute kitten"
  },
  aliasId: "main" // Version alias, defaults to "main"
});

// Handle output
if (output.url) {
  await output.url.save("result.png");
  console.log("Image saved");
}
```

### Standard Usage

```javascript
const SpeedPix = require("speedpix");

// Using environment variables
const client = new SpeedPix();

// Run workflow
const output = await client.run("workflow-id", {
  input: {
    prompt: "A cute kitten"
  },
  aliasId: "main" // Version alias, defaults to "main"
});

// Handle output
if (output.url) {
  await output.url.save("result.png");
  console.log("Image saved");
}
```

### ESM Module

```javascript
import SpeedPix from "speedpix";

const client = new SpeedPix(); // Using environment variables

const output = await client.run("workflow-id", {
  input: { prompt: "Generate image" },
  aliasId: "main" // Version alias, defaults to "main"
});

if (output.url) {
  await output.url.save("result.png");
}
```

### TypeScript

```typescript
import SpeedPix from "speedpix";

const client = new SpeedPix(); // Using environment variables

const output = await client.run("workflow-id", {
  input: { prompt: "TypeScript example" },
  aliasId: "main" // Version alias, defaults to "main"
});
```

## Main Features

### 1. Run Workflows

```javascript
// Sync execution (wait for completion)
const output = await client.run("workflow-id", {
  input: {
    prompt: "Beautiful landscape",
    style: "oil painting"
  },
  aliasId: "main" // Version alias, defaults to "main"
});

// Async execution (don't wait)
const prediction = await client.run("workflow-id", {
  input: { prompt: "Complex scene" },
  aliasId: "main", // Version alias, defaults to "main"
  wait: false
});

console.log(`Task ID: ${prediction.id}`);
const result = await prediction.wait();
```

### 2. File Upload

```javascript
// Upload local file
const file = await client.files.create("./image.jpg");

// Use in workflow
const output = await client.run("workflow-id", {
  input: {
    image: file.accessUrl,
    prompt: "Process this image"
  },
  aliasId: "main" // Version alias, defaults to "main"
});
```

### 3. Output Handling

Output is always a map structure:

```javascript
const output = await client.run("workflow-id", { input: {...} });

// Single file output
if (output.url) {
  await output.url.save("result.png");
  console.log("Download URL:", output.url.toString());
}

// Multiple outputs
if (output.image1) {
  await output.image1.save("image1.png");
}
if (output.image2) {
  await output.image2.save("image2.png");
}
```

### 4. Error Handling

```javascript
try {
  const output = await client.run("workflow-id", { input: {...} });
} catch (error) {
  if (error instanceof SpeedPix.SpeedPixTimeoutError) {
    console.log("Request timeout");
  } else if (error instanceof SpeedPix.SpeedPixError) {
    console.log("API error:", error.message);
  } else {
    console.log("Unknown error:", error.message);
  }
}
```

## API Reference

### Module-level Functions (Simplest)

> **Note: Required environment variables SPEEDPIX_APP_KEY, SPEEDPIX_APP_SECRET must be set**
> **SPEEDPIX_ENDPOINT is optional and defaults to https://openai.edu-aliyun.com**

```javascript
const speedpix = require("speedpix");

// Direct module-level function (uses default client, auto-loads from env vars)
await speedpix.run(workflowId, options);
```

### SpeedPix Class

```javascript
// Method 1: Using environment variables
const client = new SpeedPix();

// Method 2: Explicit parameters
const client = new SpeedPix({
  endpoint: "string",     // Required: API endpoint
  appKey: "string",       // Required: App key
  appSecret: "string",    // Required: App secret
  userAgent: "string"     // Optional: User agent
});
```

### run() Method

```javascript
await client.run(workflowId, options);
```

**Parameters:**
- `workflowId` (string): Workflow ID
- `options` (object):
  - `input` (object): Input parameters
  - `aliasId` (string): Version alias, defaults to "main"
  - `resourceConfigId` (string, optional): Resource config ID
  - `wait` (boolean, optional): Whether to wait for completion, defaults to true
  - `timeout` (number, optional): Timeout in seconds

### files.create() Method

```javascript
const file = await client.files.create(filePath);
```

**Returns:**
- `file.accessUrl`: File access URL
- `file.id`: File ID

## License

MIT