Mineru SDK

Mineru SDK是一个用于浏览器环境的JavaScript/TypeScript工具包，用于与Mineru文档解析API进行交互。通过该SDK，你可以轻松地将Mineru的强大文档解析能力集成到你的Web应用中。

功能特性

• 创建单个文件解析任务
• 获取任务状态和结果
• 批量获取文件上传链接
• 上传本地文件并解析
• 批量创建URL文件解析任务
• 批量获取任务状态
• 任务状态轮询
• 错误处理和日志记录

安装

使用npm/yarn/pnpm安装:

# 使用npm
npm install @qzsy/mineru-sdk

# 使用yarn
yarn add @qzsy/mineru-sdk

# 使用pnpm
pnpm add @qzsy/mineru-sdk

快速开始

基本用法

import { MineruSDK } from '@qzsy/mineru-sdk';

// 创建SDK实例
const sdk = new MineruSDK('YOUR_API_TOKEN');

// 创建单个URL文件解析任务
async function createTask() {
  try {
    const response = await sdk.createTask({
      url: 'https://example.com/document.pdf',
      is_ocr: true,
      enable_formula: true
    });
    
    console.log('任务ID:', response.data.task_id);
    
    // 获取任务状态
    const status = await sdk.getTaskStatus(response.data.task_id);
    console.log('任务状态:', status.data.state);
  } catch (error) {
    console.error('Error:', error);
  }
}

createTask();

上传本地文件并解析

import { MineruSDK } from '@qzsy/mineru-sdk';

const sdk = new MineruSDK('YOUR_API_TOKEN');

async function uploadAndAnalyze(file) {
  try {
    // 获取上传链接
    const urlResponse = await sdk.getBatchFileUrls({
      files: [{ name: file.name, is_ocr: true }]
    });
    
    const batchId = urlResponse.data.batch_id;
    const uploadUrl = urlResponse.data.file_urls[0];
    
    // 上传文件
    await sdk.uploadFile(uploadUrl, file);
    
    // 轮询任务直到完成
    const result = await sdk.pollBatchTaskUntilComplete(batchId);
    console.log('解析结果:', result.data);
  } catch (error) {
    console.error('Error:', error);
  }
}

// 在浏览器中使用
document.getElementById('fileInput').addEventListener('change', (e) => {
  const file = e.target.files[0];
  uploadAndAnalyze(file);
});

轮询任务状态直到完成

import { MineruSDK } from '@qzsy/mineru-sdk';

const sdk = new MineruSDK('YOUR_API_TOKEN');

async function createAndWaitForCompletion() {
  try {
    // 创建任务
    const response = await sdk.createTask({
      url: 'https://example.com/document.pdf',
      is_ocr: true
    });
    
    const taskId = response.data.task_id;
    
    // 轮询任务直到完成，默认每3秒检查一次，最多尝试100次
    const finalStatus = await sdk.pollTaskUntilComplete(taskId);
    
    if (finalStatus.data.state === 'done') {
      console.log('任务完成! 下载链接:', finalStatus.data.full_zip_url);
    } else {
      console.error('任务失败:', finalStatus.data.err_msg);
    }
  } catch (error) {
    console.error('Error:', error);
  }
}

createAndWaitForCompletion();

API参考

MineruSDK类

构造函数

constructor(token: string, config?: AxiosRequestConfig)

• token: Mineru API令牌
• config: 可选的Axios配置对象

方法

创建单个任务

async createTask(params: CreateTaskParams): Promise<MineruResponse<CreateTaskResponse>>

获取任务状态

async getTaskStatus(taskId: string): Promise<MineruResponse<TaskStatusResponse>>

批量获取文件上传链接

async getBatchFileUrls(params: BatchFileUploadParams): Promise<MineruResponse<BatchFileUploadResponse>>

上传文件到预签名URL

async uploadFile(url: string, file: Blob): Promise<boolean>

批量创建URL任务

async createBatchUrlTasks(params: BatchURLTaskParams): Promise<MineruResponse<BatchURLTaskResponse>>

获取批量任务状态

async getBatchTaskStatus(batchId: string): Promise<MineruResponse<BatchTaskStatusResponse>>

检查任务是否完成

async isTaskCompleted(taskId: string): Promise<boolean>

轮询任务直到完成

async pollTaskUntilComplete(
  taskId: string,
  intervalMs: number = 3000,
  maxAttempts: number = 100
): Promise<MineruResponse<TaskStatusResponse>>

轮询批量任务直到完成

async pollBatchTaskUntilComplete(
  batchId: string,
  intervalMs: number = 3000,
  maxAttempts: number = 100
): Promise<MineruResponse<BatchTaskStatusResponse>>

工具类

SDK还提供了一个MineruUtils工具类，包含多个辅助函数：

• parsePageRanges: 解析页面范围字符串
• getMimeTypeFromFilename: 从文件名获取MIME类型
• generateUniqueId: 生成唯一ID
• checkFileSize: 检查文件大小是否超出限制
• formatProgressPercentage: 格式化进度百分比
• estimateRemainingTime: 估计剩余时间

示例

查看examples目录中的完整示例：

• basic-usage.ts: 基本SDK使用示例
• browser-example.html: 浏览器集成完整示例

注意事项

• 单个文件大小不能超过200MB
• 文件页数不能超过600页
• 由于网络限制，某些国外URL（如github、aws等）可能会请求超时

错误码

SDK内置了常见错误码的处理，主要错误码包括：

| 错误码 | 说明 | 解决建议 | |---------|---------|---------| | A0202 | Token错误 | 检查Token是否正确，或者更换新Token | | A0211 | Token过期 | 更换新Token | | -10001 | 服务异常 | 请稍后再试 | | -10002 | 请求参数错误 | 检查请求参数格式 | | -60001 | 生成上传URL失败 | 请稍后再试 | | -60004 | 空文件 | 请上传有效文件 | | -60005 | 文件大小超出限制 | 检查文件大小，最大支持200MB | | -60006 | 文件页数超过限制 | 请拆分文件后重试 |

更多错误码请参考官方文档。

许可证

MIT