# minikai 中文文档

规范地址：https://npmcn.com/package/minikai/

版本：1\.28\.1
npm 元数据更新时间：2026-11-04T04:18:02.526Z
中文译文更新时间：2026-11-04T04:29:17.042Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/minikai
原文对照：https://npmcn.com/package/minikai/?lang=original
项目主页：https://github.com/Minikai-Pty-Ltd/minikai-typescript#readme
源码仓库：https://github.com/Minikai-Pty-Ltd/minikai-typescript

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.2 MB，791 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2026-06-04T10:37:19.215Z
- 最新版本发布：2026-11-04T04:18:02.310Z
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com/?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2FMinikai-Pty-Ltd%2Fminikai-typescript) \[!(np

## 安装

```sh
npm install minikai
```

也可以使用：`pnpm add minikai`、`yarn add minikai`、`bun add minikai`

## README

# Minikai TypeScript库

[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com/?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2FMinikai-Pty-Ltd%2Fminikai-typescript) [![npm shield](https://img.shields.io/npm/v/minikai)](https://www.npmjs.com/package/minikai)

Minikai TypeScript库提供了从TypeScript访问Minikai api的便利。

## 目录表

-   [安装](https://npmcn.com/package/minikai/#readme-installation)
-   [参考](https://npmcn.com/package/minikai/#readme-reference)
-   [用法](https://npmcn.com/package/minikai/#readme-usage)
-   [环境](https://npmcn.com/package/minikai/#readme-environments)
-   [请求和响应类型](https://npmcn.com/package/minikai/#readme-request-and-response-types)
-   [异常处理](https://npmcn.com/package/minikai/#readme-exception-handling)
-   [文件上传](https://npmcn.com/package/minikai/#readme-file-uploads)
-   [二进制响应](https://npmcn.com/package/minikai/#readme-binary-response)
-   [先进的](https://npmcn.com/package/minikai/#readme-advanced)
    -   [分包出口](https://npmcn.com/package/minikai/#readme-subpackage-exports)
    -   [附加报头](https://npmcn.com/package/minikai/#readme-additional-headers)
    -   [其他查询字符串参数](https://npmcn.com/package/minikai/#readme-additional-query-string-parameters)
    -   [重试](https://npmcn.com/package/minikai/#readme-retries)
    -   [超时](https://npmcn.com/package/minikai/#readme-timeouts)
    -   [流产的请求](https://npmcn.com/package/minikai/#readme-aborting-requests)
    -   [访问原始响应数据](https://npmcn.com/package/minikai/#readme-access-raw-response-data)
    -   [日志记录](https://npmcn.com/package/minikai/#readme-logging)
    -   [自定义获取](https://npmcn.com/package/minikai/#readme-custom-fetch)
    -   [运行时的兼容性](https://npmcn.com/package/minikai/#readme-runtime-compatibility)
-   [贡献](https://npmcn.com/package/minikai/#readme-contributing)

## 安装

```sh
npm i -s minikai
```

## 参考

这个库的完整参考资料是可用的 [在这里](https://github.com/Minikai-Pty-Ltd/minikai-typescript/blob/HEAD/reference.md)。

## 用法

实例化和使用客户端如下：

```typescript
import { MinikaiClient } from "minikai";

const client = new MinikaiClient({ token: "YOUR_TOKEN" });
await client.labelGroups.createLabelGroup({
    name: "name",
    resourceType: "record"
});
```

## 环境

这个SDK允许您为API请求配置不同的环境。

```typescript
import { MinikaiClient, MinikaiEnvironment } from "minikai";

const client = new MinikaiClient({
    environment: MinikaiEnvironment.Australia,
});
```

## 请求和响应类型

SDK将所有的请求和响应类型导出为TypeScript接口。简单地导入它们 名称空间:

```typescript
import { Minikai } from "minikai";

const request: Minikai.CreateLabelGroupCommand = {
    ...
};
```

## 异常处理

当API返回非成功状态码（4xx或5xx响应）时，将生成以下错误的子类 会被扔。

```typescript
import { MinikaiError } from "minikai";

try {
    await client.labelGroups.createLabelGroup(...);
} catch (err) {
    if (err instanceof MinikaiError) {
        console.log(err.statusCode);
        console.log(err.message);
        console.log(err.body);
        console.log(err.rawResponse);
    }
}
```

## 文件上传

您可以使用客户端上传文件：

```typescript
import { createReadStream } from "fs";
import * as fs from "fs";
import { MinikaiClient } from "minikai";

const client = new MinikaiClient({ token: "YOUR_TOKEN" });
await client.minis.uploadMiniProfilePicture("id", {
    file: fs.createReadStream("/path/to/your/file")
});
```

客户端接受各种类型的文件上传参数：

-   流类型: `fs.ReadStream`， `stream.Readable`, `ReadableStream`
-   缓冲类型: `Buffer`， `Blob`， `File`， `ArrayBuffer`， `ArrayBufferView`, `Uint8Array`

### 元数据

您可以在上传文件时配置元数据：

```typescript
const file: Uploadable.WithMetadata = {
    data: createReadStream("path/to/file"),
    filename: "my-file",       // optional
    contentType: "audio/mpeg", // optional
    contentLength: 1949,       // optional
};
```

或者，您可以直接从文件路径上传文件：

```typescript
const file : Uploadable.FromPath = {
    path: "path/to/file",
    filename: "my-file",        // optional
    contentType: "audio/mpeg",  // optional
    contentLength: 1949,        // optional
};
```

元数据用于设置 `Content-Length`， `Content-Type`, `Content-Disposition` 头。如果没有提供，客户端将尝试自动确定它们。 例如, `fs.ReadStream` 有一个 `path` 属性，SDK使用该属性从文件系统检索文件大小，而不将其加载到内存中。

## 二进制响应

方法从端点使用二进制数据 `BinaryResponse` 类型，它允许您选择如何使用数据：

```typescript
const response = await client.minis.downloadMiniProfilePicture(...);
const stream: ReadableStream<Uint8Array> = response.stream();
// const arrayBuffer: ArrayBuffer = await response.arrayBuffer();
// const blob: Blob = response.blob();
// const bytes: Uint8Array = response.bytes();
// You can only use the response body once, so you must choose one of the above methods.
// If you want to check if the response body has been used, you can use the following property.
const bodyUsed = response.bodyUsed;
```

将二进制响应保存到文件中

> node . js
> 
> > ReadableStream(最有效)
> > 
> > ```ts
> > import { createWriteStream } from 'fs';
> > import { Readable } from 'stream';
> > import { pipeline } from 'stream/promises';
> > 
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const stream = response.stream();
> > const nodeStream = Readable.fromWeb(stream);
> > const writeStream = createWriteStream('path/to/file');
> > 
> > await pipeline(nodeStream, writeStream);
> > ```
> 
> > ArrayBuffer
> > 
> > ```ts
> > import { writeFile } from 'fs/promises';
> > 
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const arrayBuffer = await response.arrayBuffer();
> > await writeFile('path/to/file', Buffer.from(arrayBuffer));
> > ```
> 
> > 团
> > 
> > ```ts
> > import { writeFile } from 'fs/promises';
> > 
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const blob = await response.blob();
> > const arrayBuffer = await blob.arrayBuffer();
> > await writeFile('output.bin', Buffer.from(arrayBuffer));
> > ```
> 
> > 字节(UIntArray8)
> > 
> > ```ts
> > import { writeFile } from 'fs/promises';
> > 
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const bytes = await response.bytes();
> > await writeFile('path/to/file', bytes);
> > ```

> 包子
> 
> > ReadableStream(最有效)
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const stream = response.stream();
> > await Bun.write('path/to/file', stream);
> > ```
> 
> > ArrayBuffer
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const arrayBuffer = await response.arrayBuffer();
> > await Bun.write('path/to/file', arrayBuffer);
> > ```
> 
> > 团
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const blob = await response.blob();
> > await Bun.write('path/to/file', blob);
> > ```
> 
> > 字节(UIntArray8)
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const bytes = await response.bytes();
> > await Bun.write('path/to/file', bytes);
> > ```

> Deno
> 
> > ReadableStream(最有效)
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const stream = response.stream();
> > const file = await Deno.open('path/to/file', { write: true, create: true });
> > await stream.pipeTo(file.writable);
> > ```
> 
> > ArrayBuffer
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const arrayBuffer = await response.arrayBuffer();
> > await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
> > ```
> 
> > 团
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const blob = await response.blob();
> > const arrayBuffer = await blob.arrayBuffer();
> > await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
> > ```
> 
> > 字节(UIntArray8)
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const bytes = await response.bytes();
> > await Deno.writeFile('path/to/file', bytes);
> > ```

> 浏览器
> 
> > Blob(最有效)
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const blob = await response.blob();
> > const url = URL.createObjectURL(blob);
> > 
> > // trigger download
> > const a = document.createElement('a');
> > a.href = url;
> > a.download = 'filename';
> > a.click();
> > URL.revokeObjectURL(url);
> > ```
> 
> > ReadableStream
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const stream = response.stream();
> > const reader = stream.getReader();
> > const chunks = [];
> > 
> > while (true) {
> >   const { done, value } = await reader.read();
> >   if (done) break;
> >   chunks.push(value);
> > }
> > 
> > const blob = new Blob(chunks);
> > const url = URL.createObjectURL(blob);
> > 
> > // trigger download
> > const a = document.createElement('a');
> > a.href = url;
> > a.download = 'filename';
> > a.click();
> > URL.revokeObjectURL(url);
> > ```
> 
> > ArrayBuffer
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const arrayBuffer = await response.arrayBuffer();
> > const blob = new Blob([arrayBuffer]);
> > const url = URL.createObjectURL(blob);
> > 
> > // trigger download
> > const a = document.createElement('a');
> > a.href = url;
> > a.download = 'filename';
> > a.click();
> > URL.revokeObjectURL(url);
> > ```
> 
> > 字节(UIntArray8)
> > 
> > ```ts
> > const response = await client.minis.downloadMiniProfilePicture(...);
> > 
> > const bytes = await response.bytes();
> > const blob = new Blob([bytes]);
> > const url = URL.createObjectURL(blob);
> > 
> > // trigger download
> > const a = document.createElement('a');
> > a.href = url;
> > a.download = 'filename';
> > a.click();
> > URL.revokeObjectURL(url);
> > ```
将二进制响应转换为文本

> ReadableStream
> 
> ```ts
> const response = await client.minis.downloadMiniProfilePicture(...);
> 
> const stream = response.stream();
> const text = await new Response(stream).text();
> ```

> ArrayBuffer
> 
> ```ts
> const response = await client.minis.downloadMiniProfilePicture(...);
> 
> const arrayBuffer = await response.arrayBuffer();
> const text = new TextDecoder().decode(arrayBuffer);
> ```

> 团
> 
> ```ts
> const response = await client.minis.downloadMiniProfilePicture(...);
> 
> const blob = await response.blob();
> const text = await blob.text();
> ```

> 字节(UIntArray8)
> 
> ```ts
> const response = await client.minis.downloadMiniProfilePicture(...);
> 
> const bytes = await response.bytes();
> const text = new TextDecoder().decode(bytes);
> ```

## 先进的

### 分包出口

这个SDK支持直接导入子包客户端，这允许JavaScript打包器进行树摇，只包含导入的子包代码。这将导致更小的包大小。

```typescript
import { LabelGroupsClient } from 'minikai/labelGroups';

const client = new LabelGroupsClient({...});
```

### 附加报头

如果您希望发送额外的标头作为请求的一部分，请使用 `headers` 请求的选项。

```typescript
import { MinikaiClient } from "minikai";

const client = new MinikaiClient({
    ...
    headers: {
        'X-Custom-Header': 'custom value'
    }
});

const response = await client.labelGroups.createLabelGroup(..., {
    headers: {
        'X-Custom-Header': 'custom value'
    }
});
```

### 其他查询字符串参数

如果希望将其他查询字符串参数作为请求的一部分发送，请使用 `queryParams` 请求的选项。

```typescript
const response = await client.labelGroups.createLabelGroup(..., {
    queryParams: {
        'customQueryParamKey': 'custom query param value'
    }
});
```

### 重试

SDK配备了自动重试和指数回退。请求将被重试 由于该请求被认为是可重试的，并且重试尝试的次数没有超过配置 重试限制（默认为2）。

重试哪些状态码取决于 `retryStatusCodes` 发电机配置:

**`legacy`** （当前默认值）：重试

-   [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (超时)
-   [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) （请求太多）
-   [5 xx](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) （所有服务器错误，包括500）

**`recommended`**retries on

-   [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (超时)
-   [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) （请求太多）
-   [502](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) (错误网关)
-   [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) (服务不可用)
-   [504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) (网关超时)

使用 `maxRetries` 请求选项来配置此行为。

```typescript
const response = await client.labelGroups.createLabelGroup(..., {
    maxRetries: 0 // override maxRetries at the request level
});
```

### 超时

SDK默认为60秒超时。使用 `timeoutInSeconds` 选项配置此行为。

```typescript
const response = await client.labelGroups.createLabelGroup(..., {
    timeoutInSeconds: 30 // override timeout to 30s
});
```

### 流产的请求

SDK允许用户在任何时候通过传入一个中止信号来中止请求。

```typescript
const controller = new AbortController();
const response = await client.labelGroups.createLabelGroup(..., {
    abortSignal: controller.signal
});
controller.abort(); // aborts the request
```

### 访问原始响应数据

方法提供对原始响应数据（包括标头）的访问 `.withRawResponse()` 方法。 这个 `.withRawResponse()` 方法返回一个promise，该promise的结果是一个带有 `data` 和一个 `rawResponse` 财产。

```typescript
const { data, rawResponse } = await client.labelGroups.createLabelGroup(...).withRawResponse();

console.log(data);
console.log(rawResponse.headers['X-My-Header']);
```

### 日志记录

SDK支持日志记录。可以通过传入参数来配置日志记录器 `logging` 对象到客户端选项。

```typescript
import { MinikaiClient, logging } from "minikai";

const client = new MinikaiClient({
    ...
    logging: {
        level: logging.LogLevel.Debug, // defaults to logging.LogLevel.Info
        logger: new logging.ConsoleLogger(), // defaults to ConsoleLogger
        silent: false, // defaults to true, set to false to enable logging
    }
});
```

这个 `logging` 对象可以具有以下属性：

-   `level`：要使用的日志级别。默认为 `logging.LogLevel.Info`。
-   `logger`：要使用的记录器。默认为a。 `logging.ConsoleLogger`。
-   `silent`：是否关闭日志记录器。默认为 `true`。

这个 `level` 属性可以是以下值之一：

-   `logging.LogLevel.Debug`
-   `logging.LogLevel.Info`
-   `logging.LogLevel.Warn`
-   `logging.LogLevel.Error`

要提供自定义日志记录器，可以传入一个对象，该对象实现 `logging.ILogger` 接口。

自定义日志程序示例

下面是一个使用popular的例子 `winston` 日志库。

```ts
import winston from 'winston';

const winstonLogger = winston.createLogger({...});

const logger: logging.ILogger = {
    debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
    info: (msg, ...args) => winstonLogger.info(msg, ...args),
    warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
    error: (msg, ...args) => winstonLogger.error(msg, ...args),
};
```

下面是一个使用popular的例子 `pino` 日志库。

```ts
import pino from 'pino';

const pinoLogger = pino({...});

const logger: logging.ILogger = {
  debug: (msg, ...args) => pinoLogger.debug(args, msg),
  info: (msg, ...args) => pinoLogger.info(args, msg),
  warn: (msg, ...args) => pinoLogger.warn(args, msg),
  error: (msg, ...args) => pinoLogger.error(args, msg),
};
```

### 自定义获取

SDK提供了一个底层 `fetch` 方法，用于在静止时发出自定义HTTP请求 受益于sdk级别的配置，如身份验证、重试、超时和日志记录。 这对于调用SDK中尚未支持的API端点非常有用。

```typescript
const response = await client.fetch("/v1/custom/endpoint", {
    method: "GET",
}, {
    timeoutInSeconds: 30,
    maxRetries: 3,
    headers: {
        "X-Custom-Header": "custom-value",
    },
});

const data = await response.json();
```

### 运行时的兼容性

SDK工作在以下运行时：

-   node . js 18 +
-   Vercel
-   Cloudflare工人
-   Deno v1.25 +
-   面包1.0 +
-   反应本地

## 贡献

虽然我们重视对这个SDK的开源贡献，但这个库是通过编程生成的。 直接添加到这个库的内容必须移动到我们的生成代码中， 否则，它们将在下一个生成的版本中被覆盖。请随意打开PR帐户 一个概念的证明，但知道我们将无法合并它。我们建议 一个问题先和我们讨论！

另一方面，对README的贡献总是非常受欢迎的！

## 常见问题

### minikai 是什么？

\[\!\(np

### 如何安装 minikai？

在项目目录运行 npm install minikai，或使用 pnpm add / yarn add / bun add。

### minikai 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### minikai 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### minikai 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### minikai 可以商用吗？

minikai 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### minikai 还在维护吗？

最新版本 1\.28\.1 发布于 2026/11/04（今天）；至今共发布 32 个版本，其中过去 12 个月发布了 32 个；首次发布于 2026/06/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。