API 文档

Neptunium 投影管理系统 API 接口文档

API 概述

Neptunium API 提供了完整的投影文件管理功能，支持文件上传、下载、查看等操作。 API 采用 RESTful 设计，支持 JSON 格式的请求和响应。

基础信息

Base URL: https://your-domain.com
认证方式: API Key 或 JWT Token
请求格式: JSON
响应格式: JSON
支持的文件格式: .litematic, .schem, .schematic, .nbt, .structure
最大文件大小: 50MB

认证方式

1. API 密钥认证

在请求头中添加 API 密钥：

X-API-Key: npt_your_api_key_here

2. JWT Token 认证

在请求头中添加 Bearer Token：

Authorization: Bearer your_jwt_token

注意： 部分接口支持匿名访问，但建议使用认证以获得更好的服务质量和访问统计。

API 端点

GET/api/projection/{fileId}

获取投影文件信息

参数：

参数名	类型	说明
fileId	string	6位数文件ID
action	string	操作类型：info（默认）或 download

请求头：

头部名称	类型	说明
X-API-Key	string	API 密钥（可选）

请求示例：

curl -X GET "https://your-domain.com/api/projection/123456?action=info" \
  -H "X-API-Key: npt_your_api_key_here"

GET/api/projection/{fileId}?action=download

获取投影文件下载链接

参数：

参数名	类型	说明
fileId	string	6位数文件ID

请求头：

头部名称	类型	说明
X-API-Key	string	API 密钥（可选）

请求示例：

curl -X GET "https://your-domain.com/api/projection/123456?action=download" \
  -H "X-API-Key: npt_your_api_key_here"

POST/api/upload-file

上传投影文件

参数：

参数名	类型	说明
filename	string	文件名
fileSize	number	文件大小（字节）
fileType	string	文件类型（可选）
checksum	string	文件校验和（可选）

请求头：

头部名称	类型	说明
Authorization	string	Bearer token（可选，支持匿名上传）
Content-Type	string	application/json

请求示例：

curl -X POST "https://your-domain.com/api/upload-file" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "my_build.litematic",
    "fileSize": 1024000,
    "fileType": ".litematic"
  }'

响应示例

文件信息响应

{
  "message": "文件信息获取成功",
  "file": {
    "file_id": "123456",
    "filename": "my_build.litematic",
    "original_filename": "我的建筑.litematic",
    "file_size": 1024000,
    "file_type": ".litematic",
    "mime_type": "application/octet-stream",
    "download_count": 42,
    "is_public": true,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

下载链接响应

{
  "message": "下载链接生成成功",
  "downloadUrl": "https://storage.example.com/signed-url",
  "expiresIn": 3600,
  "file": {
    "file_id": "123456",
    "filename": "my_build.litematic",
    "file_size": 1024000
  }
}

上传响应

{
  "message": "文件上传准备完成",
  "fileId": "789012",
  "uploadUrl": "https://storage.example.com/upload-url",
  "expiresIn": 900,
  "file": {
    "id": "uuid-here",
    "file_id": "789012",
    "filename": "my_build.litematic",
    "file_size": 1024000,
    "storage_path": "projections/78/789012.litematic"
  }
}

错误代码

状态码	说明	可能原因
400	请求错误	参数缺失或格式错误
401	未授权	API 密钥无效或缺失
403	禁止访问	权限不足
404	资源不存在	文件ID不存在
429	请求过于频繁	超出速率限制
500	服务器错误	内部服务器错误

使用限制

• 文件大小限制： 单个文件最大 50MB
• 文件格式限制： 仅支持 .litematic, .schem, .schematic, .nbt, .structure 格式
• 速率限制： 默认每小时 1000 次请求（可通过 API 密钥配置）
• 存储时间： 文件默认永久存储，可设置过期时间
• 匿名上传： 支持匿名上传，但建议注册用户以获得更好的管理体验