ystp/frontend/src/pages/DocsPage.vue

<template>
  <div class="space-y-6">
    <div class="space-y-1">
      <h1 class="text-2xl font-semibold tracking-tight text-slate-900">开发者</h1>
      <p class="text-sm text-slate-600">完整 API 调用说明与示例，适合直接集成到服务端或脚本。</p>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">快速开始</div>
      <ol class="mt-2 list-decimal space-y-1 pl-5">
        <li>登录后在控制台创建 API Key（仅 Pro/Business）。</li>
        <li>使用 <code>X-API-Key</code> 调用压缩接口。</li>
        <li>建议为每次请求设置 <code>Idempotency-Key</code>，避免重复扣费。</li>
      </ol>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">基础信息</div>
      <ul class="mt-2 list-disc space-y-1 pl-5">
        <li>Base URL：<code>https://ys.workyai.cn/api/v1</code></li>
        <li>认证方式：<code>X-API-Key</code>（推荐）或 <code>Authorization: Bearer &lt;token&gt;</code></li>
        <li>支持格式：PNG / JPG / JPEG / WebP / AVIF / GIF / BMP / TIFF / ICO（仅静态图片，支持 output_format 转码）</li>
        <li>压缩率：<code>compression_rate</code> 1-100；JPEG/WebP/AVIF 以该比例为体积上限，无损格式为尽力优化</li>
        <li>目标体积：<code>target_size_bytes</code> 仅支持 JPEG/WebP/AVIF，且不能与 <code>compression_rate</code> 同时提交</li>
        <li>计量：输出体积变小时计 1 次；仅同格式、无缩放的 <code>compression_rate=100</code> 原样请求免计量</li>
      </ul>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">同步压缩（返回 JSON + 下载链接）</div>
      <div class="mt-2 text-xs text-slate-500">
        <code>POST /compress</code>，表单字段：<code>file</code>、<code>compression_rate</code>/<code>target_size_bytes</code>、
        <code>output_format</code>、<code>max_width</code>、<code>max_height</code>、<code>preserve_metadata</code>
      </div>
      <pre class="mt-3 overflow-auto rounded-lg bg-slate-950 p-4 text-xs text-slate-100"><code>curl -X POST \
  -H "X-API-Key: if_live_xxx" \
  -F "file=@./demo.jpg" \
  -F "compression_rate=20" \
  -F "output_format=webp" \
  -F "max_width=2000" \
  https://ys.workyai.cn/api/v1/compress</code></pre>
      <div class="mt-3 text-xs text-slate-500">
        返回字段包含 <code>download_url</code>、<code>saved_percent</code> 与 <code>billing.units_charged</code>。
        目标小于清晰度保护边界时返回 <code>INVALID_REQUEST</code>，不会返回超过目标的文件。
      </div>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">同步压缩（直接返回二进制）</div>
      <div class="mt-2 text-xs text-slate-500">
        <code>POST /compress/direct</code>，支持同样参数（含 output_format、target_size_bytes），响应头包含原/压缩大小与扣费信息。
      </div>
      <pre class="mt-3 overflow-auto rounded-lg bg-slate-950 p-4 text-xs text-slate-100"><code>curl -X POST \
  -H "X-API-Key: if_live_xxx" \
  -F "file=@./demo.jpg" \
  -F "target_size_bytes=120000" \
  -F "output_format=jpeg" \
  https://ys.workyai.cn/api/v1/compress/direct -o out.jpg -D headers.txt</code></pre>
      <div class="mt-3 text-xs text-slate-500">
        重点响应头：<code>ImageForge-Original-Size</code>、
        <code>ImageForge-Compressed-Size</code>、
        <code>ImageForge-Units-Charged</code>
      </div>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">批量压缩（异步任务）</div>
      <div class="mt-2 text-xs text-slate-500">
        <code>POST /compress/batch</code>，上传多文件后返回任务 ID。
      </div>
      <pre class="mt-3 overflow-auto rounded-lg bg-slate-950 p-4 text-xs text-slate-100"><code>curl -X POST \
  -H "X-API-Key: if_live_xxx" \
  -F "files[]=@./a.jpg" \
  -F "files[]=@./b.jpg" \
  -F "compression_rate=30" \
  https://ys.workyai.cn/api/v1/compress/batch</code></pre>
      <div class="mt-3 text-xs text-slate-500">
        轮询任务：<code>GET /compress/tasks/&lt;task_id&gt;</code>，响应包含每个文件的 <code>download_url</code> 和 <code>download_all_url</code>（ZIP）。
      </div>
      <pre class="mt-3 overflow-auto rounded-lg bg-slate-950 p-4 text-xs text-slate-100"><code>curl -H "X-API-Key: if_live_xxx" \
  https://ys.workyai.cn/api/v1/compress/tasks/550e8400-e29b-41d4-a716-446655440200</code></pre>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">下载文件</div>
      <div class="mt-2 text-xs text-slate-500">
        下载地址不在 <code>/api/v1</code> 下，需带同样的认证头。
      </div>
      <pre class="mt-3 overflow-auto rounded-lg bg-slate-950 p-4 text-xs text-slate-100"><code>curl -H "X-API-Key: if_live_xxx" \
  -L https://ys.workyai.cn/downloads/&lt;file_id&gt; -o result.jpg

curl -H "X-API-Key: if_live_xxx" \
  -L https://ys.workyai.cn/downloads/tasks/&lt;task_id&gt; -o batch.zip</code></pre>
    </div>

    <div class="rounded-xl border border-slate-200 bg-white p-5 text-sm text-slate-700">
      <div class="font-medium text-slate-900">错误处理与常见问题</div>
      <ul class="mt-2 list-disc space-y-1 pl-5">
        <li><code>INVALID_REQUEST</code>：参数或文件不合法（检查格式与字段）</li>
        <li><code>UNSUPPORTED_FORMAT</code>：不支持该格式或输入为动画图片</li>
        <li><code>QUOTA_EXCEEDED</code>：额度不足（升级套餐或等待周期重置）</li>
        <li><code>FORBIDDEN</code>：无权限下载该任务/文件（认证不一致）</li>
        <li><code>EMAIL_NOT_VERIFIED</code>：登录用户需先完成邮箱验证</li>
      </ul>
    </div>

    <div class="text-sm text-slate-600">
      更完整的字段与响应说明请查看仓库文档：<code>docs/api.md</code>。
    </div>
  </div>
</template>