API接口

iLoveOFD API 提供在线文件转换、文件上传、任务管理、账户余额及账单查询等接口。

通过 API，开发者可以将文件上传至百度云 BOS，创建文件转换任务，并通过任务状态及任务详情接口获取转换结果。

一、API 调用流程

一次完整的文件转换流程如下：

1. 登录 API 账户
        ↓
2. 获取 Token
        ↓
3. 获取百度云 BOS 临时授权信息
        ↓
4. 将文件上传至 BOS
        ↓
5. 创建转换任务
        ↓
6. 查询任务状态
        ↓
7. 获取转换结果

接口列表

接口 方法 说明
/api/login POST 登录并获取 Token
/api/auth GET 获取百度云 BOS 临时授权信息
BOS 上传地址 PUT 上传待处理文件
/api/create POST 创建文件转换任务
/api/status/{requestId} GET 查询任务处理状态
/api/detail/{requestId} GET 获取转换后的文件信息
/api/balance GET 查询账户余额
/api/billing/{year}/{month} GET 查询月度账单
/api/billing/{year}/{month}/{day} GET 查询指定日期账单
/api/order/list GET 查询充值记录

二、认证说明

2.1 Token 认证

除登录接口外，其他 API 接口均需要在 HTTP Header 中携带 Token。

token: {your_token}

例如：

GET /api/balance HTTP/1.1
Host: api.iloveofd.cn
token: eyJhbGciOiJIUzI1NiJ9...

Token 使用建议

建议开发者使用中控服务器统一获取和刷新 Token。

其他业务服务器使用的 Token 应从中控服务器获取，不建议多个业务服务器同时自行刷新 Token，避免并发刷新导致 Token 被覆盖，从而影响正常 API 调用。

Token 默认有效期为 30 天，请在 Token 失效前及时重新获取。

Token 属于敏感凭证，请妥善保管，不得将 Token 暴露在：

  • 前端代码
  • 浏览器页面
  • JavaScript 源码
  • 日志
  • Git 仓库
  • 公共代码仓库
  • 其他公开环境

三、登录并获取 Token

3.1 接口说明

使用 API 用户名和密码进行登录，登录成功后返回身份认证 Token。

如果没有 API 调用账号，请联系我们申请开通。

📧 邮箱：iloveofd@163.com

微信扫码，公众号后台联系：

iLoveOFD

3.2 请求信息

项目 内容
请求 URL https://api.iloveofd.cn/api/login
请求方式 POST
Content-Type application/json
是否需要 Token 否

###3.3 请求参数

参数名 类型 必填 说明
username String 是 API 用户名称
password String 是 API 用户密码

3.4 请求示例

{
  "username": "your_username",
  "password": "your_password"
}

3.5 成功响应

{
  "code": 200,
  "token": "your_token"
}

3.6 响应参数

参数名 类型 说明
code Number 状态码
token String 身份认证 Token
msg String 请求失败时的错误描述

3.7 失败响应

{
  "code": 401,
  "msg": "无权访问"
}

3.8 状态码

Code 说明
200 登录成功
400 请求参数错误
401 无权访问

四、获取百度云 BOS 临时授权信息

4.1 接口说明

获取用于上传文件的百度云 BOS 临时访问凭证。

获取到临时授权信息后，开发者可以直接将文件上传至指定 BOS Bucket。

4.2 请求信息

项目 内容
请求 URL https://api.iloveofd.cn/api/auth
请求方式 GET
是否需要 Token 是

4.3 请求 Header

Header 类型 必填 说明
token String 是 登录接口返回的身份认证 Token

示例：

token: {your_token}

4.4 响应参数

参数名 类型 说明
code Number 状态码
accessKeyId String BOS 临时访问 Key
secretAccessKey String BOS 临时访问 Secret
securityToken String BOS 临时安全 Token
bucket String BOS Bucket 名称
endpoint String BOS 上传地址
durationSeconds Number 临时授权有效时间，单位：秒
expiration String 临时授权过期时间
msg String 请求失败时的错误描述

4.5 成功响应示例

{
  "code": 200,
  "accessKeyId": "your_access_key_id",
  "secretAccessKey": "your_secret_access_key",
  "securityToken": "your_security_token",
  "bucket": "iloveofd",
  "endpoint": "https://iloveofd.gz.bcebos.com",
  "durationSeconds": 1200,
  "expiration": "2026-08-23 22:05:36"
}

accessKeyId、secretAccessKey 和 securityToken 均为临时授权信息，仅用于文件上传，请勿保存为长期凭证或公开。

4.6 状态码

Code 说明
200 获取成功
400 请求参数错误
401 无权访问
402 Token 已失效或未登录

五、上传文件至百度云 BOS

5.1 接口说明

获取 BOS 临时授权信息后，将待转换文件直接上传至指定 Bucket。

BOS 文件上传的具体实现方式请参考百度智能云 BOS 官方文档。

5.2 上传信息

项目 内容
上传方式 PUT
Bucket iloveofd
Endpoint 以 /api/auth 返回的 endpoint 为准

文件 Key

使用 UUID 作为文件 Key，避免文件名称重复。

例如：

2642efca-cd38-46ec-bf3c-d1a2af8dea84.caj

文件上传成功后，在创建任务时将该 Key 作为 fileKey 传入。

5.3 上传流程

调用 /api/auth
      ↓
获取 BOS 临时授权信息
      ↓
生成 UUID 文件 Key
      ↓
PUT 上传文件
      ↓
上传成功
      ↓
调用 /api/create 创建转换任务

注意：文件必须先成功上传至 BOS，再调用创建任务接口。

六、创建转换任务

6.1 接口说明

创建文件转换任务。

文件上传成功后，调用该接口创建转换任务，接口返回 requestId 和 uuid。

其中：

  • requestId：用于后续查询任务状态和任务详情
  • uuid：任务唯一标识

6.2 请求信息

项目 内容
请求 URL https://api.iloveofd.cn/api/create
请求方式 POST
Content-Type application/json
是否需要 Token 是

6.3 请求 Header

参数名 类型 必填 说明
token String 是 登录接口返回的身份认证 Token

6.4 Body 参数

参数名 类型 必填 说明
taskType String 是 任务类型，例如 AudioInstrumentalSeparator
strPairs Object / Array 否 转换任务参数，不同任务类型参数不同
ossPendingFiles Array 是 待转换文件列表

6.5 strPairs 参数

6.5.1 音乐伴奏提取功能：

参数名 类型 必填 说明
outputFormat String 是 输出格式，默认输出wav格式，另外支持 wav、mp3、png 、webp、svg、ico icns 、tif、tiff、bmp、avif
separateTaskType String 是 音乐分离类型，伴奏提取使用 instrumental

支持的输出格式：

wav
mp3
flac
ogg
opus
m4a
aiff
ac3

默认输出格式为 wav。

6.5.2 图片格式转换功能

参数名 类型 必填 说明
tf String 是 输出格式，例如 jpg、jpeg、png 、webp、svg、ico icns 、tif、tiff、bmp、avif

支持的输出格式：

jpg
jpeg
png
webp
svg
ico
icns
tif
tiff
bmp
avif

6.6 ossPendingFiles 参数

参数名 类型 必填 说明
fileKey String 是 文件在 BOS 中的 Key
fileName String 是 原始文件名称，生成结果文件时会参考使用该名称
fileSize Number 否 文件大小，单位：Byte

6.7 请求示例

音乐伴奏提取

{
  "taskType": "AudioInstrumentalSeparator",
  "strPairs": {
    "outputFormat": "wav",
    "separateTaskType": "instrumental"
  },
  "ossPendingFiles": [
    {
      "fileKey": "9d4e76ef-fa37-462b-836d-9069b87b8247.wav",
      "fileName": "山茶花开伴奏.wav"
    }
  ]
}

6.8 成功响应

{
  "code": 200,
  "requestId": "c8d157af99e64296bd8e027060691e83",
  "uuid": "5bc3aa30e04c47819a41241acdc10a42"
}

6.9 响应参数

参数名 类型 说明
code Number 状态码
requestId String 任务请求 ID，用于查询任务状态和任务详情
uuid String 任务唯一标识
msg String 请求失败时的错误描述

6.10 状态码

Code 说明
200 创建任务成功
400 请求参数错误
401 无权访问
403 账户余额不足
404 未找到客户余额信息
405 未发现需要处理的文件
406 单个任务超过文件数量限制
407 文件名称格式错误，必须使用 UUID 格式
408 当前账户未开通该功能
409 文件不存在，请检查文件是否上传成功
410 参数错误

七、查询任务状态

7.1 接口说明

根据创建任务时返回的 requestId 查询任务当前处理状态。

建议客户端采用轮询方式查询任务状态。

7.2 请求信息

项目 内容
请求 URL https://api.iloveofd.cn/api/status/{requestId}
请求方式 GET
是否需要 Token 是

例如：

https://api.iloveofd.cn/api/status/c8d157af99e64296bd8e027060691e83

7.3 Path 参数

参数名 类型 必填 说明
requestId String 是 创建任务时返回的请求 ID

7.4 请求 Header

token: {your_token}

7.5 响应参数

参数名 类型 说明
code Number 状态码
taskStatus Object 任务状态信息
taskStatus.status String 当前任务状态
taskStatus.uuid String 任务唯一标识
taskStatus.progress Number 任务处理进度，未开始时可能为 null，开始后以数字显示进度，50，表示50%进度
taskStatus.order Number 任务排序信息，无数据时可能为 null
msg String 请求失败时的错误描述

7.6 任务状态

状态 说明
NOT_STARTED 等待处理
PROCESSING 转换中
COMPLETED 转换完成
FAILED 转换失败

7.7 成功响应

{
  "code": 200,
  "taskStatus": {
    "status": "PROCESSING",
    "uuid": "5bc3aa30e04c47819a41241acdc10a42",
    "progress": 50,
    "order": null
  }
}

7.8 状态码

Code 说明
200 查询成功
401 无权访问
402 Token 已失效或未登录

八、获取转换后的文件信息

8.1 接口说明

任务转换完成后，根据 requestId 获取转换后的文件信息及临时下载地址。

建议先通过任务状态接口确认任务状态为 COMPLETED，再调用本接口。

8.2 请求信息

项目 内容
请求 URL https://api.iloveofd.cn/api/detail/{requestId}
请求方式 GET
是否需要 Token 是

例如：

https://api.iloveofd.cn/api/detail/c8d157af99e64296bd8e027060691e83

8.3 Path 参数

参数名 类型 必填 说明
requestId String 是 创建任务时返回的请求 ID

8.4 请求 Header

token: {your_token}

8.5 响应参数

参数名 类型 说明
code Number 状态码
task Object 转换任务信息
task.uuid String 任务唯一标识
task.createTime String 创建时间，Unix 时间戳，单位：毫秒
task.finishTime String 完成时间，Unix 时间戳，单位：毫秒
task.taskType String 任务类型，例如 OFD2PDF
task.userId Number 创建任务的用户 ID
task.taskStatus String 当前任务状态
task.ossProcessedFiles Array 转换完成后的文件列表

ossProcessedFiles 参数

参数名 类型 说明
sort Number 文件顺序，从 0 开始
fileSize Number 文件大小，单位：Byte
fileName String 转换后的文件名称
fileUrl String 转换后文件的临时下载地址
fileKey String 转换后文件在 BOS 中的 Key

8.6 成功响应

{
  "code": 200,
  "task": {
    "uuid": "26ef1de38d864a2ab3f5627e963740ac",
    "createTime": "1787497334590",
    "finishTime": "1787497358615",
    "taskType": "OFD2PDF",
    "userId": 67706,
    "taskStatus": "COMPLETED",
    "ossProcessedFiles": [
      {
        "sort": 0,
        "fileSize": 6828704,
        "fileName": "result.pdf",
        "fileUrl": "https://download.iloveofd.cn/...",
        "fileKey": "/2026/08/23/3248009ca2f342ae9e9c8de5fd9171db/result.pdf"
      }
    ]
  }
}

fileUrl 为临时下载地址，请在有效期内完成文件下载。

8.7 状态码

Code 说明
200 查询成功
401 无权访问
402 Token 已失效或未登录

九、查询账户余额

9.1 接口说明

查询当前 API 账户的企业名称、账户余额及余额更新时间。

9.2 请求信息

项目 内容
请求 URL https://api.iloveofd.cn/api/balance
请求方式 GET
是否需要 Token 是

9.3 请求 Header

token: {your_token}

9.4 响应参数

参数名 类型 说明
code Number 状态码
msg String 请求结果描述
data Object 账户信息
data.companyName String 企业名称
data.balance Number 当前账户余额，单位：元
data.balanceUpdateTime String 余额最后更新时间，格式：yyyy-MM-dd HH:mm:ss

9.5 成功响应

{
  "msg": "查询成功",
  "code": 200,
  "data": {
    "companyName": "蓬安卜口",
    "balance": 90.74,
    "balanceUpdateTime": "2026-08-23 15:37:30"
  }
}

9.6 状态码

Code 说明
200 查询成功
401 无权访问
402 Token 已失效或未登录
404 未找到客户余额信息

十、查询计费列表

10.1 接口说明

查询 API 账户的文件处理费用、流量费用及账单信息。

支持按月份和具体日期查询。具体日期查询：每日凌晨12.05分更新前一天的数据。

10.2 请求信息

按月查询

GET https://api.iloveofd.cn/api/billing/{year}/{month}

按日查询

GET https://api.iloveofd.cn/api/billing/{year}/{month}/{day}

请求方式：

GET

10.3 Path 参数

参数名 类型 必填 说明
year Integer 是 查询年份，例如 2026
month Integer 是 查询月份，取值范围 1-12
day Integer 否 查询日期，取值范围 1-31；传入后查询指定日期

10.4 请求 Header

token: {your_token}

10.5 响应参数

参数名 类型 说明
code Number 状态码
msg String 请求结果描述
data Array 账单列表
data[].id Number 账单记录 ID
data[].adminId Number 管理员 ID
data[].companyId Number 企业 ID
data[].companyName String 企业名称
data[].totalFileSize Number 文件总大小，单位：Byte
data[].trafficFee Number 流量费用，单位：元
data[].processFee Number 文件处理费用，单位：元
data[].totalFee Number 账单总费用，单位：元
data[].billingDate String 账单日期
data[].createTime String 账单创建时间
data[].updateTime String 账单最后更新时间
data[].status Number 账单状态

10.6 成功响应

{
  "msg": "查询成功",
  "code": 200,
  "data": [
    {
      "id": 1,
      "adminId": null,
      "companyId": null,
      "companyName": "penganbukou",
      "totalFileSize": 0,
      "trafficFee": 0,
      "processFee": 0,
      "totalFee": 0,
      "billingDate": "2026-08-21T16:00:00.000+00:00",
      "createTime": "2026-08-22T02:08:53.000+00:00",
      "updateTime": "2026-08-22T02:49:37.000+00:00",
      "status": 1
    }
  ]
}

10.7 状态码

Code 说明
200 查询成功
401 无权访问
402 Token 已失效或未登录
404 未找到相关账户信息

十一、查询充值记录

11.1 接口说明

查询当前 API 账户的充值订单记录。

11.2 请求信息

项目 内容
请求 URL https://api.iloveofd.cn/api/order/list
请求方式 GET
是否需要 Token 是

#3# 11.3 请求 Header

token: {your_token}

11.4 响应参数

参数名 类型 说明
code Number 状态码
msg String 请求结果描述
data Array 充值订单列表
data[].orderNo String 订单号
data[].companyName String 企业名称
data[].amount Number 充值金额，单位：元
data[].orderUrl String 订单支付地址
data[].invoice Number 发票状态
data[].createTime String 订单创建时间
data[].status Number 订单状态

11.5 成功响应

{
  "msg": "查询成功",
  "code": 200,
  "data": [
    {
      "orderNo": "078761c692db448c947d000ad441604d",
      "companyName": "蓬安卜口软件开发技术咨询店",
      "amount": 100,
      "orderUrl": "https://iloveofd.cn/open/pay/1/...",
      "invoice": 0,
      "createTime": "2026-08-23 20:47:27",
      "status": 1
    }
  ]
}

11.6 状态码

Code 说明
200 查询成功
401 无权访问
402 Token 已失效或未登录
404 未找到相关账户信息

十二、错误处理

所有 API 接口均通过 code 表示请求结果。

建议开发者优先根据 code 判断接口是否调用成功，再根据 msg 获取具体错误信息。

通用状态码：

Code 说明
200 请求成功
400 请求参数错误
401 无权访问
402 Token 已失效或未登录
403 账户余额不足
404 相关资源或账户信息不存在

不同业务接口可能存在其他业务状态码，具体以对应接口的状态码说明为准。

十三、完整调用示例

以文件转换为例，完整调用流程如下：

第一步：登录

POST https://api.iloveofd.cn/api/login
Content-Type: application/json

获取：

{
  "code": 200,
  "token": "your_token"
}

第二步：获取 BOS 临时授权

GET https://api.iloveofd.cn/api/auth
token: your_token

获取：

accessKeyId
secretAccessKey
securityToken
bucket
endpoint

第三步：上传文件

使用第二步返回的 BOS 临时授权信息，将文件通过 PUT 上传至 BOS。

同时使用 UUID 生成文件 Key，例如：

2642efca-cd38-46ec-bf3c-d1a2af8dea84.caj

第四步：创建任务

POST https://api.iloveofd.cn/api/create
Content-Type: application/json
token: your_token

获取：

{
  "code": 200,
  "requestId": "c8d157af99e64296bd8e027060691e83",
  "uuid": "5bc3aa30e04c47819a41241acdc10a42"
}

第五步：查询任务状态

GET https://api.iloveofd.cn/api/status/c8d157af99e64296bd8e027060691e83
token: your_token

当：

{
  "taskStatus": {
    "status": "COMPLETED"
  }
}

表示任务处理完成。

第六步：获取转换结果

GET https://api.iloveofd.cn/api/detail/c8d157af99e64296bd8e027060691e83
token: your_token

从：

task.ossProcessedFiles[].fileUrl

获取转换后的文件下载地址。

十四、注意事项

1. Token 安全

Token 属于身份认证凭证，请勿在前端、网页源码、Git 仓库、日志等公开环境中保存。

2. BOS 临时授权

accessKeyId、secretAccessKey 和 securityToken 均为临时授权凭证，仅用于文件上传。

3. 文件 Key

上传文件时使用 UUID 作为文件 Key，避免因文件名称重复导致文件覆盖或任务识别异常。

4. 创建任务

文件必须先成功上传至 BOS，再调用 /api/create 创建转换任务。

5. 任务查询

创建任务成功后，通过 requestId 查询任务状态。

建议采用合理的轮询间隔，不要高频请求任务状态接口。

6. 下载地址

转换完成后，fileUrl 为临时下载地址，应及时下载文件。

7. 账户余额

API 为计费服务，请确保账户余额充足，否则创建任务可能返回余额不足。

十五、联系我们

如需申请 API 接口账号、开通更多转换功能或了解 API 计费方式，请联系我们。

📧 邮箱：iloveofd@163.com

iLoveOFD

📧 联系方式：iloveofd@163.com

文档编辑日期：2026/08/24