seacloud-sdk 0.10.0 → 0.10.1

package/README.md

@@ -0,0 +1,969 @@
+# SeaCloud SDK
+
+<div align="center">
+
+**统一的 AI 服务 SDK for JavaScript/TypeScript**
+
+[![npm version](https://img.shields.io/npm/v/seacloud-sdk.svg)](https://www.npmjs.com/package/seacloud-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+
+</div>
+
+---
+
+## 📖 概述
+
+**SeaCloud SDK** 是一个全面的 TypeScript/JavaScript SDK，提供对 100+ 种 AI 模型和服务的统一访问，包括：
+
+- 🤖 **LLM 聊天补全** - Claude、GPT、Gemini、DeepSeek、Kimi 等 40+ 种模型
+- 🎨 **图像生成** - FLUX、WANx、Seedream、Imagen 等
+- 🎬 **视频生成** - Kling、Vidu、Sora、PixelVerse、Runway
+- 🛡️ **内容安全扫描** - NSFW 检测、暴力、政治内容识别
+- 🤖 **Agent 智能体** - 工具调用、多模态生成、会话管理
+- 🎵 **音频与 3D** - TTS、音乐生成、3D 模型创建
+
+---
+
+## ✨ 特性
+
+- ✅ **100+ AI 模型** - 通过单一接口访问最新最强的 AI 模型
+- ✅ **类型安全** - 完整的 TypeScript 支持，全面的类型定义
+- ✅ **流式支持** - Server-Sent Events (SSE) 实现实时响应
+- ✅ **智能任务管理** - 自动轮询和状态跟踪
+- ✅ **多环境支持** - 可在 Node.js、浏览器和 iframe 环境中使用
+- ✅ **灵活的 Token 管理** - 多种身份验证方式
+- ✅ **CLI 工具** - 命令行接口快速测试
+- ✅ **零依赖** - 使用原生 fetch API，最小化体积
+
+---
+
+## 📦 安装
+
+```bash
+# npm
+npm install seacloud-sdk
+
+# yarn
+yarn add seacloud-sdk
+
+# pnpm
+pnpm add seacloud-sdk
+```
+
+**环境要求**: Node.js 18+ 或支持 fetch API 的现代浏览器
+
+---
+
+## 🚀 快速开始
+
+### 1. 初始化 SDK
+
+```typescript
+import { initSeacloud } from 'seacloud-sdk';
+
+// 方式 1: 使用 API Key 简单初始化
+initSeacloud('your-api-key');
+
+// 方式 2: 完整配置
+initSeacloud({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://proxy-rs.seaverse.ai',
+  timeout: 30000,
+  intervalMs: 3000,    // 轮询间隔
+  maxAttempts: 100     // 最大轮询次数
+});
+
+// 方式 3: 从环境变量自动检测
+initSeacloud();
+```
+
+### 2. LLM 聊天（基础）
+
+```typescript
+import { llmChatCompletions } from 'seacloud-sdk';
+
+const response = await llmChatCompletions({
+  model: 'deepseek-v3.1',
+  messages: [
+    { role: 'user', content: '你好！你怎么样？' }
+  ],
+  max_tokens: 1000
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### 3. LLM 聊天（流式）
+
+```typescript
+const stream = await llmChatCompletions({
+  model: 'gpt-4o',
+  messages: [
+    { role: 'user', content: '写一首关于 AI 的诗' }
+  ],
+  stream: true
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
+}
+```
+
+### 4. 图像生成
+
+```typescript
+import { alibabaWanx21T2iTurbo } from 'seacloud-sdk';
+
+const result = await alibabaWanx21T2iTurbo({
+  input: {
+    prompt: '一幅美丽的山间日落',
+    negative_prompt: '模糊，低质量'
+  },
+  parameters: {
+    size: '1024*1024',
+    n: 1
+  }
+});
+
+console.log(result[0].url); // 图像 URL
+```
+
+### 5. 内容安全扫描
+
+```typescript
+import { scan } from 'seacloud-sdk';
+
+const result = await scan({
+  uri: 'https://example.com/image.jpg',
+  risk_types: ['EROTIC', 'VIOLENT'],
+  detected_age: 0,
+  is_video: 0
+});
+
+console.log('风险等级:', result.nsfw_level); // 0-6
+console.log('标签:', result.label_items);
+```
+
+---
+
+## 📚 文档
+
+### 配置
+
+#### 环境变量
+
+```bash
+# .env 文件
+API_SERVICE_TOKEN=your-api-key-here
+SEACLOUD_BASE_URL=https://proxy-rs.seaverse.ai  # 可选
+```
+
+#### Token 优先级
+
+SDK 按以下顺序获取 API Token：
+
+1. **提供的 `apiKey`** 参数（在 `initSeacloud()` 中）
+2. **浏览器 `localStorage.auth_token`**（浏览器环境）
+3. **环境变量 `process.env.API_SERVICE_TOKEN`**（Node.js）
+4. **父页面 PostMessage**（iframe 环境）
+
+---
+
+### 核心 API
+
+#### 🤖 LLM 聊天补全
+
+访问 100+ 种 LLM 模型进行聊天和文本生成。
+
+**支持的模型：**
+- Claude: `seaart-mix-sonnet-4-5`, `seacloud-claude-opus-4.5`, `seacloud-claude-haiku-4.5`
+- GPT: `gpt-4o`, `gpt-4o-mini`, `gpt-4.1`, `gpt-5`
+- DeepSeek: `deepseek-v3.1`, `deepseek-r1`
+- Gemini: `gemini-2.5-pro`, `gemini-2.5-flash`
+- Kimi: `kimi-k2`, `kimi-k2-thinking`
+- Grok: `grok-4`, `grok-code-fast-1`
+- Qwen: `qwen-plus`, `qwen3-coder-plus`
+- GLM: `glm-4.5-air`, `glm-4.6`
+- 还有 30+ 种模型...
+
+```typescript
+import { llmChatCompletions } from 'seacloud-sdk';
+
+// 非流式
+const response = await llmChatCompletions({
+  model: 'deepseek-v3.1',
+  messages: [
+    { role: 'system', content: '你是一个有用的助手。' },
+    { role: 'user', content: '解释量子计算' }
+  ],
+  temperature: 0.7,
+  max_tokens: 2000,
+  top_p: 0.9
+});
+
+// 流式
+const stream = await llmChatCompletions({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: '给我讲个故事' }],
+  stream: true
+});
+
+for await (const chunk of stream) {
+  const content = chunk.choices[0]?.delta?.content;
+  if (content) process.stdout.write(content);
+}
+```
+
+---
+
+#### 🤖 Agent 聊天补全
+
+具有工具调用和多模态能力的智能 Agent。
+
+**功能：**
+- 多轮对话和会话管理
+- 工具调用（图像/视频/音乐生成）
+- 流式和非流式响应
+- 多模态输入（文本、图像、视频）
+
+```typescript
+import {
+  agentChatCompletions,
+  createTextMessage,
+  createImageMessage,
+  createTool
+} from 'seacloud-sdk';
+
+// 简单文本聊天
+const response = await agentChatCompletions({
+  agent_id: 'seaverse_agent',
+  messages: [
+    createTextMessage('user', '生成一张美丽的风景图片')
+  ],
+  model: 'gpt-4o',
+  seq: 0
+});
+
+if (response.artifacts) {
+  console.log('已生成:', response.artifacts[0].url);
+}
+
+// 多轮对话
+const response1 = await agentChatCompletions({
+  agent_id: 'seaverse_agent',
+  messages: [createTextMessage('user', '什么是 AI？')],
+  model: 'gpt-4o',
+  seq: 0
+});
+
+const sessionId = response1.session_id;
+
+const response2 = await agentChatCompletions({
+  agent_id: 'seaverse_agent',
+  session_id: sessionId,
+  messages: [
+    createTextMessage('user', '什么是 AI？'),
+    { role: 'assistant', content: [{ type: 'text', text: response1.choices[0].message.content }] },
+    createTextMessage('user', '给我举个例子')
+  ],
+  model: 'gpt-4o',
+  seq: 1
+});
+
+// 图像分析
+const response3 = await agentChatCompletions({
+  agent_id: 'seaverse_agent',
+  messages: [
+    createImageMessage('user', '这张图片里有什么？', 'https://example.com/image.jpg')
+  ],
+  model: 'gpt-4o',
+  seq: 0
+});
+
+// 自定义工具
+const imageTool = createTool('seacloud_fast_text_to_image');
+const videoTool = createTool('seacloud_fast_text_to_video');
+
+const response4 = await agentChatCompletions({
+  agent_id: 'seaverse_agent',
+  messages: [createTextMessage('user', '创建一个日落视频')],
+  tools: [videoTool],
+  model: 'gpt-4o',
+  seq: 0
+});
+```
+
+**可用工具：**
+- `seacloud_fast_text_to_image` - 快速图像生成
+- `seacloud_fast_text_to_video` - 快速视频生成
+- `seacloud_music_generation` - 音乐生成
+- `seacloud_image_edit_google` - 图像编辑
+- `seacloud_flux_pro_edit` - FLUX 图像编辑
+
+---
+
+#### 🛡️ 内容安全扫描
+
+检测图像和视频中的不安全内容。
+
+**风险类型：**
+- `POLITY` - 政治内容
+- `EROTIC` - 成人/NSFW 内容
+- `VIOLENT` - 暴力和血腥
+- `CHILD` - 儿童安全问题
+
+```typescript
+import { scan } from 'seacloud-sdk';
+
+// 图像扫描
+const imageResult = await scan({
+  uri: 'https://example.com/image.jpg',
+  risk_types: ['EROTIC', 'VIOLENT'],
+  detected_age: 0,  // 0=不检测年龄, 1=检测年龄
+  is_video: 0       // 0=图像, 1=视频
+});
+
+console.log('风险等级:', imageResult.nsfw_level); // 0-6 (0=安全, 6=最高风险)
+console.log('标签:', imageResult.label_items);    // ['person', 'outdoor', ...]
+console.log('风险:', imageResult.risk_types);      // ['EROTIC']
+
+// 视频扫描（逐帧）
+const videoResult = await scan({
+  uri: 'https://example.com/video.mp4',
+  risk_types: ['EROTIC', 'VIOLENT'],
+  detected_age: 1,
+  is_video: 1
+});
+
+console.log('时长:', videoResult.video_duration);
+console.log('帧数:', videoResult.frame_count);
+console.log('帧结果:', videoResult.frame_results);
+// [
+//   { frame_no: 0, nsfw_level: 0, label_items: [...] },
+//   { frame_no: 1, nsfw_level: 1, label_items: [...] },
+//   ...
+// ]
+
+// Base64 图像扫描
+const base64Result = await scan({
+  img_base64: 'data:image/jpeg;base64,/9j/4AAQ...',
+  risk_types: ['EROTIC'],
+  detected_age: 0,
+  is_video: 0
+});
+```
+
+---
+
+#### 🎨 图像生成模型
+
+访问来自各种提供商的 50+ 种图像生成模型。
+
+##### 阿里巴巴 WANx 系列
+
+```typescript
+import {
+  alibabaWanx21T2iTurbo,
+  alibabaWanx25T2i,
+  alibabaWanx26T2i,
+  alibabaWanx21I2i
+} from 'seacloud-sdk';
+
+// 文本到图像
+const result = await alibabaWanx26T2i({
+  input: {
+    prompt: '一只可爱的柯基犬在花园里玩耍',
+    negative_prompt: '模糊，低质量，扭曲'
+  },
+  parameters: {
+    size: '1024*1024',  // 或 '768*1024', '1024*768'
+    n: 1,
+    seed: 42,           // 可选：用于可重现性
+    ref_mode: 'repaint' // 可选：参考模式
+  }
+});
+
+console.log(result[0].url);
+
+// 图像到图像
+const i2iResult = await alibabaWanx21I2i({
+  input: {
+    prompt: '转换为水彩画',
+    image_url: 'https://example.com/input.jpg'
+  },
+  parameters: {
+    size: '1024*1024',
+    n: 1
+  }
+});
+```
+
+##### Black Forest Labs FLUX 系列
+
+```typescript
+import {
+  blackforestlabsFlux2Pro,
+  blackforestlabsFlux11Pro,
+  blackforestlabsFluxFlex,
+  blackforestlabsFluxProEdit
+} from 'seacloud-sdk';
+
+// FLUX Pro（最高质量）
+const fluxResult = await blackforestlabsFlux2Pro({
+  prompt: '一位女性的逼真肖像',
+  width: 1024,
+  height: 1024,
+  prompt_upsampling: false,
+  seed: 12345,
+  safety_tolerance: 2
+});
+
+// FLUX 图像编辑
+const editResult = await blackforestlabsFluxProEdit({
+  prompt: '给人物添加墨镜',
+  image_url: 'https://example.com/portrait.jpg',
+  width: 1024,
+  height: 1024
+});
+```
+
+##### Volces Seedream 系列
+
+```typescript
+import {
+  volcesSeedream45,
+  volcesSeededit3,
+  volcesSeedance
+} from 'seacloud-sdk';
+
+// 图像生成
+const seedreamResult = await volcesSeedream45({
+  prompt: '云中的幻想城堡',
+  negative_prompt: '模糊',
+  width: 1024,
+  height: 1024,
+  seed: 123,
+  scale: 7.5
+});
+
+// 图像编辑
+const editResult = await volcesSeededit3({
+  prompt: '将天空改为日落',
+  image_url: 'https://example.com/landscape.jpg'
+});
+```
+
+##### Google 系列
+
+```typescript
+import {
+  googleGemini2Image,
+  googleImagen4Generate,
+  googleVeo2
+} from 'seacloud-sdk';
+
+// Gemini 图像生成
+const geminiResult = await googleGemini2Image({
+  prompt: '科技创业公司的极简 logo 设计',
+  number_of_images: 4,
+  aspect_ratio: '1:1', // '1:1', '3:4', '4:3', '9:16', '16:9'
+  negative_prompt: 'text, watermark'
+});
+
+// Imagen 4（最高质量）
+const imagenResult = await googleImagen4Generate({
+  prompt: '超逼真的美食摄影',
+  number_of_images: 1,
+  aspect_ratio: '16:9'
+});
+```
+
+---
+
+#### 🎬 视频生成模型
+
+使用 40+ 种视频模型从文本或图像生成视频。
+
+##### Kling 系列（字节跳动）
+
+```typescript
+import {
+  klingV26,
+  klingV25Turbo,
+  klingV21Master,
+  klingOmni,
+  klingAvatar,
+  klingLipsync
+} from 'seacloud-sdk';
+
+// 文本到视频
+const videoResult = await klingV26({
+  prompt: '一只猫在玩毛线球',
+  negative_prompt: '模糊，抖动',
+  cfg_scale: 0.5,
+  mode: 'pro',      // 'std' 或 'pro'
+  duration: '10',   // '5' 或 '10' 秒
+  aspect_ratio: '16:9'
+});
+
+console.log(videoResult[0].url);
+console.log('时长:', videoResult[0].duration);
+
+// 图像到视频
+const i2vResult = await klingV26({
+  image_url: 'https://example.com/static-image.jpg',
+  prompt: '添加轻微的镜头平移',
+  mode: 'pro',
+  duration: '5',
+  aspect_ratio: '16:9'
+});
+
+// 虚拟人生成
+const avatarResult = await klingAvatar({
+  driver_video: 'https://example.com/talking.mp4',
+  image_url: 'https://example.com/portrait.jpg'
+});
+
+// 唇形同步
+const lipsyncResult = await klingLipsync({
+  audio_url: 'https://example.com/speech.mp3',
+  image_url: 'https://example.com/face.jpg'
+});
+```
+
+##### Vidu 系列
+
+```typescript
+import { viduQ2, viduQ1, vidu15 } from 'seacloud-sdk';
+
+const viduResult = await viduQ2({
+  prompt: '海滨城市日落的无人机镜头',
+  enhance_prompt: true,
+  duration: 8,        // 4 或 8 秒
+  aspect_ratio: '16:9'
+});
+```
+
+##### PixelVerse 系列
+
+```typescript
+import { pixverseV55, pixverseV45 } from 'seacloud-sdk';
+
+const pixResult = await pixverseV55({
+  prompt: '花朵绽放的延时摄影',
+  negative_prompt: '静止',
+  seed: 789,
+  aspect_ratio: '16:9'
+});
+```
+
+##### 微软 Sora
+
+```typescript
+import { microsoftSora2 } from 'seacloud-sdk';
+
+const soraResult = await microsoftSora2({
+  prompt: '未来主义的城市景观与飞行汽车',
+  duration: 10,
+  resolution: '1080p'  // '720p', '1080p', '4k'
+});
+```
+
+---
+
+#### 🎵 音频和 3D 生成
+
+```typescript
+// 文本转语音（ElevenLabs）
+import { elevenlabsTtsGenerator } from 'seacloud-sdk';
+
+const ttsResult = await elevenlabsTtsGenerator({
+  text: '你好，这是文本转语音的测试。',
+  voice_id: 'default',
+  model_id: 'eleven_multilingual_v2'
+});
+
+console.log('音频 URL:', ttsResult[0].url);
+
+// 3D 模型生成（腾讯）
+import { tencentHunyuan3d } from 'seacloud-sdk';
+
+const model3d = await tencentHunyuan3d({
+  image_url: 'https://example.com/object.jpg',
+  format: 'obj'  // 'obj', 'glb', 'fbx'
+});
+
+console.log('3D 模型 URL:', model3d[0].url);
+```
+
+---
+
+#### 📱 App 快应用生成
+
+从模板创建快应用。
+
+```typescript
+import { appGeneration, appSearch } from 'seacloud-sdk';
+
+// 搜索模板
+const templates = await appSearch({
+  template_id: 'comfyui-template-001',
+  type: 'comfyui'
+});
+
+// 生成应用
+const app = await appGeneration({
+  template_id: 'comfyui-template-001',
+  params: [
+    { name: 'prompt', value: '美丽的日落' },
+    { name: 'steps', value: '30' }
+  ]
+});
+
+console.log('应用 URL:', app.url);
+```
+
+---
+
+### 任务管理
+
+所有生成 API 都会返回任务，并自动轮询直到完成。
+
+```typescript
+import {
+  createAndWaitTask,
+  pollTaskUntilComplete,
+  getTaskStatus,
+  getClient
+} from 'seacloud-sdk';
+
+// 手动创建和轮询任务
+const client = getClient();
+
+const task = await client.createTask('/v1/image/generation', {
+  model: 'flux-pro',
+  input: [{ params: { prompt: '日落' } }]
+});
+
+console.log('任务 ID:', task.id);
+
+// 手动轮询
+const result = await pollTaskUntilComplete(client, task.id, {
+  intervalMs: 3000,
+  maxAttempts: 100,
+  onProgress: (attempt, status) => {
+    console.log(`尝试 ${attempt}: ${status}`);
+  }
+});
+
+// 直接检查任务状态
+const status = await getTaskStatus(task.id);
+console.log('状态:', status.status);
+console.log('输出:', status.output);
+```
+
+---
+
+### 错误处理
+
+```typescript
+import { SeacloudError } from 'seacloud-sdk';
+
+try {
+  const result = await llmChatCompletions({
+    model: 'invalid-model',
+    messages: [{ role: 'user', content: 'Hello' }]
+  });
+} catch (error) {
+  if (error instanceof SeacloudError) {
+    console.error('SeaCloud 错误:', error.message);
+    console.error('状态码:', error.statusCode);
+    console.error('详情:', error.details);
+  } else {
+    console.error('未知错误:', error);
+  }
+}
+```
+
+---
+
+## 🖥️ CLI 使用
+
+SDK 包含用于快速测试的命令行工具。
+
+```bash
+# LLM 聊天
+seacloud llm "你好，最近怎么样？" --model gpt-4o --stream
+
+# Agent 聊天（带图像生成）
+seacloud agent "生成一张可爱小狗的图片" --stream
+
+# 内容扫描
+seacloud scan "https://example.com/image.jpg" --risk-types EROTIC,VIOLENT
+
+# 检查任务状态
+seacloud status task-123abc
+
+# App 生成
+seacloud app search "template-id" --type comfyui
+seacloud app generation --template-id "xxx" --params '[{"name":"prompt","value":"test"}]'
+
+# 图像生成
+seacloud flux_2_pro --params '{"prompt":"美丽的日落","width":1024,"height":1024}'
+
+# 视频生成
+seacloud kling_v2_6 --params '{"prompt":"一只猫在玩耍","mode":"pro","duration":"5"}'
+```
+
+---
+
+## 🌍 支持的模型
+
+### LLM 模型（40+）
+
+| 提供商 | 模型 |
+|----------|--------|
+| **Anthropic Claude** | seaart-mix-sonnet-4-5, seacloud-claude-opus-4.5, seacloud-claude-haiku-4.5, shaseng-claude-4.5 |
+| **OpenAI** | gpt-4o, gpt-4o-mini, gpt-4.1, gpt-5, o1, o1-mini, o3-mini |
+| **DeepSeek** | deepseek-v3.1, deepseek-r1, deepseek-chat, deepseek-coder |
+| **Google** | gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-thinking, gemini-1.5-pro |
+| **Kimi** | kimi-k2, kimi-k2-thinking, kimi-k1.5, kimi-k1 |
+| **Grok** | grok-4, grok-code-fast-1, grok-2, grok-2-vision |
+| **阿里巴巴** | qwen-plus, qwen-turbo, qwen3-coder-plus, qwen-max |
+| **智谱 AI** | glm-4.5-air, glm-4.6, glm-4-plus, glm-zero |
+| **更多...** | Doubao、Hunyuan、Yi、Mistral、Llama 等 |
+
+### 图像生成模型（50+）
+
+| 提供商 | 系列 | 数量 |
+|----------|--------|-------|
+| 阿里巴巴 | WANx 2.1/2.5/2.6 | 23 个模型 |
+| Black Forest Labs | FLUX Pro/Flex/Edit | 8 个模型 |
+| Volces | Seedream/Seededit | 21 个模型 |
+| Google | Gemini/Imagen 4 | 11 个模型 |
+| 其他 | 各种提供商 | 20+ 个模型 |
+
+### 视频生成模型（40+）
+
+| 提供商 | 系列 | 数量 |
+|----------|--------|-------|
+| Kling（字节跳动） | V2.6/V2.5/V2.1/Omni | 27 个模型 |
+| PixelVerse | V3.5/V4.5/V5.5 | 16 个模型 |
+| Vidu | Q1/Q2/1.5 | 8 个模型 |
+| MiniMax | HaiLuo T2V/I2V | 12 个模型 |
+| 其他 | Sora、Runway 等 | 10+ 个模型 |
+
+---
+
+## 🔧 高级用法
+
+### 自定义轮询选项
+
+```typescript
+import { initSeacloud, setDefaultPollingOptions } from 'seacloud-sdk';
+
+// 设置全局默认值
+setDefaultPollingOptions({
+  intervalMs: 5000,     // 每 5 秒轮询一次
+  maxAttempts: 200      // 最多 200 次尝试（16+ 分钟）
+});
+
+// 或者按请求设置
+import { createAndWaitTask, getClient } from 'seacloud-sdk';
+
+const client = getClient();
+const result = await createAndWaitTask(
+  client,
+  '/v1/image/generation',
+  { model: 'flux-pro', input: [{ params: { prompt: 'test' } }] },
+  {
+    intervalMs: 2000,
+    maxAttempts: 50,
+    onProgress: (attempt, status) => {
+      console.log(`轮询尝试 ${attempt}，状态: ${status}`);
+    }
+  }
+);
+```
+
+### 浏览器使用
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module">
+    import { initSeacloud, llmChatCompletions } from 'https://esm.sh/seacloud-sdk';
+
+    // 从 localStorage 获取 Token
+    localStorage.setItem('auth_token', 'your-api-key');
+    initSeacloud();
+
+    const response = await llmChatCompletions({
+      model: 'gpt-4o',
+      messages: [{ role: 'user', content: '来自浏览器的你好！' }]
+    });
+
+    console.log(response.choices[0].message.content);
+  </script>
+</head>
+<body>
+  <h1>SeaCloud SDK 浏览器示例</h1>
+</body>
+</html>
+```
+
+### Iframe 集成
+
+```typescript
+// 在父页面中
+window.addEventListener('message', (event) => {
+  if (event.data.type === 'seaverse:get_token') {
+    event.source.postMessage({
+      type: 'seaverse:token',
+      token: 'your-api-key'
+    }, '*');
+  }
+});
+
+// 在 iframe 中
+import { initSeacloud, llmChatCompletions } from 'seacloud-sdk';
+
+initSeacloud(); // 将自动从父页面请求 token
+
+const response = await llmChatCompletions({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: '来自 iframe 的你好！' }]
+});
+```
+
+---
+
+## 📖 类型定义
+
+SDK 完全类型化。以下是关键接口：
+
+```typescript
+// 配置
+interface SeacloudConfig {
+  apiKey?: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+  timeout?: number;
+}
+
+// 任务
+interface TaskResult {
+  id: string;
+  created_at: number;
+  status: 'pending' | 'processing' | 'completed' | 'failed';
+  error?: { code: string; message: string } | null;
+  model: string;
+  output?: Array<{
+    content?: Array<{
+      type?: string;
+      url?: string;
+      size?: { width: number; height: number };
+      duration?: number;
+    }>;
+  }>;
+}
+
+// LLM 消息
+interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+interface ChatCompletionResponse {
+  id: string;
+  choices: Array<{
+    index: number;
+    message: { role: string; content: string };
+    finish_reason: string;
+  }>;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+// Agent 消息
+interface AgentMessage {
+  role: 'developer' | 'user' | 'assistant' | 'tool';
+  content: Array<
+    | { type: 'text'; text: string }
+    | { type: 'image_url'; image_url: { url: string } }
+    | { type: 'video_url'; video_url: { url: string } }
+  >;
+}
+
+// 扫描
+interface ScanParams {
+  uri?: string;
+  img_base64?: string;
+  risk_types: ('POLITY' | 'EROTIC' | 'VIOLENT' | 'CHILD')[];
+  detected_age: 0 | 1;
+  is_video: 0 | 1;
+}
+
+interface ScanResponse {
+  nsfw_level: number;  // 0-6
+  label_items: string[];
+  risk_types: string[];
+  frame_results?: Array<{
+    frame_no: number;
+    nsfw_level: number;
+    label_items: string[];
+  }>;
+}
+```
+
+---
+
+## 🤝 贡献
+
+欢迎贡献！请随时提交 Pull Request。
+
+1. Fork 仓库
+2. 创建您的特性分支 (`git checkout -b feature/amazing-feature`)
+3. 提交您的更改 (`git commit -m '添加某个很棒的功能'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 打开 Pull Request
+
+---
+
+## 📄 许可证
+
+本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
+
+---
+
+## 🔗 链接
+
+- **GitHub**: [https://github.com/SeaVerseAI/seacloud-sdk](https://github.com/SeaVerseAI/seacloud-sdk)
+- **npm**: [https://www.npmjs.com/package/seacloud-sdk](https://www.npmjs.com/package/seacloud-sdk)
+- **Issues**: [https://github.com/SeaVerseAI/seacloud-sdk/issues](https://github.com/SeaVerseAI/seacloud-sdk/issues)
+- **文档**: [即将推出]
+
+---
+
+## 📞 支持
+
+如果您有任何问题或需要帮助：
+
+- 在 [GitHub Issues](https://github.com/SeaVerseAI/seacloud-sdk/issues) 上提出问题
+- 查看 [examples](./examples_agent.ts) 文件夹
+- 阅读 [API 文档](./seacloud-api.json)
+
+---
+
+<div align="center">
+
+**由 SeaVerse AI 用 ❤️ 构建**
+
+[⬆ 回到顶部](#seacloud-sdk)
+
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seacloud-sdk",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "SeaCloud SDK for JavaScript/TypeScript - AI models, LLM, content safety scanning",
   "type": "module",
   "main": "./dist/index.js",