SpeedPix JavaScript SDK

智作工坊 SpeedPix API 的官方 JavaScript SDK，支持 Node.js 和浏览器环境。

📚 关于智作工坊

智作工坊（AIGC Service Lab）是阿里云教育推出的 AIGC 生成服务，主要为泛教育、设计业务企业提供高效的 AIGC（人工智能生成内容）PAAS 服务。

🎯 核心功能

• 文生图：根据文本描述生成高质量图像
• 图生图：基于输入图像进行风格转换或内容变换
• 文转视频：将文本描述转换为动态视频内容
• 图转视频：将静态图像转换为动态视频

🔧 技术支持

• 支持通义万相以及开源的 Stable Diffusion 模型
• 提供 WEB UI 和 ComfyUI 两种模式
• 集成阿里云严格的内容安全检测服务
• 支持自定义界面部署和权限管理

📖 详细文档

• 智作工坊产品文档
• 产品概述
• 智作工坊控制台

安装

npm install speedpix

配置

提供两种配置方式：

方式一：环境变量（推荐）

export SPEEDPIX_ENDPOINT=your-endpoint.com  # 可选，默认为 https://openai.edu-aliyun.com
export SPEEDPIX_APP_KEY=your-app-key        # 必需
export SPEEDPIX_APP_SECRET=your-app-secret  # 必需

// 自动从环境变量加载
const client = new SpeedPix();

方式二：构造函数参数

// 基础配置（推荐）
const client = new SpeedPix({
  appKey: "your-app-key",
  appSecret: "your-app-secret"
});

// 完整配置（自定义端点和其他选项）
const client = new SpeedPix({
  appKey: "your-app-key",
  appSecret: "your-app-secret",
  endpoint: "https://your-endpoint.com",  // 可选，默认为 https://openai.edu-aliyun.com
  timeout: 60  // 可选，60秒超时
});

快速开始

最简单的用法

注意：可以选择性设置环境变量

export SPEEDPIX_ENDPOINT=your-endpoint.com  # 可选，默认为 https://openai.edu-aliyun.com
export SPEEDPIX_APP_KEY=your-app-key        # 必需
export SPEEDPIX_APP_SECRET=your-app-secret  # 必需

const speedpix = require("speedpix");

// 运行工作流（使用默认客户端，自动从环境变量加载）
const output = await speedpix.run("workflow-id", {
  input: {
    prompt: "a cute dog"
  },
  aliasId: "main" // 版本别名，默认为 "main"
});

// 处理输出
if (output?.images?.url) {
  await output.images.url.save("result.png");
  console.log("图片已保存");
}

标准用法

const SpeedPix = require("speedpix");

// 使用环境变量
const client = new SpeedPix();

// 运行工作流
const output = await client.run("workflow-id", {
  input: {
    prompt: "a cute dog"
  },
  aliasId: "main" // 版本别名，默认为 "main"
});

// 处理输出
if (output?.images?.url) {
  await output.images.url.save("result.png");
  console.log("图片已保存");
}

ESM 模块

import SpeedPix from "speedpix";

const client = new SpeedPix(); // 使用环境变量

const output = await client.run("workflow-id", {
  input: { prompt: "a cute dog" },
  aliasId: "main" // 版本别名，默认为 "main"
});

if (output?.images?.url) {
  await output.images.url.save("result.png");
}

TypeScript

import SpeedPix from "speedpix";

const client = new SpeedPix(); // 使用环境变量

const output = await client.run("workflow-id", {
  input: { prompt: "TypeScript 示例" },
  aliasId: "main" // 版本别名，默认为 "main"
});

主要功能

1. 运行工作流

// 同步执行（等待完成）
const output = await client.run("workflow-id", {
  input: {
    prompt: "a beautiful landscape",
    style: "impressionism"
  },
  aliasId: "main" // 版本别名，默认为 "main"
});

// 异步执行（不等待）
const prediction = await client.run("workflow-id", {
  input: { prompt: "复杂场景" },
  aliasId: "main", // 版本别名，默认为 "main"
  wait: false
});

console.log(`任务 ID: ${prediction.id}`);
const result = await prediction.wait();

2. 版本控制

SpeedPix 支持两种版本指定方式，二者互斥：

// 方式一：使用版本别名（推荐）
const output = await client.run("workflow-id", {
  input: { prompt: "test" },
  aliasId: "main"  // 使用版本别名，默认为 "main"
});

// 方式二：使用具体版本ID
const output = await client.run("workflow-id", {
  input: { prompt: "test" },
  versionId: "6ac5c995-4c28-4777-b9fc-03ca24f65d64"  // 使用具体版本ID
});

// 注意：如果同时提供 versionId 和 aliasId，只会使用 versionId
// 推荐只使用其中一种方式

版本选择规则：

• 如果未提供 versionId 和 aliasId，则自动使用 aliasId: "main"
• 如果提供了 versionId，则使用指定的版本ID（忽略 aliasId）
• 如果提供了 aliasId，则使用指定的版本别名

3. 文件上传

// 上传本地文件
const file = await client.files.create("./image.jpg");

// 在工作流中使用
const output = await client.run("workflow-id", {
  input: {
    image: file.accessUrl,
    prompt: "a cute girl"
  },
  aliasId: "main" // 版本别名，默认为 "main"
});

// 处理结果
if (output?.images?.url) {
  await output.images.url.save("processed_image.png");
}

3. 输出处理

输出始终是映射结构：

const output = await client.run("workflow-id", { input: {...} });

// 常见模式 - 图片输出
if (output?.images?.url) {
  await output.images.url.save("result.png");
  console.log("下载链接:", output.images.url.toString());
}

// 多个输出示例
if (output?.image1?.url) {
  await output.image1.url.save("image1.png");
}
if (output?.image2?.url) {
  await output.image2.url.save("image2.png");
}

// 处理不同的输出结构
if (output?.result?.url) {
  await output.result.url.save("result.png");
}

4. 错误处理

try {
  const output = await client.run("workflow-id", { input: {...} });

  // 处理成功输出
  if (output?.images?.url) {
    await output.images.url.save("result.png");
    console.log("图片保存成功");
  }
} catch (error) {
  if (error instanceof SpeedPix.SpeedPixTimeoutError) {
    console.log("请求超时");
  } else if (error instanceof SpeedPix.SpeedPixError) {
    console.log("API 错误:", error.message);
  } else {
    console.log("未知错误:", error.message);
  }
}

🚀 资源配置

共享算力 vs 独享资源

智作工坊支持两种资源类型：

• 共享算力：默认使用，成本较低，适合一般业务场景
• 独享资源：推荐对延迟和成功率敏感的业务使用，提供更稳定的性能保障

配置方式

默认情况下，如果不指定 resourceConfigId，系统会使用共享算力资源。如果您对延迟和成功率有较高要求，推荐配置独享资源。

const SpeedPix = require("speedpix");
const client = new SpeedPix({
  appKey: "your-app-key",
  appSecret: "your-app-secret"
});

// 使用共享算力（默认）
const output1 = await client.run("workflow-id", {
  input: {
    prompt: "一个美丽的风景"
  },
  aliasId: "main"
  // 不指定 resourceConfigId 时自动使用共享算力
});

// 使用独享资源
const output2 = await client.run("workflow-id", {
  input: {
    prompt: "一个美丽的风景"
  },
  aliasId: "main",
  resourceConfigId: "your-dedicated-resource-id"  // 指定独享资源ID
});

// 通过 createPrediction 指定独享资源
const prediction = await client.predictions.create({
  workflowId: "workflow-id",
  input: {
    prompt: "一个美丽的风景"
  },
  aliasId: "main",
  resourceConfigId: "your-dedicated-resource-id"
});

相关文档

• 独享资源管理
• 资源配置参数说明

API 参考

模块级函数（最简单）

注意：必须设置环境变量 SPEEDPIX_APP_KEY, SPEEDPIX_APP_SECRET SPEEDPIX_ENDPOINT 是可选的，默认为 https://openai.edu-aliyun.com

const speedpix = require("speedpix");

// 直接使用模块级函数（使用默认客户端，自动从环境变量加载）
await speedpix.run(workflowId, options);

SpeedPix 类

// 方式一：使用环境变量
const client = new SpeedPix();

// 方式二：显式参数
const client = new SpeedPix({
  endpoint: "string",     // 可选：API 端点，默认为 https://openai.edu-aliyun.com
  appKey: "string",       // 必需：应用密钥
  appSecret: "string",    // 必需：应用密码
  userAgent: "string"     // 可选：用户代理
});

run() 方法

await client.run(workflowId, options);

参数：

• workflowId (string): 工作流 ID
• options (object):
  • input (object): 输入参数
  • aliasId (string, 可选): 版本别名，默认为 "main"
  • versionId (string, 可选): 具体版本ID，与 aliasId 互斥
  • resourceConfigId (string, 可选): 资源配置 ID，默认为 "default"
  • wait (boolean, 可选): 是否等待完成，默认为 true
  • timeout (number, 可选): 超时时间（秒）

注意： aliasId 和 versionId 是互斥的，推荐优先使用 aliasId。

files.create() 方法

const file = await client.files.create(filePath);

返回：

• file.accessUrl: 文件访问 URL
• file.id: 文件 ID

许可证

MIT