SeaCloud SDK

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

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

Installation

pnpm install seacloud-sdk

Quick Start

Initialize SDK

import { initSeacloud, agentChatCompletions, createTextMessage } from 'seacloud-sdk';

// Initialize SDK
initSeacloud({
  apiKey: 'your-api-key',
  appId: 'my-app-123',  // Optional, application identifier
  baseUrl: 'https://proxy-rs.seaverse.ai',
  xProject: 'SeaVerse',  // Optional, defaults to 'SeaVerse'
});

Simple Chat

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

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 | | appId | string | - | Application ID, can be set via APP_ID environment variable or localStorage.app_id | | baseUrl | string | https://proxy-rs.seaverse.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:

// 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'
});

appId Parameter

The appId parameter sets the X-App-ID request header to identify the specific application instance. This allows backend services to:

• Isolate data by application
• Manage quotas per application
• Track usage and logs

// Set appId explicitly
initSeacloud({
  apiKey: 'your-api-key',
  appId: 'my-app-123',
});

// Auto-retrieve from localStorage (browser)
// localStorage.setItem('app_id', 'my-app-123');
initSeacloud({ apiKey: 'your-api-key' });

// Auto-retrieve from parent page (iframe)
// SDK will send PostMessage to request appId
initSeacloud();

For iframe integration, the parent page should respond to seaverse:get_appId messages.

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
4. iframe environment: PostMessage from parent page

App ID Priority

The SDK retrieves App ID in the following priority order:

1. appId passed to initSeacloud({ appId: '...' })
2. Browser environment: localStorage.getItem('app_id')
3. Node.js environment: process.env.APP_ID
4. iframe environment: PostMessage from parent page

Environment Variables

| Variable | Description | |----------|-------------| | API_SERVICE_TOKEN | API key | | APP_ID | Application ID | | SEACLOUD_BASE_URL | API server URL |

API Reference

Agent Chat API

import { agentChatCompletions, createTextMessage, createImageMessage, createTool } from 'seacloud-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

License

MIT