@qzsy/image-processing-sdk

Image Processing Service 的 TypeScript / Bun 客户端。

对接异步任务 API：创建主体抠图 / 图标切图任务 → 轮询状态 → 拿到 CDN 资源与 manifest。

• 类型完整：请求、状态、manifest 均为严格类型，无 any
• 运行时校验：getJob / waitForJob 会对响应做结构收窄
• 零依赖：使用标准 fetch（Bun / Node 18+ / 浏览器）

安装

在 monorepo 内本地引用：

cd sdk
bun install
bun run build

其他项目：

bun add ../path/to/image-processing-service/sdk
# 或 npm / pnpm / yarn 指向该目录

快速开始

import {
  ImageServiceClient,
  isSubjectManifest,
  isSliceSetManifest,
  ImageServiceJobError,
} from "@image-service/sdk";

const client = new ImageServiceClient({
  baseUrl: "http://localhost:8000",
  apiKey: process.env.IMAGE_SERVICE_API_KEY, // 服务端配置了 API_KEY 时必填
});

// 主体抠图：提交并等待完成
const subject = await client.subject({
  image_url: "https://cdn.example.com/product.jpg",
  remove_background: true,
  output: {
    canvas_width: 1024,
    canvas_height: 1024,
    format: "png",
  },
});

if (isSubjectManifest(subject.result)) {
  console.log(subject.result.asset.url);
  console.log(subject.result.processing.source_subject_box);
}

// 图标切图
const slices = await client.slices({
  image_url: "https://cdn.example.com/icon-sheet.png",
  options: {
    mode: "grid",
    rows: 3,
    columns: 3,
    background: "auto",
  },
});

if (isSliceSetManifest(slices.result)) {
  for (const item of slices.result.items) {
    console.log(item.name, item.asset.url);
  }
}

客户端配置

| 选项 | 类型 | 说明 | |------|------|------| | baseUrl | string | 服务地址，如 http://localhost:8000 | | apiKey? | string | 对应请求头 X-API-Key | | fetch? | typeof fetch | 自定义 fetch（测试 / 代理） | | headers? | Record<string, string> | 默认额外请求头 | | signal? | AbortSignal | 应用到单次 HTTP 请求 |

API 方法

健康检查

await client.live();  // GET /health/live  → { status: "ok" }
await client.ready(); // GET /health/ready → { status: "ready" }

创建任务（立即返回）

const created = await client.createSubjectJob({ image_url: "..." });
// { job_id, status: "queued", status_url }

const created2 = await client.createSliceJob({
  image_url: "...",
  options: { mode: "auto" },
});

查询 / 等待

const status = await client.getJob(created.job_id);
// status: "queued" | "running" | "succeeded" | "failed"

const done = await client.waitForJob(created.job_id, {
  intervalMs: 1000,
  timeoutMs: 120_000,
  onProgress: (s) => console.log(s.progress, s.stage),
});

便捷方法 client.subject() / client.slices() = 创建 + waitForJob。

任务状态与结果

JobStatus 按 status 字段区分：

| status | 含义 | 关键字段 | |--------|------|----------| | queued | 排队中 | progress, stage | | running | 处理中 | progress, stage | | succeeded | 成功 | result（manifest） | | failed | 失败 | error（code / message / retryable） |

成功时 result 为判别联合：

• type: "subject" → SubjectManifest（含 asset）
• type: "slice-set" → SliceSetManifest（含 items[]）

类型守卫：

import { isSubjectManifest, isSliceSetManifest, isSucceededJobStatus } from "@image-service/sdk";

if (isSucceededJobStatus(status) && isSubjectManifest(status.result)) {
  status.result.asset.url; // string
}

请求字段摘要

SubjectRequest

| 字段 | 默认 | 说明 | |------|------|------| | image_url | 必填 | HTTP(S) 图片 URL | | remove_background | true | 是否抠图 | | model | null | rembg 模型覆盖 | | alpha_matting | null | alpha matting 覆盖 | | output | 1024×1024 / padding 0.06 | 画布与编码 | | client_reference | null | 业务侧关联 ID（≤128） |

SliceRequest.options

| 字段 | 默认 | 说明 | |------|------|------| | mode | "auto" | auto / grid / components | | rows / columns | null | 必须成对；mode=grid 时必填 | | background | "auto" | auto / alpha / color / ai | | max_items | 200 | 最大切图数 | | output | 512×512 / padding 0.08 | 每个图标的画布 |

错误处理

| 错误类 | 场景 | |--------|------| | ImageServiceApiError | HTTP 4xx/5xx、网络失败（含 status、code、detail） | | ImageServiceJobError | 任务 failed（含 jobError、retryable） | | ImageServiceTimeoutError | waitForJob 超时 | | ImageServiceAbortError | AbortSignal 取消 |

try {
  await client.subject({ image_url: "..." });
} catch (err) {
  if (err instanceof ImageServiceJobError) {
    console.error(err.code, err.retryable, err.message);
  } else if (err instanceof ImageServiceApiError) {
    console.error(err.status, err.code, err.message);
  } else {
    throw err;
  }
}

常见 API code：unauthorized、job_not_found、queue_unavailable。
常见任务 code：download_error、unsafe_source、invalid_image、empty_subject、slice_detection_error、storage_error。

开发

bun install
bun run typecheck
bun run build
bun test

构建产物在 dist/（ESM + .d.ts）。

与服务端对应关系

| SDK | HTTP | |-----|------| | createSubjectJob | POST /v1/jobs/subject → 202 | | createSliceJob | POST /v1/jobs/slices → 202 | | getJob | GET /v1/jobs/{job_id} | | live / ready | GET /health/live / ready |

服务端仓库：上级目录 image-processing-service（FastAPI + Celery）。