API 开发文档 - KoiDoc 文档转换接口

快速入门

KoiDoc API 基于 REST 风格设计，所有请求和响应均使用 JSON 格式。API 基础地址：

BASE URL

https://api.koidoc.com/v1

以下是一个最简单的 Word 转 PDF 示例：

cURL

curl -X POST https://api.koidoc.com/v1/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.docx" \
  -F "to=pdf"

💡 提示 使用前请先在用户中心申请 API Key，免费套餐每月可调用 500 次。

鉴权方式

所有 API 请求需要在 HTTP Header 中携带 API Key 进行身份验证：

Header

Authorization: Bearer YOUR_API_KEY

API Key 可在用户中心创建和管理。请妥善保管，不要暴露在前端代码中。

⚠️ 安全提示 API Key 具有账户完整权限，请勿提交至公开代码仓库或暴露在客户端。

转换接口

POST /convert

上传文件并触发格式转换。请求格式为 multipart/form-data。

请求参数

参数	类型	必填	说明
`file`	File	必填	上传的原始文件，最大 50MB
`to`	string	必填	目标格式，如 `pdf`、`docx`、`png`
`from`	string	可选	源格式，不填时自动检测
`quality`	integer	可选	图片质量 1-100，默认 85（仅图片格式有效）
`webhook`	string	可选	转换完成后回调的 URL

响应示例

JSON

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "tkd_a1b2c3d4e5f6",
    "status": "processing",
    "created_at": "2026-04-26T10:00:00Z"
  }
}

查询任务状态

GET /task/{task_id}

通过任务 ID 查询转换进度与结果。

cURL

curl https://api.koidoc.com/v1/task/tkd_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY"

响应

{
  "code": 0,
  "data": {
    "task_id": "tkd_a1b2c3d4e5f6",
    "status": "done",  // processing | done | failed
    "download_url": "https://cdn.koidoc.com/result/xxx.pdf",
    "expires_at": "2026-04-27T10:00:00Z"
  }
}

错误码

code	HTTP 状态	含义
`0`	200	成功
`1001`	401	API Key 无效或已过期
`1002`	403	调用次数超出配额
`1003`	400	文件格式不支持
`1004`	413	文件超过大小限制
`1005`	404	任务不存在或已过期
`5000`	500	服务器内部错误，请稍后重试

SDK 示例

JavaScript / Node.js

JS

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

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

const res = await axios.post(
  'https://api.koidoc.com/v1/convert',
  form,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

Python

import requests

with open('document.docx', 'rb') as f:
    res = requests.post(
        'https://api.koidoc.com/v1/convert',
        headers={'Authorization': f'Bearer {API_KEY}'},
        files={'file': f},
        data={'to': 'pdf'}
    )
print(res.json())