API 总览

公共约定

• 示例基础地址：https://markify.example.com。
• JSON 请求使用 Content-Type: application/json。
• 上传使用 multipart/form-data，字段名为 file。
• Token 使用大小写敏感的 base64url 字符串，不应记录到公开日志。
• 除实时流和二进制结果外，错误响应使用 JSON。

公开业务接口

方法	路径	请求	成功响应
POST	/v1/resource	multipart 图片	201 资源元数据
DELETE	/v1/resource/{resourceToken}	路径参数	204
POST	/v1/source/streams	CreateStreamRequest	201 流元数据
GET	/v1/source/stream/{streamToken}	路径参数	200 multipart 流
DELETE	/v1/source/streams/{streamToken}	路径参数	204
POST	/v1/source/preview	RenderRequest	200 发布结果
POST	/v1/source/render	RenderRequest	200 ZIP
POST	/v1/render/image	旧 multipart 模型	200 图片

健康与观测

方法	路径	说明
GET	/health/live	API 进程存活
GET	/health/ready	API 可接收请求
GET	/health/dependencies	已注册 Worker 状态
GET	/logs	API 持久化日志查询

状态码

状态码	含义
200	查询、预览或渲染成功
201	资源或预览流创建成功
204	删除成功，无响应体
400	请求模型、字段组合或 JSON 非法
404	资源、流或端点不存在
409	资源状态冲突或预览被新请求取代
410	资源或流已经过期
413	上传或输出超过单项限制
422	媒体内容不可处理
429	Worker 或订阅者并发达到上限
502	Worker 返回了无效响应
503	Worker/资源服务不可用或流容量耗尽
504	下游渲染超时
507	tmpfs、资源或预览帧容量耗尽

Worker 可选不等于业务可选

API readiness 不依赖 Worker，但调用图片预览或渲染时必须配置并启动 Image Worker。