diff --git a/frontend/src/pages/DocsPage.vue b/frontend/src/pages/DocsPage.vue
index 9fbc0ae..4413122 100644
--- a/frontend/src/pages/DocsPage.vue
+++ b/frontend/src/pages/DocsPage.vue
@@ -2,29 +2,105 @@
   <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>
+      <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>POST /api/v1/compress/direct</code> 获得二进制输出。</li>
-        <li>配额不足返回 <code>402 QUOTA_EXCEEDED</code>，请升级或等待周期重置。</li>
+        <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">示例（curl）</div>
+      <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</li>
+        <li>压缩率：<code>compression_rate</code> 1-100，表示压缩后体积占原图比例，100 为不压缩</li>
+        <li>计量：成功压缩 1 个文件计 1 次；若体积未变小或压缩率为 100，则不扣额度</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>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.png\" \\
-  -F \"compression_rate=70\" \\
-  https://your-domain.com/api/v1/compress/direct -o out.png</code></pre>
+  -F \"file=@./demo.jpg\" \\
+  -F \"compression_rate=20\" \\
+  -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>。
+      </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>，响应头包含原/压缩大小与扣费信息。
+      </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\" \\
+  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>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>。
+      更完整的字段与响应说明请查看仓库文档：<code>docs/api.md</code>。
     </div>
   </div>
 </template>