# SeaCloud SDK

Official SeaCloud SDK for JavaScript/TypeScript - Call SeaCloud AI services with ease.

> **Note**: This package is part of the [SeaVerse SDK Monorepo](https://github.com/seaverseai/sv-sdk).

## Features

- 🤖 **Agent Chat API** - Multi-turn conversations, tool calling, streaming output
- 🎨 **Image Generation** - Support for multiple AI image generation models
- 🎬 **Video Generation** - Text-to-Video, Image-to-Video
- 🎵 **Music Generation** - Song and lyrics generation
- 🔄 **Streaming Response** - Real-time AI responses
- 📦 **TypeScript Support** - Complete type definitions
- 🚀 **Zero Dependencies** - Lightweight and fast
- 🛠️ **CLI Tool** - Command-line interface included

## Installation

```bash
# Using pnpm (recommended)
pnpm install seaspark-seaclaude-sdk

# Using npm
npm install seaspark-seaclaude-sdk

# Using yarn
yarn add seaspark-seaclaude-sdk
```

## Quick Start

### Initialize SDK

```typescript
import { initSeacloud, agentChatCompletions, createTextMessage } from 'seaspark-seaclaude-sdk';

// Initialize SDK
initSeacloud({
  apiKey: 'your-api-key',
  baseUrl: 'https://seaspark-seacloud-proxy-rs.dev.seaspark.ai',
  xProject: 'SeaVerse',  // Optional, defaults to 'SeaVerse'
});
```

### Simple Chat

```typescript
const response = await agentChatCompletions({
  agent_id: 'seagen_agent',
  messages: [
    createTextMessage('user', 'Hello! How are you?')
  ],
  model: 'gpt-4o',
});

console.log(response.choices[0].message.content);
```

### Streaming Chat

```typescript
const stream = await agentChatCompletions({
  agent_id: 'seagen_agent',
  messages: [
    createTextMessage('user', 'Tell me a story')
  ],
  model: 'gpt-4o',
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}
```

## Configuration Options

### initSeacloud(options)

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `apiKey` | `string` | - | API key, can also be set via `API_SERVICE_TOKEN` environment variable |
| `baseUrl` | `string` | `https://seaspark-seacloud-proxy-rs.dev.seaspark.ai` | API server URL |
| `timeout` | `number` | `30000` | Request timeout in milliseconds |
| `intervalMs` | `number` | `3000` | Polling interval in milliseconds |
| `maxAttempts` | `number` | `100` | Maximum polling attempts |
| `xProject` | `string` | `'SeaVerse'` | X-Project header value for project identification |

### xProject Parameter

The `xProject` parameter sets the `X-Project` request header to identify the source project. Different projects may have different quotas and permissions:

```typescript
// SeaVerse project
initSeacloud({
  apiKey: 'your-api-key',
  xProject: 'SeaVerse',
});

// KIIRA project
initSeacloud({
  apiKey: 'your-api-key',
  xProject: 'KIIRA',
});

// Default: SeaVerse
initSeacloud({
  apiKey: 'your-api-key',
  // xProject defaults to 'SeaVerse'
});
```

## Token Priority

The SDK retrieves API tokens in the following priority order:

1. `apiKey` passed to `initSeacloud({ apiKey: '...' })`
2. Browser environment: `localStorage.getItem('auth_token')`
3. Node.js environment: `process.env.API_SERVICE_TOKEN`

## Environment Variables

| Variable | Description |
|----------|-------------|
| `API_SERVICE_TOKEN` | API key |
| `SEACLOUD_BASE_URL` | API server URL |

## API Reference

### Agent Chat API

```typescript
import { agentChatCompletions, createTextMessage, createImageMessage, createTool } from 'seaspark-seaclaude-sdk';

// Text message
const textMessage = createTextMessage('user', 'Hello!');

// Image message
const imageMessage = createImageMessage('user', 'What is this?', 'https://example.com/image.jpg');

// Create tool
const tool = createTool('seagen_text2image_flux1d_artifact_tool');
```

### Available Tools

**Image Generation:**
- `seagen_text2image_flux1d_artifact_tool`
- `seagen_text2image_seedream40_artifact_tool`
- `seagen_text2image_google_gemini3_pro_image_artifact_tool`
- `seagen_blackforestlabs_flux_2_pro_tool`
- `mm_volces_seedream_4_5_gateway_tool`

**Image Editing:**
- `seagen_edit_image_google_artifact_tool`
- `seagen_blackforestlabs_flux_2_pro_edit_tool`

**Video Generation:**
- `seagen_image2video_wanx26_artifact_tool`
- `seagen_text2video_wanx26_artifact_tool`
- `seagen_image2video_seedance_pro_fast_artifact_tool`
- `mm_text2video_kling_v2_6_gateway_tool`
- `mm_image2video_kling_v2_6_i2v_gateway_tool`

**Music Generation:**
- `seagen_text2song_mureka_artifact_tool`
- `seagen_text2lyrics_mureka_artifact_tool`

## Examples

For more examples, see [examples_agent.ts](./examples_agent.ts)

## License

MIT