diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..6d238fb
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,62 @@
+# gen2d API 文档
+
+Base URL: `http://localhost:8080`
+
+## 统一响应格式
+
+所有接口均返回以下 JSON 结构：
+
+```json
+{
+  "code": 0,
+  "message": "ok",
+  "data": {}
+}
+```
+
+| 字段      | 类型   | 说明                                   |
+| --------- | ------ | -------------------------------------- |
+| `code`    | int    | 业务状态码。`0` 表示成功，非零为错误码 |
+| `message` | string | 状态描述                               |
+| `data`    | any    | 响应数据，错误时可能不返回此字段       |
+
+### 成功响应
+
+```json
+{
+  "code": 0,
+  "message": "ok",
+  "data": { ... }
+}
+```
+
+### 错误响应
+
+```json
+{
+  "code": 400,
+  "message": "error description"
+}
+```
+
+---
+
+## 接口列表
+
+### 健康检查
+
+```
+GET /api/v1/health
+```
+
+**响应示例**
+
+```json
+{
+  "code": 0,
+  "message": "ok",
+  "data": {
+    "status": "healthy"
+  }
+}
+```