加速器 API 參考¶

本頁列出 Spectrum / Prisma 加速器服務的所有 REST API 端點。端點依層級分類，高層級端點向下相容。

基礎 URL：https://{prisma-host}:{port}（Remote 模式）或透過 SpectrumClient 間接呼叫（Sidecar 模式）。

通用慣例¶

請求標頭¶

Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
X-Request-ID: {uuid-v4}      # 可選，用於追蹤
X-Tenant-ID: {tenant-id}     # HighControl 模式必填

通用回應格式¶

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "version": "1.0.0",
  "data": { ... },
  "meta": {
    "duration_ms": 45,
    "worker_id": "worker-3",
    "cached": false
  }
}

錯誤回應（RFC 7807）¶

{
  "type": "https://docs.nextpdf.dev/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded 1000 requests per minute.",
  "instance": "/v1/parse/b9d3e8a1",
  "retry_after": 30
}

健康檢查端點（所有層級）¶

`GET /health`¶

服務健康狀態檢查。

回應

{
  "status": "ok",
  "version": "1.0.0",
  "tier": "spectrum",
  "mode": "sidecar",
  "workers": {
    "total": 8,
    "busy": 2,
    "idle": 6
  },
  "uptime_seconds": 86400,
  "circuit_breaker": "closed"
}

`GET /metrics`¶

Prometheus 格式指標（需啟用 SPECTRUM_METRICS_ENABLED）。

# HELP spectrum_requests_total Total number of requests
# TYPE spectrum_requests_total counter
spectrum_requests_total{operation="font_subset",status="success"} 12453
spectrum_requests_total{operation="font_subset",status="error"} 3

# HELP spectrum_request_duration_seconds Request duration in seconds
# TYPE spectrum_request_duration_seconds histogram
spectrum_request_duration_seconds_bucket{operation="font_subset",le="0.01"} 9823
spectrum_request_duration_seconds_bucket{operation="font_subset",le="0.05"} 12201

Core 端點（Spectrum，所有層級）¶

`POST /v1/font/subset`¶

執行 OpenType 字型子集化。

請求體

{
  "font_data": "<base64-encoded font bytes>",
  "codepoints": [72, 101, 108, 108, 111],
  "options": {
    "preserve_hints": true,
    "optimize_cff": true,
    "include_gsub": true
  }
}

回應

{
  "request_id": "...",
  "data": {
    "font_data": "<base64-encoded subset>",
    "original_size_bytes": 524288,
    "subset_size_bytes": 12488,
    "reduction_percent": 97.6,
    "included_glyphs": 5
  }
}

錯誤碼

狀態碼	錯誤類型	說明
400	`invalid-font-data`	字型資料損毀或格式不支援
413	`font-too-large`	字型超過最大允許大小（預設 50MB）
429	`rate-limit-exceeded`	請求頻率超過限制
503	`worker-pool-exhausted`	所有 Worker 均忙碌

`POST /v1/image/compress`¶

執行影像壓縮與重採樣。

請求體

{
  "image_data": "<base64-encoded image bytes>",
  "format": "jpeg",
  "options": {
    "quality": 85,
    "max_width": 2048,
    "max_height": 2048,
    "resample": "lanczos",
    "color_space": "rgb"
  }
}

回應

{
  "data": {
    "image_data": "<base64-encoded compressed image>",
    "original_size_bytes": 2097152,
    "compressed_size_bytes": 145678,
    "width": 1920,
    "height": 1080,
    "format": "jpeg"
  }
}

`POST /v1/linearize`¶

對已生成的 PDF 執行線性化（Fast Web View）。

請求體

{
  "pdf_data": "<base64-encoded PDF>",
  "options": {
    "optimize_for_web": true,
    "preserve_signatures": true
  }
}

解析端點（Prisma Pro+）¶

`POST /v1/parse`¶

解析 PDF 文件，提取結構化內容。

請求體

{
  "pdf_data": "<base64-encoded PDF>",
  "options": {
    "extract_text": true,
    "extract_images": false,
    "extract_tables": true,
    "extract_forms": true,
    "extract_bookmarks": true,
    "page_range": [1, 10],
    "language_hint": "zh-TW"
  }
}

回應

{
  "data": {
    "page_count": 10,
    "metadata": {
      "title": "Document Title",
      "author": "Author Name",
      "created_at": "2026-01-15T10:00:00Z",
      "pdf_version": "2.0",
      "is_linearized": true,
      "has_signatures": false
    },
    "pages": [
      {
        "page_number": 1,
        "width": 595.28,
        "height": 841.89,
        "text_blocks": [
          {
            "text": "Hello World",
            "x": 56.69,
            "y": 785.20,
            "width": 120.5,
            "height": 14.0,
            "font": "Helvetica",
            "font_size": 12.0,
            "reading_order": 1
          }
        ],
        "tables": [],
        "form_fields": []
      }
    ]
  }
}

`POST /v1/compare`¶

比較兩份 PDF 文件的差異。

請求體

{
  "pdf_a": "<base64-encoded PDF A>",
  "pdf_b": "<base64-encoded PDF B>",
  "options": {
    "mode": "semantic",
    "ignore_formatting": false,
    "page_range": null
  }
}

回應

{
  "data": {
    "summary": {
      "pages_changed": 3,
      "text_additions": 15,
      "text_deletions": 8,
      "image_changes": 2
    },
    "changes": [
      {
        "type": "text_change",
        "page": 2,
        "before": "Old text content",
        "after": "New text content",
        "position": { "x": 56.69, "y": 700.0 }
      }
    ]
  }
}

`POST /v1/extract-text`¶

高精度文字提取，保留字型、顏色與位置元資料。

RAG 端點（Prisma Enterprise）¶

`POST /v1/rag/chunk`¶

將 PDF 文件分割為語意塊（Chunks），供 RAG 管線使用。

請求體

{
  "pdf_data": "<base64-encoded PDF>",
  "options": {
    "strategy": "semantic",
    "max_chunk_size": 512,
    "chunk_overlap": 64,
    "preserve_structure": true,
    "language": "zh-TW"
  }
}

回應

{
  "data": {
    "document_id": "doc-abc123",
    "chunk_count": 48,
    "chunks": [
      {
        "chunk_id": "chunk-0001",
        "text": "...",
        "page": 1,
        "section": "Introduction",
        "token_count": 487,
        "metadata": {
          "headings_path": ["Chapter 1", "Introduction"],
          "is_table": false,
          "language": "zh-TW"
        }
      }
    ]
  }
}

`POST /v1/rag/embed`¶

將文字或 PDF 內容向量化，返回嵌入向量。

請求體

{
  "inputs": [
    { "id": "chunk-0001", "text": "..." },
    { "id": "chunk-0002", "text": "..." }
  ],
  "model": "nextpdf-embed-v1",
  "options": {
    "normalize": true,
    "dimensions": 1536
  }
}

回應

{
  "data": {
    "model": "nextpdf-embed-v1",
    "dimensions": 1536,
    "embeddings": [
      {
        "id": "chunk-0001",
        "vector": [0.0123, -0.0456, ...],
        "token_count": 487
      }
    ]
  }
}

`POST /v1/rag/index`¶

直接將 PDF 文件分塊、向量化並寫入向量資料庫。

請求體

{
  "pdf_data": "<base64-encoded PDF>",
  "vector_store": {
    "backend": "qdrant",
    "collection": "my-knowledge-base",
    "endpoint": "http://qdrant:6333",
    "api_key": "${QDRANT_API_KEY}"
  },
  "options": {
    "chunking_strategy": "semantic",
    "embedding_model": "nextpdf-embed-v1",
    "upsert": true,
    "namespace": "tenant-abc123"
  }
}

回應

{
  "data": {
    "document_id": "doc-abc123",
    "chunks_indexed": 48,
    "vectors_upserted": 48,
    "collection": "my-knowledge-base",
    "duration_ms": 1234
  }
}

`POST /v1/rag/search`¶

在已索引的文件中執行向量語意搜尋。

請求體

{
  "query": "What is the refund policy?",
  "vector_store": {
    "backend": "qdrant",
    "collection": "my-knowledge-base"
  },
  "options": {
    "top_k": 5,
    "min_score": 0.7,
    "namespace": "tenant-abc123",
    "filter": {
      "metadata.language": "zh-TW"
    }
  }
}

叢集管理端點（Prisma Enterprise）¶

`GET /v1/cluster/status`¶

查詢叢集所有節點的狀態。

回應

{
  "data": {
    "cluster_id": "prod-cluster-1",
    "node_count": 3,
    "healthy_nodes": 3,
    "nodes": [
      {
        "node_id": "node-1",
        "address": "prisma-1.internal:8080",
        "status": "healthy",
        "active_jobs": 12,
        "cpu_percent": 45.2,
        "memory_mb": 1024
      }
    ]
  }
}

速率限制¶

層級	預設限制	可設定範圍
Spectrum	無限制（本地 Socket）	—
Prisma Pro	每分鐘 1,000 請求	可設定
Prisma Enterprise	每分鐘 10,000 請求	可設定 + 多租戶獨立限制

參見¶

驗證機制 — 所有端點的認證標頭格式
設定參考 — 速率限制設定
效能報告 — 各端點的基準延遲資料

加速器 API 參考¶

通用慣例¶

請求標頭¶

通用回應格式¶

錯誤回應（RFC 7807）¶

健康檢查端點（所有層級）¶

GET /health¶

GET /metrics¶

Core 端點（Spectrum，所有層級）¶

POST /v1/font/subset¶

POST /v1/image/compress¶

POST /v1/linearize¶

解析端點（Prisma Pro+）¶

POST /v1/parse¶

POST /v1/compare¶

POST /v1/extract-text¶

RAG 端點（Prisma Enterprise）¶

POST /v1/rag/chunk¶

POST /v1/rag/embed¶

POST /v1/rag/index¶

POST /v1/rag/search¶

叢集管理端點（Prisma Enterprise）¶

GET /v1/cluster/status¶

速率限制¶

參見¶

`GET /health`¶

`GET /metrics`¶

`POST /v1/font/subset`¶

`POST /v1/image/compress`¶

`POST /v1/linearize`¶

`POST /v1/parse`¶

`POST /v1/compare`¶

`POST /v1/extract-text`¶

`POST /v1/rag/chunk`¶

`POST /v1/rag/embed`¶

`POST /v1/rag/index`¶

`POST /v1/rag/search`¶

`GET /v1/cluster/status`¶