快速开始

下面通过公开 API 完成“上传图片 → 创建预览流 → 更新预览 → 下载最终结果”的完整流程。

1. 启动图片处理拓扑

docker network create wangquan-network
cp .env.example .env

docker compose \
  -f docker-compose.yml \
  -f docker-compose.workers.yml \
  up -d --build resource-service image-worker markify-api docs

API、Resource Service 和 Image Worker 在各自容器内监听 80。项目不直接发布宿主机端口，需要由同一 wangquan-network 中的网关或反向代理访问 markify-api 和 markify-docs。

2. 上传源图片

curl -X POST https://markify.example.com/v1/resource \
  -F 'file=@source.png'

响应示例：

{
  "resourceToken": "<resource-token>",
  "expiresIn": 3000,
  "mediaType": "image/png",
  "size": 184220,
  "width": 1920,
  "height": 1080,
  "status": "READY"
}

3. 创建实时预览流

curl -X POST https://markify.example.com/v1/source/streams \
  -H 'content-type: application/json' \
  -d '{"resourceToken":"<resource-token>"}'

将响应中的流地址设置给图片元素一次：

<img
  src="https://markify.example.com/v1/source/stream/<stream-token>"
  alt="水印预览"
/>

4. 发布预览

curl -X POST https://markify.example.com/v1/source/preview \
  -H 'content-type: application/json' \
  -d @render-job.json

render-job.json：

{
  "version": 1,
  "resources": [{ "resourceToken": "<resource-token>" }],
  "layers": [
    {
      "type": "text",
      "text": "Markify · Internal",
      "zIndex": 10,
      "font": {
        "family": "Noto Sans CJK SC",
        "size": 48,
        "weight": 600,
        "color": "#ffffff"
      },
      "opacity": 0.65,
      "position": { "mode": "bottom-right", "offset": { "x": -32, "y": -32 } },
      "rotation": 0
    }
  ],
  "output": { "format": "png", "quality": 90 }
}

预览通道固定生成 WebP 80；output 只影响最终渲染。

5. 下载最终结果

curl -X POST https://markify.example.com/v1/source/render \
  -H 'content-type: application/json' \
  -d @render-job.json \
  --output markify-images.zip

最终 ZIP 完整交付后，resources[] 中的源资源会被消费并关闭关联预览流。作为图片图层引用、但没有出现在 resources[] 中的资源不会被自动消费。

不需要预览时

可以跳过创建 streamToken 和发布预览，上传完成后直接调用最终渲染接口。