更新于 2026-05-17  ·  版本 v1.6

API 开发文档

通过 Moxu RESTful API，将文档格式转换能力无缝集成到您的应用、工作流或自动化脚本中，支持 50+ 种格式互转，高可用稳定保障。

快速入门 #

Moxu API 基于 REST 架构，所有请求与响应均使用 JSON 格式（文件上传使用 multipart/form-data）。

Base URLhttps://api.moxu.com/v1
协议HTTPS / TLS 1.2+（HTTP 请求将被拒绝）
响应格式application/json，UTF-8 编码
时间格式ISO 8601，如 2026-05-01T08:00:00Z

五分钟快速上手

  1. 获取 API Key：登录 用户中心 → 开发者设置 → 新建密钥
  2. 发起转换：POST 上传文件，获取 task_id
  3. 查询结果：轮询状态接口，或配置 Webhook 主动接收通知
  4. 下载文件：状态为 done 后，GET 下载转换结果
# 1. 发起转换
curl -X POST https://api.moxu.com/v1/convert \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -F "file=@/path/to/document.docx" \
  -F "to=pdf"

# 2. 查询状态（用返回的 task_id）
curl -H "Authorization: Bearer kd_live_your_api_key" \
  https://api.moxu.com/v1/tasks/tkd_a1b2c3d4

# 3. 下载结果文件
curl -L -o result.pdf \
  -H "Authorization: Bearer kd_live_your_api_key" \
  https://api.moxu.com/v1/download/tkd_a1b2c3d4
// npm install form-data node-fetch
const FormData = require('form-data');
const fetch = require('node-fetch');
const fs = require('fs');

const API_KEY = 'kd_live_your_api_key';
const form = new FormData();
form.append('file', fs.createReadStream('document.docx'));
form.append('to', 'pdf');

const res = await fetch('https://api.moxu.com/v1/convert', {
  method: 'POST',
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: form
});
const { data } = await res.json();
console.log('task_id:', data.task_id);
# pip install requests
import requests

API_KEY = "kd_live_your_api_key"
headers = {"Authorization": f"Bearer {API_KEY}"}

with open("document.docx", "rb") as f:
    resp = requests.post(
        "https://api.moxu.com/v1/convert",
        headers=headers,
        files={"file": f},
        data={"to": "pdf"}
    )
task_id = resp.json()["data"]["task_id"]
print(f"task_id: {task_id}")

鉴权方式 #

所有 API 请求需在 HTTP 请求头中携带 API Key，使用 Bearer Token 方案。

Authorization: Bearer kd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Key 类型

类型前缀说明
测试密钥kd_test_开发测试用，不消耗配额，输出文件带水印
生产密钥kd_live_正式生产环境，消耗套餐配额，输出无水印
🔒
安全警告

API Key 拥有账户完整权限，请勿提交至公开代码仓库，不要硬编码在前端或移动端代码中。建议通过后端服务器中转调用。

速率限制 #

超出速率限制后返回 HTTP 429，请实现指数退避重试。响应头中包含当前限额信息：

套餐并发任务每分钟请求月配额
免费版110500 次
基础版3605,000 次
专业版1020050,000 次
企业版不限不限按量计费
 
X-RateLimit-Limit:     200       # 本分钟上限
X-RateLimit-Remaining: 187       # 本分钟剩余
X-RateLimit-Reset:     1746086460 # 重置时间（Unix 时间戳）
X-Quota-Monthly:       50000     # 月总配额
X-Quota-Used:          1234      # 本月已用

发起转换 #

HTTP URLhttps://api.moxu.com/v1/convert
HTTP MethodPOST
Content-Typemultipart/form-data（含文件）/ application/json（URL 模式）
权限要求有效 API Key（测试/生产均可）

上传本地文件或指定远程 URL，触发异步格式转换任务，立即返回 task_id。

请求参数

参数名类型必填说明
fileFile必填*上传的原始文件。与 url 二选一
urlstring必填*远程文件 HTTPS 地址，系统自动拉取。与 file 二选一
tostring必填目标格式标识符，如 pdf、docx、png
fromstring可选源格式，不填则自动检测（建议填写以提升准确率）
pagesstring可选页码范围，如 1-3、1,4,7、2-（多页文档有效）
qualityinteger可选图片质量 1~100，默认 85（仅图片输出格式有效）
dpiinteger可选渲染分辨率，默认 150，范围 72~600
passwordstring可选受密码保护文件的解密密码（PDF / Office）
webhookstring可选转换完成后回调的 HTTPS 地址
metastring可选透传元数据，Webhook 回调时原样返回，最长 1024 字符

响应格式

{
  "code":    0,
  "message": "success",
  "data": {
    "task_id":    "tkd_a1b2c3d4e5f6",
    "status":     "processing",
    "from":       "docx",
    "to":         "pdf",
    "file_size":  204800,
    "created_at": "2026-05-17T08:00:00Z"
  }
}
💡
推荐使用 Webhook

发起转换时传入 webhook 参数，完成后系统主动推送，无需轮询。查看 Webhook 文档 →

查询状态 #

HTTP URLhttps://api.moxu.com/v1/tasks/{task_id}
HTTP MethodGET
权限要求有效 API Key

任务状态说明

状态值描述
pending任务已接收，等待调度处理
processing正在转换中
done转换成功，可下载结果文件
failed转换失败，error 字段包含原因
cancelled任务已取消
 
{
  "code": 0,
  "data": {
    "task_id":     "tkd_a1b2c3d4e5f6",
    "status":      "done",
    "from":        "docx",
    "to":          "pdf",
    "file_size":   204800,
    "result_size": 318422,
    "pages":       12,
    "duration_ms": 1840,
    "created_at":  "2026-05-17T08:00:00Z",
    "completed_at":"2026-05-17T08:00:02Z",
    "download_url":"https://cdn.moxu.com/result/tkd_a1b2c3d4.pdf",
    "expires_at":  "2026-05-17T10:00:02Z"
  }
}

下载文件 #

HTTP URLhttps://api.moxu.com/v1/download/{task_id}
HTTP MethodGET
权限要求有效 API Key

成功后返回 HTTP 302 重定向至 CDN 文件直链。转换结果文件保留 2 小时，过期后自动删除。

curl -L -o output.pdf \
  -H "Authorization: Bearer kd_live_your_api_key" \
  https://api.moxu.com/v1/download/tkd_a1b2c3d4

任务列表 #

HTTP URLhttps://api.moxu.com/v1/tasks
HTTP MethodGET
权限要求有效 API Key

查询参数

参数名类型说明
statusstring过滤状态：pending / processing / done / failed
pageinteger页码，从 1 开始，默认 1
per_pageinteger每页数量 1~100，默认 20

取消任务 #

HTTP URLhttps://api.moxu.com/v1/tasks/{task_id}
HTTP MethodDELETE
权限要求有效 API Key

仅 pending 或 processing 状态的任务可取消。

Webhook 回调 #

发起转换时传入 webhook 参数，任务完成后系统将向该 URL 发送 POST 请求。

事件类型

task.done转换成功，data 包含下载链接
task.failed转换失败，data 包含错误信息
task.cancelled任务已取消
{
  "event":    "task.done",
  "task_id":  "tkd_a1b2c3d4e5f6",
  "status":   "done",
  "data": {
    "download_url": "https://cdn.moxu.com/result/tkd_a1b2c3d4.pdf",
    "expires_at":   "2026-05-17T10:00:02Z",
    "pages":        12
  },
  "meta":     "your_custom_data",
  "timestamp": "2026-05-17T08:00:02Z"
}
⚠️
安全验证

回调请求头包含 X-Moxu-Signature，值为 HMAC-SHA256 对 payload 的签名，请务必在服务端验证签名，防止伪造请求。

支持格式列表 #

Moxu API 支持 50+ 种格式互转，以下为主要格式分类：

文档类

📄 PDF📝 DOCX 📝 DOC📝 RTF 📝 ODT📝 TXT 📝 EPUB📝 Markdown 📝 HTML 📝 OFD

表格类

📊 XLSX📊 XLS 📊 CSV📊 ODS 📊 TSV

演示文稿类

📑 PPTX📑 PPT 📑 ODP

图片类

🖼 PNG🖼 JPEG 🖼 WebP🖼 TIFF 🖼 BMP🖼 GIF 🖼 SVG

错误码参考 #

所有错误响应格式：{"code": 错误码, "message": "描述", "doc": "文档链接"}

错误码HTTP 状态说明
0200成功
1001401API Key 无效或已过期
1002403API Key 权限不足
1003429请求频率超出限制
2001400缺少必要参数 file 或 url
2002400不支持的格式组合
2003413文件大小超出限制（免费版最大 20MB）
2004400文件内容损坏或无法读取
2005400远程 URL 无法访问或下载失败
3001500转换引擎内部错误，请重试
3002500文件渲染失败（排版异常）
4001404任务不存在
4002410任务已过期（结果文件已删除）
4003409任务状态不允许此操作（如已完成无法取消）

套餐与配额 #

功能 免费版 基础版 专业版 企业版
月转换次数500 次5,000 次50,000 次按量
并发任务1310不限
单文件大小20 MB100 MB500 MB2 GB
结果保留时间2 小时24 小时72 小时7 天
Webhook 支持—✓✓✓
专属客服———✓
💳
按量计费

企业版支持按实际转换量计费，无月度上限。查看计费详情 →

JavaScript / Node.js #

npm install @moxu/sdk
const { MoxuClient } = require('@moxu/sdk');

const client = new MoxuClient({ apiKey: 'kd_live_your_key' });

const task = await client.convert.create({
  file: './document.docx',
  to: 'pdf'
});

const result = await client.convert.waitForDone(task.task_id);
await client.download(result.download_url, './output.pdf');

Python #

pip install moxu-sdk
from moxu import MoxuClient

client = MoxuClient(api_key="kd_live_your_key")
task = client.convert.create(file="document.docx", to="pdf")
result = client.convert.wait_for_done(task.task_id)
client.download(result.download_url, "output.pdf")

PHP #

composer require moxu/sdk
use Moxu\MoxuClient;

$client = new MoxuClient('kd_live_your_key');
$task = $client->convert->create([
  'file' => '/path/to/document.docx',
  'to'   => 'pdf'
]);
$result = $client->convert->waitForDone($task->task_id);
$client->download($result->download_url, 'output.pdf');

Java #

<dependency>
  <groupId>com.moxu</groupId>
  <artifactId>moxu-sdk</artifactId>
  <version>1.6.0</version>
</dependency>
MoxuClient client = new MoxuClient("kd_live_your_key");
ConvertTask task = client.convert().create(
  ConvertRequest.builder()
    .file(Paths.get("document.docx"))
    .to("pdf")
    .build()
);
ConvertResult result = client.convert().waitForDone(task.getTaskId());
client.download(result.getDownloadUrl(), "output.pdf");

Go #

go get github.com/moxu/moxu-go
client := moxu.NewClient("kd_live_your_key")
task, _ := client.Convert.Create(moxu.ConvertRequest{
  File: "document.docx",
  To:   "pdf",
})
result, _ := client.Convert.WaitForDone(task.TaskID)
client.Download(result.DownloadURL, "output.pdf")

更新日志 #

2026-05-17

新增支持 Markdown → PDF 直接转换

优化大文件分块上传，最大支持 2GB（企业版）

2026-04-01

新增Webhook 签名验证机制（HMAC-SHA256）

修复PPT 转 PNG 部分页面渲染失真问题

2026-03-10

新增Go / Java 官方 SDK

优化API 响应时间平均降低 30%

2026-01-15

破坏性v1.5 废弃 /convert/sync 同步接口，请迁移至异步任务接口

本文档是否有帮助？ 如有问题请 联系技术支持
← 上一篇功能特性 下一篇 →在线示例
本页目录