npm package: @magic-ai-tools/ai-api-gateway-client
Description: TypeScript client SDK for AI API Gateway
Latest version: 1.0.9

# AI API Gateway Client

A type-safe TypeScript/JavaScript client SDK for the AI API Gateway.

## Installation

```bash
npm install ai-api-gateway-client
```

## Quick Start

```typescript
import { createClient } from 'ai-api-gateway-client';

// Create a client instance
const client = createClient({
  baseUrl: 'https://your-gateway.com',
  apiKey: 'your-api-key',
  system: 'your-system-code',
  defaultWatermark: 'your-watermark' // Optional default watermark
});

// Generate an image with Flux 1 Schnell
const result = await client.fluxSchnell({
  prompt: 'A beautiful sunset over the ocean',
  aspectRatio: '16:9'
});

console.log('Task ID:', result.data.taskId);
```

## Configuration

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `baseUrl` | `string` | Yes | Base URL of the AI API Gateway |
| `apiKey` | `string` | Yes | API key for authentication |
| `system` | `string` | Yes | System identifier for your application |
| `defaultWatermark` | `string` | No | Default watermark text for all requests |

## Available APIs

### Image Generation

#### Flux 1 Schnell

Fast image generation with good quality.

```typescript
const result = await client.fluxSchnell({
  prompt: 'A cyberpunk cityscape at night',
  aspectRatio: '16:9', // '1:1' | '16:9' | '9:16' | '3:2' | '2:3'
  seed: 12345, // Optional: for reproducible results
  watermarkText: 'custom-watermark', // Optional: override default
  webHookUrl: 'https://your-webhook.com/callback' // Optional
});
```

#### GPT Image 1

Advanced image generation and editing.

```typescript
const result = await client.gptImage1({
  prompt: 'A portrait in impressionist style',
  size: '1024x1024', // Optional
  variants: 2, // Optional: number of variants
  urls: ['https://example.com/reference.jpg'], // Optional: reference images
  watermarkText: 'custom-watermark',
  webHookUrl: 'https://your-webhook.com/callback'
});
```

#### Seedream 4

High-quality image generation with multiple variants.

```typescript
const result = await client.seedream4({
  prompt: 'A serene mountain landscape',
  aspectRatio: '16:9', // '1:1' | '16:9' | '9:16' | '3:2' | '2:3' | '3:4' | '4:3' | '21:9'
  resolution: '2K', // '1K' | '2K' | '4K'
  variants: 3, // 1-6
  urls: ['https://example.com/reference.jpg'], // Optional
  watermarkText: 'custom-watermark',
  webHookUrl: 'https://your-webhook.com/callback'
});
```

#### Imagen 4 Ultra

Google's advanced image generation.

```typescript
const result = await client.imagen4Ultra({
  prompt: 'A photorealistic portrait',
  aspectRatio: '1:1', // '1:1' | '16:9' | '9:16' | '4:3' | '3:4'
  watermarkText: 'custom-watermark',
  webHookUrl: 'https://your-webhook.com/callback'
});
```

### Image Transformation

#### Nano Banana

```typescript
const result = await client.nanoBanana({
  prompt: 'Transform to anime style',
  aspectRatio: '1:1',
  urls: ['https://example.com/source.jpg'],
  watermarkText: 'custom-watermark',
  webHookUrl: 'https://your-webhook.com/callback'
});
```

#### Nano Banana Pro

Advanced transformation with resolution and format options.

```typescript
const result = await client.nanoBananaPro({
  prompt: 'Transform to watercolor painting',
  aspectRatio: '1:1',
  urls: ['https://example.com/source.jpg'],
  resolution: '2K', // '1K' | '2K' | '4K'
  outputFormat: 'png', // 'jpg' | 'png'
  watermarkText: 'custom-watermark',
  webHookUrl: 'https://your-webhook.com/callback'
});
```

### Image Processing

#### Remove Background

```typescript
const result = await client.rmBg({
  imageUrl: 'https://example.com/photo.jpg',
  watermarkText: 'custom-watermark',
  webHookUrl: 'https://your-webhook.com/callback'
});
```

### Task Management

#### Get Task

```typescript
const task = await client.getTask('task-id-here');
console.log('Status:', task.data.status);
console.log('Outputs:', task.data.outputs);
```

#### List Tasks

```typescript
const tasks = await client.listTasks({
  page: 1,
  pageSize: 20
});

console.log('Total:', tasks.data.pagination.total);
tasks.data.tasks.forEach(task => {
  console.log(`${task.id}: ${task.status}`);
});
```

#### Retry Webhook

```typescript
const result = await client.retryWebhook('task-id-here');
console.log('Webhook status:', result.data.webHookStatus);
```

## Error Handling

The client throws `AiApiGatewayError` for API errors:

```typescript
import { createClient, AiApiGatewayError } from 'ai-api-gateway-client';

try {
  const result = await client.fluxSchnell({
    prompt: 'A beautiful sunset',
    aspectRatio: '16:9'
  });
} catch (error) {
  if (AiApiGatewayError.isAiApiGatewayError(error)) {
    console.error('API Error:', error.message);
    console.error('Error Code:', error.code);
    console.error('Status Code:', error.statusCode);
    console.error('Response:', error.response);
  } else {
    throw error;
  }
}
```

## TypeScript Support

The client is written in TypeScript and provides full type definitions:

```typescript
import type {
  ClientConfig,
  ApiResponse,
  TaskResponse,
  Task,
  FluxSchnellParams,
  GptImage1Params,
  // ... other types
} from 'ai-api-gateway-client';
```

## Release

```bash
npm run build
#npm login # or set accessToken
npm config set //registry.npmjs.org/:_authToken npm_xxxxxxxxxxxxxxxxxxxxxxxx
npm publish --access public


```

## Credit

Thanks zzo.ai for the donation.

- [Zzo AI](https://zzo.ai/)


## License

MIT