开放API

更新时间：2026-08-02

接口总览

Method

URI

用途

POST

/openApi/user/fetchBasicInfo.json

获取当前API用户的基本信息

POST

/openApi/user/authenticate.json

获取本站对用户身份挑战值的RSA签名

POST

/openApi/torrent/fetchTorrentIdWithPiecesHash.json

批量根据piecesHash查询种子ID

POST

/openApi/torrent/fetchOpenTorrentList.json

分页查询公开种子列表

POST

/openApi/torrent/generateDownloadKey.json

生成临时种子下载凭证

认证方式

开放API接口URI均以 /openApi/ 开头。请求Header中的 Authorization 应直接填写API AuthKey，不要添加 Bearer 前缀。

API AuthKey需要在个人详情页创建，有效期为180天，每个用户最多同时保留3个有效AuthKey。用户可以在个人详情页删除AuthKey，删除后立即失效。请勿在URL、日志或公开代码中暴露AuthKey。

调用示例：

// node javascript
fetch("https://www.yemapt.org/openApi/xxxxxxxxx", {
  "headers": {
    "Authorization": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
});

# bash
curl 'https://www.yemapt.org/openApi/xxxxxxxxx' \
 -H 'Authorization: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

Cookie中的登录auth不能用于开放API。如果在 Authorization 中传入Cookie auth，接口会返回：

{
    "success": false,
    "showType": 2,
    "errorCode": 403,
    "errorMessage": "need api auth"
}

通用响应

除下载种子文件的接口外，开放API均返回 ResultDTO 格式的JSON。业务调用是否成功应以 success 为准，不要只依赖HTTP状态码。

成功响应：

{
    "success": true,
    "showType": 0,
    "data": {}
}

失败响应：

{
    "success": false,
    "showType": 2,
    "errorCode": 2401,
    "errorMessage": "参数异常"
}

常见错误码：

errorCode

说明

400

未提供AuthKey，或AuthKey格式异常、签名无效、已经过期

402

当前用户没有访问相关资源的权限

403

使用的不是API AuthKey，或API AuthKey已被删除

1402

当前接口要求用户先完成邮箱验证

2401

请求参数或业务校验不通过，具体原因见 errorMessage

500

系统内部异常；反馈问题时请同时提供响应中的traceId信息

1. 用户

1.1 获取用户基本信息

POST /openApi/user/fetchBasicInfo.json

原 GET /openApi/user/fetchBasicInfo.json 已废弃，仅用于兼容已有对接。

响应结果

{
    "success": true,
    "showType": 0,
    "data": {
        "id": 10,
        "name": "abcde",
        "avatar": "https://img.yemapt.org/avatar/97/97d77c955bf14b0c8807020755ebd8a0.png",
        "bonus": 1000000,
        "level": 7,
        "status": "enable",
        "invitedNum": 100,
        "availableInviteNum": 100,
        "registerTime": "2024-05-01T00:00:00.000+00:00",
        "promotionUploadSize": 1000000,
        "promotionDownloadSize": 1000000,
        "admin": false
    }
}

主要字段说明：

字段

类型

说明

id

Long

用户ID

name

String

用户名

avatar

String

用户上传头像的完整URL，或系统生成的头像标识

bonus

Long

用户积分

level

Integer

用户等级

status

String

用户状态

invitedNum

Long

已邀请用户数量

availableInviteNum

Long

当前可用邀请数量

registerTime

Date

注册时间，ISO 8601格式

promotionUploadSize

Long

促销上传量，单位为字节

promotionDownloadSize

Long

促销下载量，单位为字节

admin

Boolean

是否为管理员

备注：用户上传头像后，avatar直接返回以 https://img.yemapt.org/avatar/ 开头的完整URL，无需再拼接域名；如果返回的是32位随机字符串，则需要使用 Multiavatar 转换。该组件提供JavaScript、PHP和Python工具包。

1.2 校验是否为本站用户

用于第三方系统校验用户提交的auth是否正常，以及获取对应的uid，此功能采用RSA签名技术。

当前使用的publicKey：

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAm6OpYYWpF5Js8SWtuAXGZ1iWGsADHSDhdkz9wDQYuvRB3SW2xGSQpwYB7B7Bn6ZfoXtxhMm2v4JzwTe3qZioWmwgyweCyv7FIjvsdYIhAHMj7v7jI7zq0Xn9F6CjBMM0AWtCmhhH/eFNxICiCucVGqa6Z0hf5OcAWefPHIOdtMbWp+4fqkjWc7EuEjfqFr2eDy9kHqZWFpuByQa9jiF4v9HzLfoO/UwqBheYkNSLgoTRQ6sSF1bHlDC8yq3l4d/6fsQ7mZPJzWBf2vlohmOVpjy6s4Z+qtNpWsJhrLW9au49+1eYadKpNLR10izG5boKn+z9i5P/tRQ8WNkZELN2OwIDAQAB

POST /openApi/user/authenticate.json

Header Content-Type: application/json

Body

{
    "publicKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "randomContent": "12345678123456781234567812345678"
}

备注：

publicKey务必使用当前Wiki中展示的Key。公钥可能轮换，接口返回“publicKey已失效”时应重新读取本文档中的最新值。
randomContent必须为32个字符。建议每次请求都生成新的随机值，例如使用UUID并移除其中的 -。
验证方应同时校验RSA签名、返回的 userId 和本次提交的 randomContent，并避免重复接受相同的随机值。

响应结果

{
    "success": true,
    "showType": 0,
    "data": {
        "userId": 100,
        "signType": "rsa-sha256",
        "publicKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "signature": "OOOOOOOOOOOOOOOOOOOOOOOOOOOO"
    }
}

备注：

签名数据使用UTF-8编码，格式为“用户ID、制表符、randomContent”，即：

String data = "{userId}\t{randomContent}"
                .replace("userId","100")
                .replace("randomContent","12345678123456781234567812345678");

示例代码：

python：

from base64 import b64decode
import rsa

data = "100\t12345678123456781234567812345678"
publicKey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXX"
signature = "OOOOOOOOOOOOOOOOOOOOOOOOOOOO"

PUB = '''
-----BEGIN PUBLIC KEY-----
{publicKey}
-----END PUBLIC KEY-----
'''.format(publicKey=publicKey)

try:
    signType = rsa.verify(data.encode(), b64decode(signature), rsa.PublicKey.load_pkcs1_openssl_pem(PUB))
    print(signType)
except rsa.pkcs1.VerificationError:
    print("verification failed")

java:

import java.security.*;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;


public static boolean rsaValidate(String publicKeyStr, String sign, String data) throws NoSuchAlgorithmException, InvalidKeySpecException, InvalidKeyException, SignatureException {
    PublicKey publicKey = KeyFactory.getInstance("RSA").generatePublic(
            new X509EncodedKeySpec(Base64.getDecoder().decode(publicKeyStr)));

    Signature verify = Signature.getInstance("SHA256withRSA");
    verify.initVerify(publicKey);
    verify.update(data.getBytes());
    return verify.verify(Base64.getDecoder().decode(sign));
}

2. 种子

2.1 根据piecesHash获取种子id

POST /openApi/torrent/fetchTorrentIdWithPiecesHash.json

Header Content-Type: application/json

Body

{
    "piecesHashList": [
        "e9f3f5dd32abasdfghfea4d43d32559cf0309764",
        "e9f3f5dd32ab123456fea4d43d32559cf0309764"
    ]
}

参数说明：

piecesHashList数组长度不能超过100。
空数组会返回空Map，不会返回参数错误。
piecesHash通常是对种子 info.pieces 内容计算得到的40位SHA-1十六进制字符串；无匹配种子的Hash不会出现在响应结果中。

响应结果

{
    "success": true,
    "showType": 0,
    "data": {
        "e9f3f5dd32abasdfghfea4d43d32559cf0309764": 100
    }
}

2.2 查询公开种子列表

此接口与站内页面使用的 /api/torrent/fetchOpenTorrentList 查询能力一致，供第三方系统分页查询已发布的公开种子。

POST /openApi/torrent/fetchOpenTorrentList.json

Header Content-Type: application/json

Body

{
    "keyword": "关键词",
    "categoryId": 1,
    "downloadPromotionType": "free",
    "pageParam": {
        "current": 1,
        "pageSize": 20
    },
    "sorter": {
        "field": "listingTime",
        "order": "descend"
    }
}

请求参数说明：

keyword：可选，同时匹配种子标题和副标题，长度必须小于128个字符。
categoryId：可选，种子类目ID；查询受限类目时，API auth对应的用户必须拥有相应权限。
uploadPromotionType：可选，上传促销类型，可用值为 none、one_half、double_upload。
downloadPromotionType：可选，下载促销类型，可用值为 none、half、free。
pageParam：必填；current按页码从1开始，最大为1000；pageSize必须大于0且最大为40。
sorter：可选；order可用值为 ascend、descend。不传时按照置顶状态和发布时间倒序排列。

sorter.field支持以下值：

id、torrentSize、fileSize、fileNum
torrentCommentNum、torrentViewNum、torrentDownloadNum
leechNum、seedNum、completedNum、downloadUserNum
status、listingTime、gmtCreate、gmtModified
uploadPromotionEndTime、downloadPromotionEndTime、reportNum

响应结果

以下响应仅展示主要字段。实际响应还可能包含当前用户信息、种子媒体属性以及以后新增的兼容字段，对接系统应忽略不认识的字段，并允许可选字段为 null 或不返回。

{
    "success": true,
    "showType": 0,
    "data": [
        {
            "id": 100,
            "showName": "种子标题",
            "shortDesc": "种子副标题",
            "categoryId": 1,
            "categoryName": "电影",
            "fileSize": 1073741824,
            "seedNum": 10,
            "leechNum": 2,
            "uploadPromotion": "none",
            "downloadPromotion": "free",
            "listingTime": "2026-08-02T08:00:00.000+00:00",
            "collect": false
        }
    ]
}

主要字段说明：

字段

类型

说明

id

Long

种子ID

showName

String

种子标题

shortDesc

String

种子副标题

categoryId

Long

类目ID

categoryKey

String

包含父子层级的类目标识

categoryName

String

类目名称

categoryAvatar

String

类目图标

picture

String

种子预览图路径

fileSize

Long

种子内容总大小，单位为字节

seedNum

Integer

当前做种数量

leechNum

Integer

当前下载数量

listingTime

Date

发布时间，ISO 8601格式；具体时区以响应中的偏移量为准

isTopping

String

是否置顶，枚举值为 y、n

uploadPromotion

String

上传促销类型

uploadPromotionEndTime

Date

上传促销结束时间

downloadPromotion

String

下载促销类型

downloadPromotionEndTime

Date

下载促销结束时间

hrPunishEnable

Boolean

是否启用HR考察

userInfo

Object

发种用户的展示信息；匿名发布时不会暴露真实身份

collect

Boolean

当前API用户是否已收藏

userTorrentInfo

Object

当前API用户对该种子的下载量及做种、下载状态

接口只返回状态为 enable 的种子，目前不提供配套的总数接口。无符合条件的数据或分页参数超出限制时，data返回空数组。对接方可以逐页请求；当返回数量小于 pageSize 时，即可认为已经到达当次查询结果的最后一页。分页期间种子数据可能发生变化，对接方应使用种子 id 去重。

2.3 生成种子下载凭证

第三方系统不能直接使用开放API的 Authorization 下载种子文件，需要先为指定种子生成临时下载凭证，再使用凭证下载 .torrent 文件。

2.3.1 生成凭证

POST /openApi/torrent/generateDownloadKey.json?id={torrentId}

请求参数说明：

id：必填，需要下载的种子ID。
请求Header中必须携带开放API的 Authorization。

请求示例：

curl -X POST 'https://www.yemapt.org/openApi/torrent/generateDownloadKey.json?id=100' \
 -H 'Authorization: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

响应结果

{
    "success": true,
    "showType": 0,
    "data": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX="
}

data即种子下载凭证，有效期为30分钟。生成凭证时会校验当前API用户是否拥有该种子的下载权限；种子不存在或没有下载权限时，接口返回失败。

原 GET /openApi/torrent/generateDownloadKey.json 和 GET /openApi/torrent/generateDownloadKey 均已废弃，仅用于兼容已有对接。新接入系统必须使用带 .json 后缀的POST接口。

2.3.2 使用凭证下载种子

GET /api/torrent/download1?token={downloadKey}

此下载接口不需要携带 Authorization。下载凭证是Base64字符串，可能包含 +、/、= 等字符，作为查询参数使用前必须进行URL编码。

JavaScript示例：

const downloadUrl = "https://www.yemapt.org/api/torrent/download1?token="
    + encodeURIComponent(downloadKey);
window.location.href = downloadUrl;

cURL示例：

curl --get 'https://www.yemapt.org/api/torrent/download1' \
 --data-urlencode 'token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=' \
 --output download.torrent

下载成功时，接口返回 application/x-bittorrent 类型的种子文件，而不是JSON。凭证已过期、内容异常、用户被禁用、用户passkey发生变化或下载权限发生变化时，接口返回JSON格式的错误信息。

下载凭证与生成凭证的用户及种子绑定。下载得到的种子文件包含该用户的个人Tracker信息，请勿共享凭证或下载后的种子文件。

变更记录

日期

变更内容

2026-08-02

增加公开种子列表和种子下载凭证接口说明；新增 /openApi/torrent/generateDownloadKey.json；将 fetchBasicInfo 和 generateDownloadKey.json 调整为POST接口，原GET接口标记为废弃；原无 .json 后缀的下载凭证接口标记为废弃；补充认证、通用响应、错误码、字段与分页规则

最后更新于 8天前