目录作者 API

用于您的模组、整合包、地图和资源包的 mca_live_ 作者密钥：草稿、上传版本、页面、价格和销售统计。API 端点、密钥权限、请求示例、错误和限制。

更新于 2026年10月13日

作者在站点上对素材进行的所有操作，都可以通过您自己的脚本或构建流水线完成：创建草稿、上传新版本、编辑页面、修改价格、查看销售情况。为此，您需要一个作者密钥——形如 mca_live_… 的字符串。

密钥仅对您的素材有效：即您是作者的素材。即使知道地址，也无法用它操作他人的作品。

密钥

密钥在您的个人资料中的作者板块签发。为密钥命名并选择权限范围；密钥只显示一次——请将其保存到流水线的密钥管理中。如果丢失，请吊销并重新签发。您最多可以拥有十个有效密钥。修改密码或邮箱会吊销账户的所有密钥——之后请重新签发。

权限范围	授予的操作
`items:write`	创建草稿、确认作者身份、提交素材审核
`versions:write`	获取上传地址并登记版本
`page:write`	图片、页面草稿及提交审核
`pricing:write`	素材价格
`stats:read`	下载量、玩家数和销售情况

只给流水线它需要的东西：构建密钥通常只需 versions:write 和 stats:read。

所有端点都位于 https://api.millida.net/v2 下；密钥放在请求头中：

Authorization: Bearer mca_live_…

我的素材

GET /catalog/author-api/items

[
  {
    "slug": "my-pack",
    "type": "MODPACK",
    "title": "My modpack",
    "status": "PUBLISHED",
    "moderationStatus": "PUBLISHED",
    "pricing": "ONE_TIME",
    "priceKopecks": 49900,
    "versionsCount": 12,
    "downloads": 5310,
    "publicUrl": "/modpacks/my-pack"
  }
]

新素材

POST /catalog/author-api/items
{ "type": "MOD", "title": "My mod", "summary": "Briefly about the mod" }

素材会以草稿形式出现。地址（slug）取自名称；若地址已被占用，会返回 409 并建议一个可用地址。创建时的价格（pricing、priceKopecks）只有在密钥具有 pricing:write 权限范围时才能传入；否则响应为 403 MISSING_SCOPE。

新版本

1. 上传地址：

POST /catalog/author-api/items/my-pack/upload-url
{ "version": "1.4.0", "fileName": "my-pack-1.4.0.zip", "size": 734003200 }

{ "uploadUrl": "https://…", "storageKey": "catalog/packs/my-pack/…", "expiresIn": 3600 }

2. 上传文件，向 uploadUrl 发送 PUT 请求——直接上传到存储，不经过我们：

curl -X PUT --upload-file my-pack-1.4.0.zip "$UPLOAD_URL"

3. 登记版本：

POST /catalog/author-api/items/my-pack/versions
{
  "version": "1.4.0",
  "storageKey": "catalog/packs/my-pack/…",
  "gameVersions": ["1.20.1"],
  "loaders": ["fabric"],
  "loaderVersion": "0.16.0",
  "changelog": "New quests"
}

版本会进入自动审核，通过后对玩家可见。每次上传都是新文件：无法覆盖已发布的版本。

提交审核

新素材需经版主审核后才能进入目录。当素材至少有一个版本后，请确认作品属于您且您已选择许可证。这是一个单独的请求：提交审核不会替您完成这一步。

POST /catalog/author-api/items/my-pack/authorship

{ "ok": true }

然后提交素材：

POST /catalog/author-api/items/my-pack/submit

{ "ok": true, "status": "PENDING" }

未确认时，响应为 400“请确认整合包属于您且许可证由您选择”；没有版本时，响应为 400“请先上传整合包文件”。

页面

PUT /catalog/author-api/items/my-pack/page
{ "title": "My modpack", "summary": "…", "descriptionMd": "## What's inside\n…" }

这是草稿：在新页面通过审核之前，玩家看到的仍是旧页面。描述中的图片只能上传到我们这里；链接只能指向 Millida 页面。请先上传图标（iconUrl）、截图（gallery）和描述图片：

curl -H "Authorization: Bearer $MCA_KEY" -F "file=@icon.png" https://api.millida.net/v2/catalog/author-api/images

{ "url": "https://…/uploads/…/icon.png" }

支持 PNG、JPG、WebP 和 AVIF，最大 15 MB；不支持 GIF。上传需要 page:write 权限范围；响应中包含可放入页面的地址。提交审核：

POST /catalog/author-api/items/my-pack/page/submit

价格

PUT /catalog/author-api/items/my-pack/pricing
{ "pricing": "ONE_TIME", "priceKopecks": 49900 }

`pricing`	含义
`FREE`	免费
`ONE_TIME`	一次性购买，永久访问
`SUBSCRIPTION`	订阅，每月扣费一次

金额以戈比为单位。付费素材的最低价格为 300 ₽（30000），皮肤和披风为 50 ₽（5000）；最高为 100,000 ₽（10000000）。
平台从每笔销售中抽取 30%；其余进入您的 Millida 钱包。
销售所得可立即在 Millida 内消费，但提现需在购买后 7 天才能进行。
只有拥有访问权限的人才能下载付费素材的文件。作为作者，您始终拥有访问权限。

统计

GET /catalog/author-api/items/my-pack/stats

{
  "versions": [{ "version": "1.4.0", "downloads": 312, "reviewStatus": "APPROVED" }],
  "players": { "players": 1204, "playersRecent": 380, "days": [{ "day": "2026-09-24", "players": 41 }] },
  "sales": {
    "totalKopecks": 998000,
    "netKopecks": 698600,
    "count": 20,
    "refundedCount": 0,
    "holdDays": 7,
    "last30d": [{ "day": "2026-09-24", "count": 3, "netKopecks": 104790 }]
  }
}

一次性查看所有素材的销售情况：

GET /catalog/author-api/sales

错误

错误响应始终包含 message——可以直接展示给用户——通常还包含 code——便于在脚本中分支处理。

状态码	`code`	发生了什么
401	`INVALID_KEY`	密钥缺失、格式错误或未找到
401	`REVOKED`、`EXPIRED`	密钥已被吊销或已过期
401	`OWNER_UNAVAILABLE`	密钥所属账户已被封禁
403	`MISSING_SCOPE`	密钥缺少所需的权限范围；列表在 `scopes` 中
404	—	素材不存在或不属于您
400	`PRICE_TOO_LOW`、`PRICE_TOO_HIGH`、`INVALID_PRICING`	价格超出规则；边界值在 `minKopecks` 和 `maxKopecks` 中
409	`UNDER_REVIEW`	素材正在版主审核中——请在其回复后再上传新文件
429	—	请求过多，请稍后重试

限制

每个密钥每分钟 120 个请求。
新素材——每小时 10 个，上传地址和版本——各每小时 30 个，页面编辑——每小时 120 次，图片——每小时 60 张，价格修改——每小时 60 次。