printer_service API 文档

运行在 armbian T95 主机（192.168.3.26）上的打印服务，通过本机 CUPS 驱动局域网打印机 （HP_SmartTank_580 → ipp://192.168.3.34/ipp/print）。

版本 1.0.0 · 文档路径 /docs · 规范 /openapi.json

接入信息

快速开始

export BASE=https://19563.ai-x-service.top
export KEY=ps_xxxxxxxxxxxx   # 见 config.json / docs/API.md

# 1) 主机在线状态
curl -s -H "X-API-Key: $KEY" $BASE/api/host | jq .

# 2) 打印机状态
curl -s -H "X-API-Key: $KEY" $BASE/api/printers | jq .

# 3) 打印一个 PDF
curl -s -H "X-API-Key: $KEY" -F "file=@hello.pdf" $BASE/api/print | jq .

# 4) 打印一段文本
curl -s -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
     -d '{"text":"Hello 打印机","job_name":"问候"}' $BASE/api/print | jq .

接口总览

打印参数（POST /api/print）

支持 4 种请求体：
① multipart/form-data，文件字段名 file；
② application/json + content_base64（可带 filename）；
③ application/json + text（按 text/plain 打印）；
④ 原始字节流（Content-Type: application/pdf 等）。

输出字段说明

打印机状态 printer-state

idle 空闲 / processing 打印中 / stopped 停止（详见 state_reasons）。

任务状态 job-state

pending 排队 / processing 打印中 / completed 完成 / canceled 已取消 / aborted 失败。

错误返回

{"ok": false, "error": {"code": "cups_error", "message": "IPP 错误 ..."}}

调用示例

GET /health

服务与主机存活探针（无需密钥）

curl -s https://19563.ai-x-service.top/health

GET /api/host

armbian 主机在线状态：CPU 温度/负载、内存、磁盘、IP、CUPS 状态

curl -s -H "X-API-Key: $KEY" https://19563.ai-x-service.top/api/host

GET /api/host/resources

主机资源使用情况：CPU 使用率(总体/每核)/温度/频率、内存与交换、磁盘

curl -s -H "X-API-Key: $KEY" https://19563.ai-x-service.top/api/host/resources

GET /api/printers

打印机列表：状态、是否接收任务、队列长度、耗材余量

curl -s -H "X-API-Key: $KEY" https://19563.ai-x-service.top/api/printers

GET /api/printers/{name}

单台打印机详情 + 该打印机进行中的任务

curl -s -H "X-API-Key: $KEY" https://19563.ai-x-service.top/api/printers/HP_SmartTank_580

GET /api/printers/{name}/raw

打印机全部原始 IPP 属性（调试用）

curl -s -H "X-API-Key: $KEY" https://19563.ai-x-service.top/api/printers/HP_SmartTank_580/raw

POST /api/print

提交打印任务（multipart 文件 / JSON base64 / JSON 文本 / 原始字节流）

curl -s -H "X-API-Key: $KEY" -F "file=@a.pdf" https://19563.ai-x-service.top/api/print

POST /api/printers/{name}/test-page

打印测试页（含主机状态），验证 armbian→CUPS→打印机 链路

curl -s -X POST -H "X-API-Key: $KEY" https://19563.ai-x-service.top/api/printers/HP_SmartTank_580/test-page

GET /api/jobs

任务列表

curl -s -H "X-API-Key: $KEY" "https://19563.ai-x-service.top/api/jobs?which=active&limit=10"

GET /api/jobs/{id}

单个任务状态

curl -s -H "X-API-Key: $KEY" https://19563.ai-x-service.top/api/jobs/42

POST /api/jobs/{id}/cancel

取消任务

curl -s -X POST -H "X-API-Key: $KEY" https://19563.ai-x-service.top/api/jobs/42/cancel

GET /api/whoami

校验密钥是否有效

curl -s -H "X-API-Key: $KEY" https://19563.ai-x-service.top/api/whoami

GET /docs

本接口文档（HTML，无需密钥）

curl -s https://19563.ai-x-service.top/docs

GET /openapi.json

OpenAPI 3.0 规范（无需密钥）

curl -s https://19563.ai-x-service.top/openapi.json