开发者 API

Vecaria 的批量与工作流提供 HTTP API。所有需要登录的接口使用会话 Cookie鉴权（credentials: "include"）；Webhook 触发接口使用密钥鉴权、无需登录。机器可读的 OpenAPI 3.1 规范见 /openapi.json。

通用约定

基址：https://vecaria.com
响应包裹：{ "ok": true, "data": … } 或 { "ok": false, "error": { "code": "…", "message": "…" } }
所有限额、费用与触发开关均在后台配置（batch_configs / workflow_configs），API 读取生效值。

SDK 与 CLI

官方 零依赖 客户端封装「上传 → 任务 → 下载」与 MCP 端点：

JavaScript：vecaria-sdk（sdk/index.mjs）+ CLI（sdk/cli.mjs）

import { VecariaClient } from "vecaria-sdk";
const cf = new VecariaClient({ token: process.env.VECARIA_TOKEN });
const { fileId, url } = await cf.convert("drawing.dxf", bytes, { operation: "dxf.to.svg" });

Python：pip install ./sdk/python（vecaria，Python 3.9+ 仅标准库）

from vecaria import VecariaClient
cf = VecariaClient(token=os.environ["VECARIA_TOKEN"])
out = cf.convert("drawing.dxf", open("drawing.dxf", "rb").read(), operation="dxf.to.svg")

CLI：vecaria convert drawing.dxf --op dxf.to.svg --out out.svg

两者都提供 mcp(method, params) 调用下面的 MCP 端点。

MCP（Model Context Protocol）

POST /api/mcp 以 Streamable HTTP（JSON-RPC）实现 MCP。匿名可调用只读工具（list_tools、ping）；携带 Token 后可调用 list_batches、list_workflows，Token 具备 mcp:write 权限时可调用写工具（create_batch、run_workflow）。

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

批量

预估费用

POST /api/batch/estimate · 登录

{ "fileCount": 10 }

返回 { credits, baseCredits, perFileCredits, maxFiles }。

创建批量

POST /api/batch · 登录

{ "type": "pdf.compress", "fileIds": ["<fileId>", "…"], "params": {}, "name": "归档", "engine": "server" }

fileIds 为先经上传接口确认（UPLOADED）的文件 id。
受 batch.max_files_* / batch.max_size_mb_* 限制；按 base + per_file × N 扣点。
返回 { batchId, credits }。

查询 / 取消 / 重试 / 打包

GET /api/batch/:id → { batch, files[] }（含逐文件 status/errorCode/outFileId）
GET /api/batch/:id/events → SSE { total, done, failed, status }（终态自动结束）
POST /api/batch/:id/cancel
POST /api/batch/:id/retry（仅重试失败项）
GET /api/batch/:id/zip（STORE 流式 ZIP）

文件上传（三步）

POST /api/files/presign-upload { filename, mime, size, jobType, createJob:false } → { fileId, uploadUrl }
PUT <uploadUrl>（请求体为文件）
POST /api/files/confirm { fileId }

从 URL 导入

POST /api/files/import-url { url, filename?, mime?, jobType?, createJob? } —— 拉取远程 http(s) 文件（SSRF 防护、限大小）到 R2，返回 { fileId } 供批量/工作流使用。

工作流

校验

POST /api/workflows/validate { graphJson } → { issues[], ok }（结构 / 环 / 步数 / IO 兼容）。

定义与运行

POST /api/workflows { name, graphJson, paramsJson? }
GET /api/workflows、PUT /api/workflows/:id、DELETE /api/workflows/:id
POST /api/workflows/:id/estimate → { credits, steps, maxSteps }
POST /api/workflows/:id/run { fileIds[] } → { runId, credits }
GET /api/workflows/runs/:runId → { run, steps[] }（逐步时间线）
POST /api/workflows/runs/:runId/retry

图模型

{
  "nodes": [
    { "id": "s", "type": "source.upload", "data": { "type": "source.upload", "io": { "produces": ["pdf"] } } },
    { "id": "c", "type": "op.pdf.compress", "data": { "type": "op.pdf.compress", "params": { "level": 5 }, "io": { "accepts": ["pdf"], "produces": ["pdf"] } } },
    { "id": "z", "type": "sink.zip", "data": { "type": "sink.zip", "params": { "name": "out" } } }
  ],
  "edges": [ { "source": "s", "target": "c" }, { "source": "c", "target": "z" } ]
}

节点类别：trigger.*（manual/webhook/schedule）、source.upload、op.*、logic.filter|merge、sink.download|zip|rename。

触发器

GET /api/workflows/:id/triggers
PUT /api/workflows/:id/triggers { type: "webhook"|"schedule"|"watch", config } → { id, secret }
DELETE /api/workflows/:id/triggers/:triggerId

Webhook 触发（无需登录）

推荐 HMAC 签名；仍兼容 body 内明文 secret。

X-Vecaria-Timestamp: <unix 秒>
X-Vecaria-Signature: sha256=<hmac_sha256_hex(secret, `${timestamp}.${rawBody}`)>

POST /api/workflows/:id/hook，JSON 体 { "fileIds": ["<fileId>"] }（签名超过 300s 视为过期，防重放）。

旧版（无签名头）：

{ "secret": "<webhook secret>", "fileIds": ["<fileId>"] }

定时与监听

schedule：config.cron（UTC 5 段 cron；分钟建议取 5 的倍数，随系统 5 分钟 cron 分派）。
watch：config.suffix（如 .dxf）/ config.prefix；用户上传确认后匹配即自动运行。

完成通知

出站 Webhook：paramsJson.notifyUrl，运行结束 POST { runId, status, fileIds|error }；若同时配置 paramsJson.notifySecret（≥8 字符），请求带 X-Vecaria-Timestamp / X-Vecaria-Signature（同一 HMAC 方案）。
邮件：后台开启 workflow.notify_email_enabled（需配置 RESEND_API_KEY）。

人工审批

图中加入 logic.approval 节点（params.timeoutSeconds）。
审批：POST /api/workflows/runs/:runId/approve { "decision": "approved" | "rejected", "note": "…" }。

子工作流

使用 op.workflow 节点（params.workflowId）在同一运行内执行另一工作流；嵌套上限 3 层。

MCP

端点：POST /api/mcp（JSON-RPC 2.0，Streamable HTTP）。
方法：initialize、tools/list、tools/call。
只读工具（无需鉴权）：list_tools、ping。
Token 工具（Authorization: Bearer vk_…）：list_batches、list_workflows；写工具（create_batch、run_workflow）需 Token 具备 mcp:write scope。
示例：{"jsonrpc":"2.0","id":1,"method":"tools/list"}。

合规

所有处理优先在浏览器本地完成；云端处理仅在后台上传/限额允许时启用，产物按保留策略自动清理。