API 参考

Base URL：http://<你的服务器IP或域名>:8080

认证

所有业务接口需在请求头中携带：

Header	值	必填
`X-API-Key`	你的 API 密钥	✅

安全提醒

不要把 API Key 写在前端代码中。应放在后端服务或 CI 流水线中使用。

异步任务流程

text

POST compress   → 返回 task_id
GET tasks/{id}  → pending / processing / completed / failed
GET download    → 下载结果文件

status	含义	操作
`pending`	排队中	继续轮询
`processing`	处理中	继续轮询
`completed`	完成	调用 download
`failed`	失败	查看 error 字段

一、系统状态

GET `/api/v1/health`

无需认证。

Response 200

json

{ "status": "healthy", "version": "2.1.0", "uptime_seconds": 3600, "active_tasks": 0, "queue_length": 0 }

GET `/api/v1/capabilities`

查询当前服务支持的能力。

Response 200

json

{
  "engines": {
    "draco":   { "available": true, "version": "…", "binary_path": "…" },
    "meshopt": { "available": true, "version": "…", "binary_path": "…" }
  },
  "formats": {
    "input":  ["glb", "gltf", "obj", "fbx", "stl", "dae", "ply"],
    "output": ["glb", "gltf", "obj", "stl", "ply"]
  },
  "license": { "authorized": true, "tier": 1, "status": "active" }
}

二、模型压缩

POST `/api/v1/compress`

提交压缩任务。

Headers

Header	值
Content-Type	`multipart/form-data`
X-API-Key	你的密钥

Body (form-data)

字段	类型	必填	说明
`file`	File	✅	模型文件（GLB/glTF/OBJ/FBX 等）
`engine`	string	✅	`draco` 或 `meshopt`
`level`	integer	❌	压缩级别 0-10（0 为 RAW 不压缩），默认 `7`。数值越大压缩率越高
`position_quantization_bits`	integer	❌	位置精度（仅 Draco），默认 `14`，范围 8-24
`normal_quantization_bits`	integer	❌	法线精度（仅 Draco），默认 `10`
`texcoord_quantization_bits`	integer	❌	UV 精度（仅 Draco），默认 `12`
`color_quantization_bits`	integer	❌	颜色精度（仅 Draco），默认 `8`
`generic_quantization_bits`	integer	❌	通用属性精度（仅 Draco），默认 `12`
`meshopt_compression_level`	string	❌	Meshopt 等级：`high` / `medium` / `low`，默认 `high`

Response 200

json

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "message": "任务已提交，正在排队"
}

三、格式转换

POST `/api/v1/convert`

将模型从一种格式转换为另一种。

Headers

Header	值
Content-Type	`multipart/form-data`
X-API-Key	你的密钥

Body (form-data)

字段	类型	必填	说明
`file`	File	✅	模型文件
`target_format`	string	✅	`glb` / `gltf` / `obj` / `fbx` / `stl` / `dae` / `ply`

目标为 gltf 时输出 .zip 包（含 .gltf + .bin + 贴图）。

Response 200

json

{
  "task_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "pending"
}

四、模型修复

POST `/api/v1/repair`

自动去空节点、修法线、合并重复顶点、删退化面等。

Headers

Header	值
Content-Type	`multipart/form-data`
X-API-Key	你的密钥

Body (form-data)

字段	类型	必填	说明
`file`	File	✅	模型文件

Response 200

json

{
  "task_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "pending"
}

五、模型诊断（规划中）

POST `/api/v1/diagnose`

端点已预留，当前版本返回 501（功能尚未实现）。模型体检诊断目前仅在桌面版提供。

六、纹理优化

POST `/api/v1/textures/optimize`

对模型贴图或单独图片进行 JPEG/WebP/PNG 压缩。

Headers

Header	值
Content-Type	`multipart/form-data`
X-API-Key	你的密钥

Body (form-data)

字段	类型	必填	说明
`file`	File	✅	模型文件或单独图片
`format`	string	✅	`jpeg` / `webp` / `png`
`quality`	integer	❌	质量 1-100，默认 `82`（JPEG/WebP）；PNG 压缩级 1-9，默认 `6`

Response 200

json

{
  "task_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "status": "pending"
}

POST `/api/v1/textures/ktx2`

端点已预留，当前版本返回 501（KTX2 编码尚未实现）。KTX2 编码目前仅在桌面版提供。

七、任务管理

GET `/api/v1/tasks/{task_id}`

通过 task_id 查询任务状态和进度。

Path 参数

参数	类型	说明
`task_id`	string	任务唯一标识

Response 200 — 处理中

json

{
  "task_id": "a1b2c3d4-...",
  "status": "processing",
  "progress": 65,
  "created_at": "2026-08-03T10:30:00Z",
  "started_at": "2026-08-03T10:30:01Z",
  "type": "compress",
  "input_filename": "model.glb",
  "input_size_bytes": 15728640
}

Response 200 — 已完成

json

{
  "task_id": "a1b2c3d4-...",
  "status": "completed",
  "progress": 100,
  "created_at": "2026-08-03T10:30:00Z",
  "completed_at": "2026-08-03T10:30:05Z",
  "type": "compress",
  "input_filename": "model.glb",
  "input_size_bytes": 15728640,
  "output": {
    "filename": "model_optimized.glb",
    "size_bytes": 3145728,
    "compression_ratio": 0.20,
    "savings_percent": 80.0
  }
}

Response 200 — 失败

json

{
  "task_id": "a1b2c3d4-...",
  "status": "failed",
  "error": "draco_transcoder execution failed: exit code 1",
  "created_at": "2026-08-03T10:30:00Z",
  "failed_at": "2026-08-03T10:30:02Z"
}

响应字段说明

字段	类型	说明
`task_id`	string	任务唯一标识
`status`	string	`pending` / `processing` / `completed` / `failed`
`progress`	integer	进度 0-100
`type`	string	`compress` / `convert` / `repair` / `diagnose` / `texture_optimize` / `texture_ktx2`
`input_filename`	string	原始文件名
`input_size_bytes`	integer	原始大小（字节）
`output.filename`	string	输出文件名（completed 时）
`output.size_bytes`	integer	输出大小（字节）（completed 时）
`output.compression_ratio`	float	压缩比（compress/texture 类）
`output.savings_percent`	float	体积减少百分比（compress/texture 类）
`error`	string	错误原因（failed 时）
`created_at`	string	创建时间 ISO 8601
`started_at`	string	开始时间
`completed_at` / `failed_at`	string	结束时间

GET `/api/v1/tasks/{task_id}/download`

下载处理后的结果文件。

Path 参数

参数	类型	说明
`task_id`	string	已完成的任务 ID

Response 200

返回文件二进制流（Content-Type: application/octet-stream）。

八、批量处理

POST `/api/v1/batch/compress`

一次提交多个文件压缩，每个独立生成子任务。

Headers

Header	值
Content-Type	`multipart/form-data`
X-API-Key	你的密钥

Body (form-data)

字段	类型	必填	说明
`files`	File[]	✅	多个模型文件
`engine`	string	✅	`draco` 或 `meshopt`
`level`	integer	❌	压缩级别 1-10，默认 `7`

Response 200

json

{
  "batch_id": "batch-abc123",
  "total": 3,
  "tasks": [
    { "task_id": "t1-...", "filename": "model1.glb", "status": "pending" },
    { "task_id": "t2-...", "filename": "model2.fbx", "status": "pending" },
    { "task_id": "t3-...", "filename": "scene.gltf", "status": "pending" }
  ]
}

GET `/api/v1/batch/{batch_id}`

查询批次整体进度。

Path 参数

参数	类型	说明
`batch_id`	string	批次唯一标识

Response 200

json

{
  "batch_id": "batch-abc123",
  "status": "processing",
  "total": 3, "completed": 1, "failed": 0,
  "tasks": [
    { "task_id": "t1-...", "filename": "model1.glb", "status": "completed" },
    { "task_id": "t2-...", "filename": "model2.fbx", "status": "processing" },
    { "task_id": "t3-...", "filename": "scene.gltf", "status": "pending" }
  ]
}

子任务可单独通过查询任务和下载结果操作。

九、授权

POST `/api/v1/license/verify`

验证 License Key 是否有效。

Body (JSON)

json

{ "license_key": "xxxx-xxxx-xxxx-xxxx" }

Response 200

json

{
  "success": true,
  "message": "license valid",
  "expires_at": 1796064000
}

expires_at 为 Unix 时间戳（秒）。此端点面向管理用途。

GET `/api/v1/license/info`

查询当前授权状态。

Response 200

json

{
  "authorized": true,
  "server_fingerprint": "a1b2c3d4e5f6…",
  "status": "active",
  "license_expires_at": 1796064000,
  "tier": 1,
  "days_until_expiry": 365,
  "machine_id": "server-machine-id"
}

tier：0 = 未授权（试用限制），1/2 = 授权档位；license_expires_at 为 Unix 时间戳（秒）。

十、监控

GET `/api/v1/metrics`

Prometheus 格式监控指标，可用于 Grafana 集成。

指标名	含义
`zipoly_requests_total`	请求总数
`zipoly_active_tasks`	当前并发任务数
`zipoly_queue_length`	队列中等待的任务数
`zipoly_task_processing_duration_seconds`	任务处理耗时分布
`zipoly_tasks_completed_total`	已完成任务总数
`zipoly_tasks_failed_total`	失败任务总数
`zipoly_errors_total`	错误总数

错误码

HTTP	含义	典型场景
400	参数错误	不支持的格式、缺少必填字段
402	超出授权限制	文件超过当前套餐的大小/批量限制、授权过期
401	未授权	缺少/错误的 X-API-Key
404	不存在	task_id / batch_id 无效
500	内部错误	引擎执行失败、磁盘不足

错误响应格式

json

{ "error": "错误描述信息" }

场景	示例
不支持的格式	`{ "error": "unsupported format: .max" }`
缺少必填字段	`{ "error": "missing required field: engine" }`
未授权	`{ "error": "unauthorized: missing or invalid X-API-Key header" }`
超出限制	`{ "error": "file size 512MB exceeds limit of 500MB for current license tier" }`
内部错误	`{ "error": "internal error: draco_transcoder execution failed" }`

其他端点

除上述业务端点外，服务端还提供 Web 管理后台专用的端点（配置读写 /config、事件流 /events、/auth/me、/admin/* 等），一般无需直接调用，此处不再展开。

API 参考 ​

认证 ​

异步任务流程 ​

一、系统状态 ​

GET /api/v1/health ​

GET /api/v1/capabilities ​

二、模型压缩 ​

POST /api/v1/compress ​

三、格式转换 ​

POST /api/v1/convert ​

四、模型修复 ​

POST /api/v1/repair ​

五、模型诊断（规划中） ​

POST /api/v1/diagnose ​

六、纹理优化 ​

POST /api/v1/textures/optimize ​

POST /api/v1/textures/ktx2 ​

七、任务管理 ​

GET /api/v1/tasks/{task_id} ​

GET /api/v1/tasks/{task_id}/download ​

八、批量处理 ​

POST /api/v1/batch/compress ​

GET /api/v1/batch/{batch_id} ​

九、授权 ​

POST /api/v1/license/verify ​

GET /api/v1/license/info ​

十、监控 ​

GET /api/v1/metrics ​

错误码 ​

其他端点 ​

API 参考

认证

异步任务流程

一、系统状态

GET `/api/v1/health`

GET `/api/v1/capabilities`

二、模型压缩

POST `/api/v1/compress`

三、格式转换

POST `/api/v1/convert`

四、模型修复

POST `/api/v1/repair`

五、模型诊断（规划中）

POST `/api/v1/diagnose`

六、纹理优化

POST `/api/v1/textures/optimize`

POST `/api/v1/textures/ktx2`

七、任务管理

GET `/api/v1/tasks/{task_id}`

GET `/api/v1/tasks/{task_id}/download`

八、批量处理

POST `/api/v1/batch/compress`

GET `/api/v1/batch/{batch_id}`

九、授权

POST `/api/v1/license/verify`

GET `/api/v1/license/info`

十、监控

GET `/api/v1/metrics`

错误码

其他端点