ai-world-sdk

TypeScript SDK for AI World Platform - 一个功能完整的 AI 应用开发 SDK

特性

• 🤖 聊天模型: 兼容 LangChain.js 接口（OpenAI、Gemini、Claude、Doubao）
• 🎨 图像生成: 支持豆包 Seedream 和 Google Gemini
• 🎬 视频生成: 支持豆包 Seedance 和 OpenAI Sora
• 📥 下载代理: 支持流式下载和普通下载任意 URL 的二进制文件
• 🔐 用户认证: 支持获取当前登录用户信息
• ⚙️ 全局配置: 自动从浏览器环境获取配置，简化初始化
• 🐛 调试模式: 支持详细的请求/响应日志

安装

npm install ai-world-sdk
# 或 yarn add ai-world-sdk
# 或 pnpm add ai-world-sdk

快速开始

1. 配置（推荐）

import { sdkConfig } from 'ai-world-sdk';

// 设置全局配置（只需一次）
sdkConfig.setBaseUrl('your-base-url');
sdkConfig.setToken('your-jwt-token');
sdkConfig.setDebug(true); // 可选：启用调试模式

// 浏览器环境会自动从 window.location.origin 和 cookie 获取配置

2. 聊天模型

import { ChatGoogleGenerativeAI, ChatOpenAI, ChatAnthropic, HumanMessage, SystemMessage } from 'ai-world-sdk';

// Gemini 模型（使用 gemini provider）
const geminiModel = new ChatGoogleGenerativeAI({
  modelName: 'gemini-2.5-flash-image',
  temperature: 0.7,
  provider: 'gemini', // 或 'aihubmix', 'api2img'
  vertexai: false, // 可选：是否使用 VertexAI（仅当 provider 为 gemini 时有效）
  jsonSchema: undefined, // 可选：结构化输出 JSON Schema
});

// GPT 模型（使用 aihubmix provider）
const gptModel = new ChatOpenAI({
  modelName: 'gpt-4o-mini',
  temperature: 0.7,
  provider: 'aihubmix', // 或 'api2img'
  jsonSchema: undefined, // 可选：结构化输出 JSON Schema
});

// Claude 模型（使用 aihubmix provider）
const claudeModel = new ChatAnthropic({
  modelName: 'claude-3-sonnet-20240229',
  temperature: 0.7,
  provider: 'aihubmix', // 或 'api2img'
});

// 非流式调用
const response = await geminiModel.invoke([
  new SystemMessage('You are a helpful assistant.'),
  new HumanMessage('Hello! What is AI?'),
]);
console.log(response.content);

// 流式调用
for await (const chunk of geminiModel.stream([
  new HumanMessage('Tell me a story'),
])) {
  if (typeof chunk.content === 'string') {
    process.stdout.write(chunk.content);
  }
}

3. 图像生成

import { DoubaoImageGenerationClient, GeminiImageGenerationClient } from 'ai-world-sdk';

// 豆包图像生成
const doubaoClient = new DoubaoImageGenerationClient({});
const result = await doubaoClient.generate({
  prompt: 'A beautiful sunset over the ocean',
  size: '2K', // 或使用 '2K', '4K' 等
  quality: 'hd',
  n: 1,
});
console.log('图像 URL:', result.data[0]?.url);

// Gemini 图像生成
const geminiClient = new GeminiImageGenerationClient({});
const geminiResult = await geminiClient.generate({
  prompt: 'A futuristic city',
  model: 'gemini-3-pro-image-preview', // 使用 Gemini 3 Pro 模型
  aspect_ratio: '16:9',
  image_size: '2K', // 仅适用于 gemini-3-pro-image-preview
  response_modalities: ['IMAGE'], // 仅返回图片，不返回文本
});
console.log('图像 URL:', geminiResult.data[0]?.url);

4. 视频生成

豆包视频生成（Seedance）

import { VideoGenerationClient } from 'ai-world-sdk';

const videoClient = new VideoGenerationClient({});

// 创建任务
const task = await videoClient.create({
  prompt: 'A beautiful sunset over the ocean',
  duration: 5,
  aspect_ratio: '16:9',
});

// 轮询直到完成
const result = await videoClient.poll(task.id, {
  interval: 3000,
  timeout: 300000,
});

if (result.status === 'succeeded') {
  console.log('视频 URL:', result.content?.video_url);
}

OpenAI 视频生成（Sora）

import { OpenAIVideoGenerationClient } from 'ai-world-sdk';

const openaiVideoClient = new OpenAIVideoGenerationClient({});

// 方式1: 文本生成视频
const task = await openaiVideoClient.generate({
  prompt: 'A beautiful sunset over the ocean with waves crashing on the shore',
  model: 'sora-2',           // 或 'sora-2-pro'
  provider: 'aihubmix',      // 或 'api2img'
  seconds: '4',              // 4, 8, 或 12 秒
  size: '1280x720'           // '720x1280', '1280x720', '1024x1792', '1792x1024'
});

console.log('任务 ID:', task.id);
console.log('任务状态:', task.status);

// 方式2: 图像生成视频（图生视频）
const taskWithImage = await openaiVideoClient.generate({
  prompt: 'Animate this scene with gentle movements',
  input_reference: 'data:image/png;base64,iVBORw0KGgo...', // Base64 图像或 URL
  model: 'sora-2',
  provider: 'aihubmix',
  seconds: '4'
});

// 查询任务状态
const status = await openaiVideoClient.getTask(task.id, 'aihubmix');
console.log('当前状态:', status.status);

// 轮询等待完成
const result = await openaiVideoClient.waitForCompletion(task.id, 'aihubmix', {
  maxAttempts: 60,
  interval: 5000,
  onProgress: (status) => {
    console.log('当前状态:', status.status);
  }
});

if (result.status === 'completed') {
  console.log('视频生成成功！');
  
  // 流式下载视频
  const videoBlob = await openaiVideoClient.downloadVideo(
    result.id,
    'aihubmix',  // provider
    'video'      // 'video' 或 'thumbnail'
  );
  
  console.log('视频大小:', (videoBlob.size / 1024 / 1024).toFixed(2), 'MB');
  
  // 在浏览器中下载
  const url = URL.createObjectURL(videoBlob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'sora_video.mp4';
  a.click();
  URL.revokeObjectURL(url);
}

// 一键生成并等待（简化版）
const completeResult = await openaiVideoClient.generateAndWait({
  prompt: 'A futuristic city skyline',
  model: 'sora-2',
  provider: 'aihubmix',
  seconds: '4'
}, {
  maxAttempts: 60,
  interval: 5000,
  onProgress: (status) => console.log('状态:', status.status)
});

if (completeResult.status === 'completed') {
  const videoBlob = await openaiVideoClient.downloadVideo(
    completeResult.id,
    'aihubmix',
    'video'
  );
  console.log('一键生成完成，视频大小:', videoBlob.size);
}

5. 用户认证

import { getCurrentUserInfo, AuthClient } from 'ai-world-sdk';

// 方式1: 使用便捷函数（推荐）
const userInfo = await getCurrentUserInfo();
console.log('用户信息:', userInfo);
console.log('用户ID:', userInfo.id);
console.log('用户名:', userInfo.full_name);
console.log('邮箱:', userInfo.email);

// 方式2: 使用 AuthClient 类
const authClient = new AuthClient({
  baseUrl: 'http://localhost:8000', // 可选，默认使用全局配置
  token: 'your-token',                // 可选，默认使用全局配置
});

const userInfo2 = await authClient.getCurrentUserInfo();
console.log('用户信息:', userInfo2);

6. 下载代理

import { DownloadClient } from 'ai-world-sdk';

const downloadClient = new DownloadClient({});

// 普通下载（返回 Blob）
const blob = await downloadClient.download({
  url: 'https://example.com/file.zip',
  filename: 'myfile.zip', // 可选
});
console.log('文件大小:', blob.size, '字节');

// 下载并保存到本地
await downloadClient.downloadAsFile({
  url: 'https://example.com/file.zip',
  filename: 'myfile.zip',
});

// 流式下载（使用 for await 迭代）
let totalSize = 0;
for await (const chunk of downloadClient.streamDownload({
  url: 'https://example.com/large-file.zip',
  filename: 'large-file.zip',
})) {
  totalSize += chunk.length;
  console.log(`已下载: ${totalSize} 字节`);
}
console.log('下载完成，总大小:', totalSize, '字节');

API 参考

聊天模型

支持的模型类

| 模型类 | 说明 | 示例模型 | |--------|------|----------| | ChatOpenAI | OpenAI 兼容（GPT、O1、Doubao） | gpt-4o-mini, doubao-pro-4k | | ChatGoogleGenerativeAI | Google Gemini | gemini-2.5-flash-image | | ChatAnthropic | Anthropic Claude | claude-3-sonnet-20240229 |

核心方法

// 非流式调用
const response = await model.invoke([new HumanMessage('Hello')]);

// 流式调用
for await (const chunk of model.stream([new HumanMessage('Hello')])) {
  console.log(chunk.content);
}

// 批量处理
const responses = await model.batch([
  [new HumanMessage('Question 1')],
  [new HumanMessage('Question 2')],
]);

// 绑定参数
const boundModel = model.bind({ temperature: 0.9, maxTokens: 1000 });

// 绑定工具
const modelWithTools = model.bindTools([...tools]);

工厂函数

import { createChatModel } from 'ai-world-sdk';

// 根据模型名称自动选择正确的类
const model = createChatModel('gemini-2.5-flash-image', {
  temperature: 0.7,
  provider: 'gemini', // 或 'aihubmix', 'api2img', 'doubao'
});

支持的模型前缀:

• gpt-*, o1-* → ChatOpenAI
• doubao-* → ChatOpenAI
• gemini-* → ChatGoogleGenerativeAI
• claude-* → ChatAnthropic

Provider 参数说明:

• provider: 'aihubmix' - 使用 aihubmix 聚合服务（推荐，支持所有模型）
• provider: 'api2img' - 使用 api2img 聚合服务（推荐，支持所有模型）
• provider: 'gemini' - 直接使用 Google Gemini API
• provider: 'doubao' - 使用豆包服务

结构化输出参数:

• jsonSchema?: Record<string, any> - JSON Schema 定义，用于结构化输出（使用 with_structured_output）

图像生成

DoubaoImageGenerationClient

const client = new DoubaoImageGenerationClient({});

const result = await client.generate({
  prompt: 'A beautiful landscape',      // 必需
  model: 'doubao-seedream-4-5-251128', // 可选，默认值
  size: '2K',                   // 可选: 像素值(2048x2048, 2560x1440等)或K值(1K, 2K, 4K)
  quality: 'hd',                       // 可选: standard, hd
  n: 1,                                // 可选: 1-10
  response_format: 'url',              // 可选: url, b64_json
  style: 'vivid',                      // 可选: vivid, natural
  watermark: false,                     // 可选
});

GeminiImageGenerationClient

const client = new GeminiImageGenerationClient({});

// 基础用法（使用 Gemini 2.5 Flash - 快速模型）
const result = await client.generate({
  prompt: 'A beautiful landscape',              // 必需
  model: 'gemini-2.5-flash-image',              // 推荐：快速、高效
  aspect_ratio: '16:9',                         // 可选: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
});

// 高级用法（使用 Gemini 3 Pro - 专业模型，支持高分辨率）
const result2 = await client.generate({
  prompt: 'A futuristic city at sunset',
  model: 'gemini-3-pro-image-preview',         // 专业级模型
  aspect_ratio: '16:9',
  image_size: '2K',                             // 可选: 1K, 2K, 4K（仅适用于 gemini-3-pro-image-preview）
  response_modalities: ['IMAGE'],              // 仅返回图片，不返回文本
  temperature: 0.7,                             // 可选: 0.0-2.0
  max_output_tokens: 1000,                      // 可选
});

// 使用 aihubmix provider（通过 aihubmix 代理服务）
const aihubmixClient = new GeminiImageGenerationClient({
  provider: 'aihubmix',  // 使用 aihubmix 代理
});

const result3 = await aihubmixClient.generate({
  prompt: 'A beautiful landscape with mountains',
  model: 'gemini-3-pro-image-preview',
  aspect_ratio: '16:9',
  image_size: '1K',
  response_modalities: ['IMAGE'],
});

// 单图输入（文本 + 单张图片，实现编辑效果）
const editResult = await client.generate({
  prompt: 'Add a small wizard hat on the cat\'s head',
  image: 'data:image/png;base64,iVBORw0KGgo...', // base64 编码的图片数据或 data URL
  model: 'gemini-2.5-flash-image',
  aspect_ratio: '1:1',
  response_modalities: ['IMAGE'],
});

// 多轮图片修改（迭代式优化图片）
// 第一轮：创建初始图片
const firstResponse = await client.chat({
  message: 'Create a vibrant infographic about photosynthesis',
  model: 'gemini-3-pro-image-preview',
  aspect_ratio: '16:9',
  response_modalities: ['TEXT', 'IMAGE'],
});

// 后续轮次：修改图片（使用返回的 chat_id）
const secondResponse = await client.chat({
  chat_id: firstResponse.chat_id,
  message: 'Update this infographic to be in Spanish',
  model: 'gemini-3-pro-image-preview',
  aspect_ratio: '16:9',
  image_size: '2K',
  response_modalities: ['TEXT', 'IMAGE'],
});

参数说明：

| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | prompt | string | 图像生成提示词（必需） | - | | model | string | 模型名称 | gemini-2.0-flash-exp-image-generation | | image | string \| string[] | 输入图片（base64 或 data URL）。可以是单个图片或图片数组（多图输入） | - | | aspect_ratio | string | 宽高比 | - | | image_size | string | 图片大小（仅 gemini-3-pro-image-preview） | - | | response_modalities | array | 响应模态 | ['TEXT', 'IMAGE'] | | temperature | number | 温度参数 | 0.7 | | max_output_tokens | number | 最大输出 token 数 | 1000 |

多图输入限制：

• gemini-2.5-flash-image: 最多支持 3 张输入图片
• gemini-3-pro-image-preview: 最多支持 14 张输入图片（其中最多 5 张高保真图片）

支持的宽高比： 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9

Provider 说明：

• provider: 'gemini'（默认）- 直接使用 Google Gemini 官方 API
• provider: 'aihubmix' - 通过 aihubmix 代理服务调用，适合需要统一管理多个 API 的场景
• provider: 'api2img' - 通过 api2img 代理服务调用，适合需要统一管理多个 API 的场景

模型对比：

| 模型 | 分辨率 | 特点 | 适用场景 | |------|--------|------|----------| | gemini-2.5-flash-image | 1024px | 快速、高效、成本低 | 日常使用、批量生成 | | gemini-3-pro-image-preview | 1K/2K/4K | 专业级、高分辨率、高级功能 | 专业设计、高分辨率需求 |

多轮图片修改：

• chat() - 多轮图片修改：通过对话迭代式优化图片
  • 首次调用创建新的聊天会话，返回 chat_id
  • 后续调用使用 chat_id 继续对话
  • 推荐使用 gemini-3-pro-image-preview 模型进行多轮编辑

视频生成

VideoGenerationClient（豆包 Seedance）

const client = new VideoGenerationClient({});

// 创建任务
const task = await client.create({
  prompt: 'A beautiful sunset',        // 或 image_url
  model: 'doubao-seedance-1-0-pro-fast-251015', // 可选
  duration: 5,                         // 可选: 1-10 秒
  aspect_ratio: '16:9',                // 可选: 16:9, 9:16, 1:1
  resolution: '720p',                   // 可选
  return_last_frame: true,             // 可选
});

// 查询状态
const status = await client.get(task.id);

// 轮询直到完成
const result = await client.poll(task.id, {
  interval: 3000,   // 轮询间隔（毫秒）
  timeout: 300000,  // 超时时间（毫秒）
});

OpenAIVideoGenerationClient（OpenAI Sora）

const client = new OpenAIVideoGenerationClient({});

// 文本生成视频
const task = await client.generate({
  prompt: 'A beautiful sunset',
  model: 'sora-2',                      // 可选: sora-2, sora-2-pro
  provider: 'openai',                   // 可选: openai, aihubmix, api2img
  seconds: '4',                           // 可选: 4, 8, 12
  size: '1280x720',                     // 可选: 720x1280, 1280x720, 1024x1792, 1792x1024
});

// 图像生成视频
const taskFromImage = await client.generate({
  prompt: 'Animate this scene',
  input_reference: 'data:image/png;base64,iVBORw0KGgo...',  // Base64 或 URL
  model: 'sora-2',
  seconds: '8',
});

// 查询状态
const status = await client.getTask(task.id);

// 轮询直到完成
const result = await client.waitForCompletion(task.id, {
  maxAttempts: 60,
  interval: 5000,
  onProgress: (status) => {
    console.log('状态:', status.status);
  }
});

// 下载视频
const videoBlob = await client.downloadVideo(task.id, {
  variant: 'video'  // 或 'thumbnail'
});

// 一键生成并等待
const finalResult = await client.generateAndWait({
  prompt: 'A futuristic city',
  model: 'sora-2',
  seconds: '4'
});

下载代理

DownloadClient

const client = new DownloadClient({
  baseUrl: 'https://your-api.com', // 可选，默认使用全局配置
  token: 'your-token',              // 可选，默认使用全局配置
  headers: {                        // 可选，自定义请求头
    'X-Custom-Header': 'value',
  },
});

方法

download(options: DownloadOptions): Promise<Blob>

普通下载文件，返回 Blob 对象。

const blob = await client.download({
  url: 'https://example.com/file.zip',
  filename: 'myfile.zip', // 可选，下载时的文件名
});

// 使用 Blob
const text = await blob.text();        // 读取为文本
const arrayBuffer = await blob.arrayBuffer(); // 读取为 ArrayBuffer
const url = URL.createObjectURL(blob); // 创建对象 URL

参数:

• url (string, 必需): 要下载的文件 URL（必须是 http:// 或 https://）
• filename (string, 可选): 下载时的文件名，不提供则从 URL 或响应头中提取

返回: Promise<Blob> - 文件的 Blob 对象

错误处理:

try {
  const blob = await client.download({
    url: 'https://example.com/file.zip',
  });
  console.log('下载成功:', blob.size, '字节');
} catch (error) {
  if (error instanceof Error) {
    console.error('下载失败:', error.message);
    // 常见错误：
    // - "URL is required" - URL 参数缺失
    // - "Download failed: HTTP 404" - 文件不存在
    // - "Download failed: HTTP 403" - 访问被拒绝
    // - "下载超时，请稍后重试" - 下载超时
  }
}

downloadAsFile(options: DownloadOptions, downloadFilename?: string): Promise<void>

下载文件并触发浏览器保存对话框。

await client.downloadAsFile({
  url: 'https://example.com/file.zip',
  filename: 'myfile.zip',
}, 'custom-filename.zip'); // 可选，覆盖 filename

参数:

• options: 同 download() 方法
• downloadFilename (string, 可选): 下载时的文件名，会覆盖 options.filename

返回: Promise<void>

streamDownload(options: StreamDownloadOptions): AsyncGenerator<Uint8Array>

流式下载文件，返回异步迭代器，支持 for await 迭代。

let totalSize = 0;
for await (const chunk of client.streamDownload({
  url: 'https://example.com/large-file.zip',
  filename: 'large-file.zip',
})) {
  totalSize += chunk.length;
  console.log(`已下载: ${totalSize} 字节`);
  // 可以在这里处理每个数据块（例如：实时处理、显示进度等）
}
console.log('下载完成，总大小:', totalSize, '字节');

参数:

• url (string, 必需): 要下载的文件 URL
• filename (string, 可选): 下载时的文件名

返回: AsyncGenerator<Uint8Array> - 异步迭代器，每次迭代返回一个 Uint8Array 数据块

使用场景:

• 下载大文件时显示实时进度（通过累计 chunk.length）
• 需要处理数据流（例如：实时解析、转码等）
• 需要监控下载状态
• 需要流式处理文件内容

示例：带进度显示

// 如果服务器提供了 Content-Length，可以从响应头获取总大小
let totalSize = 0;
const total = 1024 * 1024 * 10; // 假设已知总大小（实际应从响应头获取）

for await (const chunk of client.streamDownload({
  url: 'https://example.com/large-file.zip',
})) {
  totalSize += chunk.length;
  const percent = total ? Math.round((totalSize / total) * 100) : null;
  console.log(`下载进度: ${totalSize}/${total || '未知'} (${percent || '?'}%)`);
}

示例：流式处理并保存

// 流式下载并实时保存到文件系统（Node.js 环境）
import { createWriteStream } from 'fs';
import { pipeline } from 'stream/promises';

const chunks: Uint8Array[] = [];
let totalSize = 0;

for await (const chunk of client.streamDownload({
  url: 'https://example.com/large-file.zip',
  filename: 'large-file.zip',
})) {
  chunks.push(chunk);
  totalSize += chunk.length;
  console.log(`已接收: ${totalSize} 字节`);
}

// 合并所有块并保存
const blob = new Blob(chunks);
const buffer = Buffer.from(await blob.arrayBuffer());
await fs.promises.writeFile('large-file.zip', buffer);
console.log('文件保存完成');

注意事项:

• 流式下载适合大文件，可以实时显示进度
• 普通下载适合小文件，会一次性加载到内存
• URL 必须是 http:// 或 https:// 协议
• 文件名会自动从 URL 或响应头中提取（如果未提供）
• 流式下载时，数据块大小由服务器决定，通常为 8KB-64KB

全局配置

import { sdkConfig } from 'ai-world-sdk';

// 设置配置
sdkConfig.setBaseUrl('your-base-url');
sdkConfig.setToken('your-jwt-token');
sdkConfig.setHeaders({ 'X-Custom-Header': 'value' });
sdkConfig.setDebug(true);

// 获取配置
const baseUrl = sdkConfig.getServerUrl();
const token = sdkConfig.getToken();
const headers = sdkConfig.getHeaders();
const debug = sdkConfig.getDebug();

// 重置配置
sdkConfig.reset();

浏览器环境自动配置:

• baseUrl: 从 window.location.origin 自动获取
• token: 从 document.cookie 中的 auth_token 自动获取

消息类型

import { HumanMessage, SystemMessage, AIMessage } from 'ai-world-sdk';

// 文本消息
const userMsg = new HumanMessage('Hello');
const systemMsg = new SystemMessage('You are a helpful assistant.');

// 多模态消息（文本 + 图像）
const multimodalMsg = new HumanMessage([
  { type: 'text', text: 'Describe this image' },
  { type: 'image_url', image_url: 'data:image/jpeg;base64,...' },
]);

Provider 调用示例

SDK 支持多个 provider，每个 provider 对应不同的服务提供商。以下是各 provider 的使用示例：

aihubmix Provider

aihubmix 是一个多模型聚合服务，支持多种模型（OpenAI、Gemini、Claude 等）。

import { ChatOpenAI, ChatGoogleGenerativeAI, ChatAnthropic, HumanMessage } from 'ai-world-sdk';

// OpenAI 模型（通过 aihubmix）
const gptModel = new ChatOpenAI({
  modelName: 'gpt-4o-mini',
  temperature: 0.7,
  provider: 'aihubmix',
});

// Gemini 模型（通过 aihubmix）
const geminiModel = new ChatGoogleGenerativeAI({
  modelName: 'gemini-2.5-flash',
  temperature: 0.7,
  provider: 'aihubmix',
});

// Gemini 图像生成（通过 aihubmix）
import { GeminiImageGenerationClient } from 'ai-world-sdk';

const geminiImageClient = new GeminiImageGenerationClient({
  provider: 'aihubmix',
});

const imageResult = await geminiImageClient.generate({
  prompt: 'A beautiful landscape',
  model: 'gemini-3-pro-image-preview',
  aspect_ratio: '16:9',
  image_size: '1K',
  response_modalities: ['IMAGE'],
});

// Claude 模型（通过 aihubmix）
const claudeModel = new ChatAnthropic({
  modelName: 'claude-3-sonnet-20240229',
  temperature: 0.7,
  provider: 'aihubmix',
});

// 使用示例
const response = await gptModel.invoke([
  new HumanMessage('Hello!'),
]);

gemini Provider

直接使用 Google Gemini 官方 API。

import { ChatGoogleGenerativeAI, HumanMessage } from 'ai-world-sdk';

const model = new ChatGoogleGenerativeAI({
  modelName: 'gemini-2.5-flash-image',
  temperature: 0.7,
  provider: 'gemini',
});

const response = await model.invoke([
  new HumanMessage('What is AI?'),
]);

doubao Provider

使用豆包（字节跳动）的模型服务。

import { ChatOpenAI, HumanMessage } from 'ai-world-sdk';

// Doubao 模型使用 ChatOpenAI（因为与 OpenAI 兼容）
const doubaoModel = new ChatOpenAI({
  modelName: 'doubao-pro-4k',
  temperature: 0.7,
  provider: 'doubao',
});

const response = await doubaoModel.invoke([
  new HumanMessage('你好！'),
]);

Provider 选择指南

| Provider | 适用场景 | 支持的模型 | |----------|----------|------------| | aihubmix | 多模型聚合，统一接口 | GPT、Gemini、Claude、Doubao 等 | | gemini | 直接使用 Google Gemini API | 所有 Gemini 模型 | | api2img | 使用 api2img 聚合服务 | 所有模型 | | doubao | 使用豆包服务 | Doubao 系列模型 |

推荐使用 aihubmix provider，因为它提供了统一的接口和更好的模型选择灵活性。

完整示例

聊天对话

import { ChatGoogleGenerativeAI, HumanMessage, SystemMessage } from 'ai-world-sdk';

const model = new ChatGoogleGenerativeAI({
  modelName: 'gemini-2.5-flash-image',
  temperature: 0.7,
  provider: 'gemini',
});

// 简单对话
const response = await model.invoke([
  new HumanMessage('What is AI?'),
]);
console.log(response.content);

// 带系统提示的对话
const response2 = await model.invoke([
  new SystemMessage('You are a helpful assistant.'),
  new HumanMessage('Explain machine learning.'),
]);

结构化输出（JSON Schema）

使用 jsonSchema 参数可以让模型返回结构化的 JSON 数据，而不是自由文本。

import { ChatOpenAI, ChatGoogleGenerativeAI, HumanMessage, createChatModel } from 'ai-world-sdk';

// 使用 ChatOpenAI 进行结构化输出
const openaiModel = new ChatOpenAI({
  modelName: 'gpt-4o-mini',
  temperature: 0.7,
  provider: 'aihubmix',
  jsonSchema: {
    type: 'object',
    properties: {
      name: { type: 'string', description: '用户姓名' },
      age: { type: 'integer', description: '用户年龄' },
      email: { type: 'string', description: '用户邮箱' },
    },
    required: ['name', 'age'],
  },
});

const response = await openaiModel.invoke([
  new HumanMessage('请提取以下信息：张三，25岁，邮箱是[email protected]'),
]);

// 响应内容将是结构化的 JSON 对象
console.log(response.content); // { name: '张三', age: 25, email: '[email protected]' }

使用 Gemini 模型的结构化输出：

const geminiModel = new ChatGoogleGenerativeAI({
  modelName: 'gemini-2.5-flash',
  temperature: 0.7,
  provider: 'gemini',
  jsonSchema: {
    type: 'object',
    properties: {
      summary: { type: 'string', description: '摘要' },
      keywords: {
        type: 'array',
        items: { type: 'string' },
        description: '关键词列表',
      },
      sentiment: {
        type: 'string',
        enum: ['positive', 'neutral', 'negative'],
        description: '情感倾向',
      },
    },
    required: ['summary', 'keywords'],
  },
});

const response = await geminiModel.invoke([
  new HumanMessage("分析这句话的情感：'今天天气真好，心情很愉快！'"),
]);

使用 createChatModel 工厂函数：

const model = createChatModel('gpt-4o-mini', {
  temperature: 0.7,
  provider: 'aihubmix',
  jsonSchema: {
    type: 'object',
    properties: {
      title: { type: 'string', description: '文章标题' },
      content: { type: 'string', description: '文章内容' },
      tags: {
        type: 'array',
        items: { type: 'string' },
        description: '标签列表',
      },
    },
    required: ['title', 'content'],
  },
});

const response = await model.invoke([
  new HumanMessage('生成一篇关于人工智能的短文，包含标题、内容和标签'),
]);

注意事项：

• jsonSchema 必须符合 JSON Schema 规范
• 对于 OpenAI 兼容的模型（如 GPT、Doubao），JSON Schema 会自动添加 title 和 description（如果缺失）
• 对于 Gemini 和 Anthropic 模型，直接使用提供的 JSON Schema
• 结构化输出的响应内容可能是 JSON 字符串或对象，需要根据实际情况解析
• 结构化输出使用 LangChain 的 with_structured_output 方法，底层通过 method="json_schema" 实现

流式响应

let fullText = '';
for await (const chunk of model.stream([
  new HumanMessage('Tell me a story about AI'),
])) {
  if (typeof chunk.content === 'string') {
    fullText += chunk.content;
    process.stdout.write(chunk.content);
  }
}
console.log('\n完整回复:', fullText);

工具调用

import { ToolDefinition } from 'ai-world-sdk';

const tools: ToolDefinition[] = [
  {
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get the current weather',
      parameters: {
        type: 'object',
        properties: {
          location: { type: 'string' },
        },
        required: ['location'],
      },
    },
  },
];

const modelWithTools = model.bindTools(tools);
const response = await modelWithTools.invoke([
  new HumanMessage('What is the weather in Paris?'),
]);

图像生成工作流

豆包图像生成

豆包 Seedream 支持多种图像生成模式：

支持的尺寸选项：

• 像素值（宽x高）：

  • 2048x2048 (1:1 正方形)
  • 2304x1728 (4:3 横屏)
  • 1728x2304 (3:4 竖屏)
  • 2560x1440 (16:9 横屏)
  • 1440x2560 (9:16 竖屏)
  • 2496x1664 (3:2 横屏)
  • 1664x2496 (2:3 竖屏)
  • 3024x1296 (21:9 超宽屏)

• K 值（根据模型版本）：

  • 1K - 仅 4.0 版本支持
  • 2K - 4.0 和 4.5 版本支持
  • 4K - 4.0 和 4.5 版本支持

1. 文生图（文本生成图像）

import { DoubaoImageGenerationClient } from 'ai-world-sdk';

const client = new DoubaoImageGenerationClient({});

// 生成单张图像
const result = await client.generate({
  prompt: 'A futuristic city skyline at sunset',
  size: '2048x2048', // 1:1 正方形，或使用 '2K', '4K' 等
  quality: 'hd',
});

console.log('图像 URL:', result.data[0]?.url);

2. 图文生图（单图输入单图输出）

基于一张参考图片生成新图像：

// 使用单张图片作为输入
const result = await client.generate({
  prompt: '将这张图片转换为水彩画风格',
  image: 'data:image/png;base64,iVBORw0KGgo...', // base64 编码的图片或 data URL
  size: '2560x1440', // 16:9 横屏
  quality: 'hd',
});

console.log('生成的图像 URL:', result.data[0]?.url);

3. 多图融合（多图输入单图输出）

融合多张参考图片生成新图像：

// 使用多张图片作为输入
const result = await client.generate({
  prompt: '将图1的服装换为图2的服装风格',
  image: [
    'data:image/png;base64,iVBORw0KGgo...', // 第一张图片
    'data:image/png;base64,iVBORw0KGgo...', // 第二张图片
  ],
  size: '2048x2048', // 1:1 正方形
  quality: 'hd',
});

console.log('融合后的图像 URL:', result.data[0]?.url);

4. 组图输出（多图输出）

一次生成多张不同风格的图像：

// 生成多张图像（组图输出）
const multiResult = await client.generate({
  prompt: 'A beautiful landscape',
  n: 3, // 生成 3 张图像
  size: '2560x1440', // 16:9 横屏
});

multiResult.data.forEach((image, index) => {
  console.log(`图像 ${index + 1}:`, image.url);
});

组合使用示例

// 图文生图 + 组图输出：基于一张图片生成多张不同风格的图像
const result = await client.generate({
  prompt: '生成不同风格的艺术作品',
  image: 'data:image/png;base64,iVBORw0KGgo...',
  n: 4, // 生成 4 张不同风格的图像
  size: '2048x2048', // 1:1 正方形
  quality: 'hd',
});

Gemini 图像生成

import { GeminiImageGenerationClient } from 'ai-world-sdk';

const client = new GeminiImageGenerationClient({});

// 1. 文生图（仅文本提示）
const result = await client.generate({
  prompt: 'A beautiful sunset over the ocean',
  model: 'gemini-2.5-flash-image',
  aspect_ratio: '16:9',
});

console.log('图像 URL:', result.data[0]?.url || 'Base64 编码');
if (result.text) {
  console.log('图像描述:', result.text);
}

// 2. 单图输入（文本 + 单张图片）
const result2 = await client.generate({
  prompt: 'Create a picture of my cat eating a nano-banana in a fancy restaurant',
  image: 'data:image/png;base64,iVBORw0KGgo...', // base64 编码的图片或 data URL
  model: 'gemini-2.5-flash-image',
  aspect_ratio: '16:9',
});

// 3. 多图输入（文本 + 多张图片）
// gemini-2.5-flash-image 最多支持 3 张图片
// gemini-3-pro-image-preview 最多支持 14 张图片
const result3 = await client.generate({
  prompt: 'An office group photo of these people, they are making funny faces.',
  image: [
    'data:image/png;base64,iVBORw0KGgo...', // 第一张图片
    'data:image/png;base64,iVBORw0KGgo...', // 第二张图片
    'data:image/png;base64,iVBORw0KGgo...', // 第三张图片
  ],
  model: 'gemini-3-pro-image-preview',
  aspect_ratio: '5:4',
  image_size: '2K',
  response_modalities: ['IMAGE'],
});

// 4. 使用 Gemini 3 Pro（专业模型，支持高分辨率）
const result4 = await client.generate({
  prompt: 'A futuristic city at night',
  model: 'gemini-3-pro-image-preview',
  aspect_ratio: '21:9', // 超宽屏
  image_size: '4K',    // 4K 分辨率
  response_modalities: ['IMAGE'], // 仅返回图片
});

console.log('4K 图像:', result4.data[0]?.b64_json ? 'Base64 编码' : result4.data[0]?.url);

用户认证工作流

import { getCurrentUserInfo, AuthClient } from 'ai-world-sdk';

// 1. 获取当前用户信息（使用便捷函数）
try {
  const userInfo = await getCurrentUserInfo();
  console.log('用户ID:', userInfo.id);
  console.log('用户名:', userInfo.full_name);
  console.log('邮箱:', userInfo.email);
  console.log('是否超级用户:', userInfo.is_superuser);
} catch (error) {
  console.error('获取用户信息失败:', error);
  // 可能需要重新登录
}

// 2. 使用 AuthClient 类（需要自定义配置时）
const authClient = new AuthClient({
  baseUrl: 'http://localhost:8000',
  token: 'your-jwt-token',
});

const userInfo = await authClient.getCurrentUserInfo();

// 3. 检查用户权限
if (userInfo.is_superuser) {
  console.log('用户是超级管理员');
}

if (userInfo.is_active) {
  console.log('用户账户已激活');
}

// 4. 显示用户信息
console.log(`欢迎, ${userInfo.full_name || userInfo.email || '用户'}`);
if (userInfo.avatar_url) {
  console.log('头像:', userInfo.avatar_url);
}

视频生成工作流

豆包视频生成（Doubao Seedance）

import { VideoGenerationClient } from 'ai-world-sdk';

const client = new VideoGenerationClient({});

// 1. 创建任务
const task = await client.create({
  prompt: 'A beautiful sunset over the ocean',
  duration: 5,
  aspect_ratio: '16:9',
  resolution: '720p',
});

// 2. 轮询直到完成
const result = await client.poll(task.id, {
  interval: 3000,
  timeout: 300000,
});

if (result.status === 'succeeded') {
  console.log('视频 URL:', result.content?.video_url);
  if (result.content?.last_frame_url) {
    console.log('最后一帧:', result.content.last_frame_url);
  }
} else {
  console.error('生成失败:', result.error?.message);
}

OpenAI 视频生成（Sora）

import { OpenAIVideoGenerationClient } from 'ai-world-sdk';

const client = new OpenAIVideoGenerationClient({});

// 1. 文本生成视频
const task = await client.generate({
  prompt: 'A serene mountain landscape with a flowing river',
  model: 'sora-2',           // 'sora-2' 或 'sora-2-pro'
  provider: 'aihubmix',      // 'aihubmix' 或 'api2img'
  seconds: '4',              // '4', '8', 或 '12'
  size: '1280x720'           // '720x1280', '1280x720', '1024x1792', '1792x1024'
});

console.log('任务已创建:', task.id);
console.log('任务状态:', task.status);

// 2. 查询任务状态
const status = await client.getTask(task.id, 'aihubmix');
console.log('当前状态:', status.status);

// 3. 轮询等待完成
const result = await client.waitForCompletion(
  task.id,
  'aihubmix',  // provider 参数
  {
    maxAttempts: 60,
    interval: 5000,
    onProgress: (status) => {
      console.log(`状态: ${status.status}`);
      if (status.status === 'in_progress') {
        console.log('正在生成...');
      }
    }
  }
);

if (result.status === 'completed') {
  console.log('✅ 视频生成成功！');
  
  // 4. 流式下载视频
  const videoBlob = await client.downloadVideo(
    result.id,
    'aihubmix',  // provider
    'video'      // 'video' 或 'thumbnail'
  );
  
  console.log('视频大小:', (videoBlob.size / 1024 / 1024).toFixed(2), 'MB');
  console.log('视频类型:', videoBlob.type);
  
  // 在浏览器中创建下载链接
  const url = URL.createObjectURL(videoBlob);
  const a = document.createElement('a');
  a.href = url;
  a.download = `sora_video_${result.id}.mp4`;
  a.click();
  URL.revokeObjectURL(url);
  
  // 也可以下载缩略图
  const thumbnail = await client.downloadVideo(
    result.id,
    'aihubmix',
    'thumbnail'
  );
  console.log('缩略图大小:', (thumbnail.size / 1024).toFixed(2), 'KB');
} else if (result.status === 'failed') {
  console.error('❌ 生成失败:', result.error);
}

// 一键生成并等待（简化版）
try {
  const result2 = await client.generateAndWait({
    prompt: 'A futuristic city with flying cars at night',
    model: 'sora-2',
    provider: 'aihubmix',
    seconds: '8',
    size: '1280x720'
  }, {
    maxAttempts: 60,
    interval: 5000,
    onProgress: (status) => console.log('进度:', status.status)
  });
  
  console.log('视频生成完成:', result2.id);
  
  // 流式下载
  const video = await client.downloadVideo(
    result2.id,
    'aihubmix',
    'video'
  );
  console.log('视频大小:', (video.size / 1024 / 1024).toFixed(2), 'MB');
} catch (error) {
  console.error('视频生成失败:', error);
}

// 图像生成视频示例
const imageToVideoTask = await client.generate({
  prompt: 'Make this scene come alive with gentle movements',
  input_reference: 'data:image/png;base64,iVBORw0KGgo...',  // 图像 base64 或 URL
  model: 'sora-2',
  provider: 'aihubmix',
  seconds: '4'
});

const imageToVideoResult = await client.waitForCompletion(
  imageToVideoTask.id,
  'aihubmix'
);

if (imageToVideoResult.status === 'completed') {
  console.log('图生视频完成:', imageToVideoResult.id);
  
  // 下载视频
  const videoBlob = await client.downloadVideo(
    imageToVideoResult.id,
    'aihubmix',
    'video'
  );
  console.log('视频已下载，大小:', videoBlob.size);
}

用户认证工作流

import { getCurrentUserInfo, AuthClient } from 'ai-world-sdk';

// 1. 获取当前用户信息（使用便捷函数）
try {
  const userInfo = await getCurrentUserInfo();
  console.log('用户ID:', userInfo.id);
  console.log('用户名:', userInfo.full_name);
  console.log('邮箱:', userInfo.email);
  console.log('是否超级用户:', userInfo.is_superuser);
} catch (error) {
  console.error('获取用户信息失败:', error);
  // 可能需要重新登录
}

// 2. 使用 AuthClient 类（需要自定义配置时）
const authClient = new AuthClient({
  baseUrl: 'http://localhost:8000',
  token: 'your-jwt-token',
});

const userInfo = await authClient.getCurrentUserInfo();

// 3. 检查用户权限
if (userInfo.is_superuser) {
  console.log('用户是超级管理员');
}

if (userInfo.is_active) {
  console.log('用户账户已激活');
}

// 4. 显示用户信息
console.log(`欢迎, ${userInfo.full_name || userInfo.email || '用户'}`);
if (userInfo.avatar_url) {
  console.log('头像:', userInfo.avatar_url);
}

下载代理工作流

import { DownloadClient } from 'ai-world-sdk';

const client = new DownloadClient({});

// 1. 普通下载（小文件）
const blob = await client.download({
  url: 'https://example.com/small-file.json',
  filename: 'data.json',
});

// 读取文件内容
const text = await blob.text();
const data = JSON.parse(text);
console.log('下载的数据:', data);

// 2. 下载并保存到本地
await client.downloadAsFile({
  url: 'https://example.com/document.pdf',
  filename: 'document.pdf',
});

// 3. 流式下载大文件（带进度显示）
let totalSize = 0;
const total = 1024 * 1024 * 100; // 假设已知总大小（实际应从响应头获取）

for await (const chunk of client.streamDownload({
  url: 'https://example.com/large-video.mp4',
  filename: 'video.mp4',
})) {
  totalSize += chunk.length;
  
  // 显示进度
  if (total) {
    const percent = Math.round((totalSize / total) * 100);
    console.log(`下载进度: ${percent}% (${totalSize}/${total} 字节)`);
  } else {
    console.log(`已下载: ${totalSize} 字节`);
  }
  
  // 可以在这里处理每个数据块
  // 例如：实时验证、显示下载速度等
}

console.log(`下载完成！总大小: ${totalSize} 字节`);

// 4. 批量下载多个文件
const urls = [
  'https://example.com/file1.zip',
  'https://example.com/file2.zip',
  'https://example.com/file3.zip',
];

for (const url of urls) {
  try {
    await client.downloadAsFile({
      url,
      filename: url.split('/').pop() || 'download',
    });
    console.log(`已下载: ${url}`);
  } catch (error) {
    console.error(`下载失败 ${url}:`, error);
  }
}

// 5. 流式下载并实时处理（例如：解析 JSON 流）
let buffer = '';
for await (const chunk of client.streamDownload({
  url: 'https://example.com/large-data.jsonl',
})) {
  // 将 Uint8Array 转换为字符串
  buffer += new TextDecoder().decode(chunk);
  
  // 处理完整的行
  const lines = buffer.split('\n');
  buffer = lines.pop() || ''; // 保留不完整的行
  
  for (const line of lines) {
    if (line.trim()) {
      const data = JSON.parse(line);
      console.log('处理数据:', data);
    }
  }
}

支持的模型

聊天模型

| 提供商 | Provider | 模型示例 | 模型类 | |--------|----------|----------|--------| | OpenAI | aihubmix | gpt-4o-mini, gpt-4, o1-preview | ChatOpenAI | | Google Gemini | gemini 或 aihubmix | gemini-2.5-flash-image, gemini-1.5-pro | ChatGoogleGenerativeAI | | Anthropic Claude | aihubmix | claude-3-sonnet-20240229, claude-3-opus-20240229 | ChatAnthropic | | Doubao | doubao 或 aihubmix | doubao-pro-4k, doubao-seedream-4-5-251128 | ChatOpenAI |

注意:

• 使用 aihubmix 或 api2img provider 可以访问所有模型，推荐用于多模型场景
• 使用特定 provider（如 gemini、doubao）会直接调用对应的官方 API

图像生成模型

• 豆包 Seedream:
  • doubao-seedream-4-5-251128 (4.5版本，默认) - 支持 2K、4K 和像素值尺寸
  • doubao-seedream-4-0 (4.0版本) - 支持 1K、2K、4K 和像素值尺寸
• Google Gemini:
  • gemini-2.5-flash-image (Nano Banana) - 推荐，快速、高效，1024px 分辨率，支持所有宽高比
  • gemini-3-pro-image-preview (Nano Banana Pro) - 专业级，支持 1K/2K/4K 分辨率，支持 Google 搜索、思考模式，最多 14 张参考图片
  • gemini-2.0-flash-exp-image-generation (已弃用，建议使用 gemini-2.5-flash-image)

模型选择建议：

• 日常使用: gemini-2.5-flash-image - 速度快，成本低
• 专业需求: gemini-3-pro-image-preview - 高分辨率、高级功能（需要 image_size 参数）

视频生成模型

豆包 Seedance

| 模型 | Provider | 说明 | 参数 | |------|----------|------|------| | doubao-seedance-1-0-pro-fast-251015 | doubao | 快速版（推荐） | 时长: 1-10秒，宽高比: 16:9/9:16/1:1 | | doubao-seedance-1-0-pro-250528 | doubao | 专业版 | 时长: 1-10秒，宽高比: 16:9/9:16/1:1 | | doubao-seedance-1-0-lite-t2v-250428 | doubao | 轻量版（文生视频） | 时长: 1-10秒 | | doubao-seedance-1-0-lite-i2v-250428 | doubao | 轻量版（图生视频） | 时长: 1-10秒 |

OpenAI Sora

| 模型 | Provider | 说明 | 参数 | |------|----------|------|------| | sora-2 | aihubmix / api2img | 标准模型（默认） | 时长: 4/8/12秒，分辨率: 720x1280, 1280x720, 1024x1792, 1792x1024 | | sora-2-pro | aihubmix / api2img | 专业版模型 | 时长: 4/8/12秒，分辨率: 720x1280, 1280x720, 1024x1792, 1792x1024 |

特性说明：

• 豆包 Seedance: 支持文本生成视频和图像生成视频，URL 直接返回
• OpenAI Sora: 支持文本生成视频和图像生成视频（Base64/URL），需要流式下载
• Provider 选择:
  • 豆包: 仅支持 doubao provider
  • OpenAI: 支持 aihubmix 和 api2img provider（推荐使用 aihubmix）

错误处理

try {
  const response = await model.invoke([
    new HumanMessage('Hello!'),
  ]);
  console.log(response.content);
} catch (error) {
  console.error('API 调用失败:', error);
  if (error instanceof Error) {
    console.error('错误消息:', error.message);
  }
}

开发

构建

npm run build

测试

npm test
# 或运行特定测试
npm run test:stream
npm run test:image-generation
npm run test:video-generation

参考链接

• LangChain.js - 设计灵感来源
• 火山引擎方舟平台 - 图像/视频生成 API 文档

许可证

MIT

更新日志

1.0.3

• ✨ 新增 Google Gemini 图像生成客户端
• ✨ 全局配置支持自动从浏览器环境获取
• ✨ 新增调试模式
• 🔧 改进日志输出

1.0.0

• ✨ 初始版本发布
• ✨ 支持聊天模型、图像生成、视频生成
• ✨ 兼容 LangChain.js 接口风格