From 8852ce6fc2797493bbbf4cea81ba5c9475c565d0 Mon Sep 17 00:00:00 2001 From: yuyx <237899745@qq.com> Date: Sat, 20 Dec 2025 17:55:26 +0800 Subject: [PATCH] Expand developer docs on homepage --- frontend/src/pages/DocsPage.vue | 94 +++++++++++++++++++++++++++++---- 1 file changed, 85 insertions(+), 9 deletions(-) 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 @@

开发者

-

对外 API + 计费 + 额度（硬配额）一体化。

+

完整 API 调用说明与示例，适合直接集成到服务端或脚本。

快速开始
    -
  1. 登录后，在控制台创建 API Key（仅 Pro/Business）。
    2. -
  2. 调用 POST /api/v1/compress/direct 获得二进制输出。
    3. -
  3. 配额不足返回 402 QUOTA_EXCEEDED，请升级或等待周期重置。
    4. +
  4. 登录后在控制台创建 API Key（仅 Pro/Business）。
    5. +
  5. 使用 X-API-Key 调用压缩接口。
    6. +
  6. 建议为每次请求设置 Idempotency-Key，避免重复扣费。
-
示例（curl）
+
基础信息
+ +
+ +
+
同步压缩（返回 JSON + 下载链接）
+
+ POST /compress，表单字段：file、compression_rate、 + max_width、max_height、preserve_metadata + 
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
+ -F \"file=@./demo.jpg\" \\ + -F \"compression_rate=20\" \\ + -F \"max_width=2000\" \\ + https://ys.workyai.cn/api/v1/compress +
+ 返回字段包含 download_url、saved_percent 与 billing.units_charged。 +
+
+ +
+
同步压缩（直接返回二进制）
+
+ POST /compress/direct，响应头包含原/压缩大小与扣费信息。 +
+ 
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
+
+ 重点响应头：ImageForge-Original-Size、 + ImageForge-Compressed-Size、 + ImageForge-Units-Charged +
+
+ +
+
批量压缩（异步任务）
+
+ POST /compress/batch，上传多文件后返回任务 ID。 +
+ 
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
+
+ 轮询任务：GET /compress/tasks/<task_id>，响应包含每个文件的 download_url 和 download_all_url（ZIP）。 +
+ 
curl -H \"X-API-Key: if_live_xxx\" \\
+  https://ys.workyai.cn/api/v1/compress/tasks/550e8400-e29b-41d4-a716-446655440200
+
+ +
+
下载文件
+
+ 下载地址不在 /api/v1 下，需带同样的认证头。 +
+ 
curl -H \"X-API-Key: if_live_xxx\" \\
+  -L https://ys.workyai.cn/downloads/<file_id> -o result.jpg
+
+curl -H \"X-API-Key: if_live_xxx\" \\
+  -L https://ys.workyai.cn/downloads/tasks/<task_id> -o batch.zip
+
+ +
+
错误处理与常见问题
+
- 更完整的接口说明请查看仓库内文档：docs/api.md。 + 更完整的字段与响应说明请查看仓库文档：docs/api.md。