diff --git a/README.md b/README.md
index 86ba3ff..6c67de7 100644
--- a/README.md
+++ b/README.md
@@ -331,6 +331,258 @@ llmage (模型管理) ──→ llm.ppid ──→ pricing_program.id
 
 ---
 
+## HTTP API 接口
+
+### 获取定价展示数据
+
+```
+GET /pricing/api/get_pricing_display.dspy?ppid={ppid}
+Authorization: Bearer {token}
+```
+
+**说明：** 返回指定定价项目的可读定价数据，供前端展示。自动解析 pricing_data 字段，转换为人类可读的价格表。
+
+**返回示例（Token 定价）：**
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "ppid": "5i1JIpqERgCWqKQ4DCegD",
+    "name": "通义千问 qwen3.7-max",
+    "pricing_type": "per_use",
+    "items": [
+      {
+        "filters": {"model": "qwen3.7-max"},
+        "filter_labels": {"模型": "qwen3.7-max"},
+        "price_factors": [
+          {
+            "factor": "uncache_tokens",
+            "label": "非缓存tokens",
+            "unit_price": 6.0,
+            "unit": "百万",
+            "unit_label": "元/百万"
+          }
+        ]
+      },
+      {
+        "filters": {"model": "qwen3.7-max"},
+        "filter_labels": {"模型": "qwen3.7-max"},
+        "price_factors": [
+          {
+            "factor": "cached_tokens",
+            "label": "缓存tokens",
+            "unit_price": 1.2,
+            "unit": "百万",
+            "unit_label": "元/百万"
+          }
+        ]
+      }
+    ],
+    "display_text": "【通义千问 qwen3.7-max】定价:\n  - 非缓存tokens: 6.0 元/百万\n  - 缓存tokens: 1.2 元/百万"
+  }
+}
+```
+
+**返回示例（视频生成定价）：**
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "ppid": "vidu_video_pricing",
+    "name": "viduq3视频定价",
+    "pricing_type": "per_use",
+    "items": [
+      {
+        "filters": {"model": "viduq3-turbo", "resolution": "1080p", "off_peak": "0"},
+        "filter_labels": {"模型": "viduq3-turbo", "分辨率": "1080p", "错峰": "0"},
+        "price_factors": [
+          {
+            "factor": "duration",
+            "label": "时长",
+            "unit_price": 0.56,
+            "unit": "秒",
+            "unit_label": "元/秒"
+          }
+        ]
+      }
+    ],
+    "display_text": "【viduq3视频定价】定价:\n  - 时长: 0.56 元/秒 [model=viduq3-turbo, resolution=1080p, off_peak=0]"
+  }
+}
+```
+
+**返回字段说明：**
+
+- `ppid`: 定价项目 ID
+- `name`: 定价项目名称
+- `pricing_type`: 定价类型（`per_use` 按次计费）
+- `items`: 定价项列表
+  - `filters`: 过滤条件（如适用模型、分辨率等）
+  - `filter_labels`: 过滤条件的中文标签
+  - `price_factors`: 计价因子列表
+    - `factor`: 因子字段名
+    - `label`: 因子中文名称
+    - `unit_price`: 单位价格（已转换为展示价，无需再乘）
+    - `unit`: 单位（百万、秒、次等）
+    - `unit_label`: 单位标签（元/百万、元/秒等）
+    - `tiered`: 阶梯定价（仅当价格不同时展示）
+- `display_text`: 人类可读的价格表文本
+
+---
+
+## pricing_data 使用指南
+
+### 两种格式
+
+pricing_data 支持两种格式：
+
+#### 1. 新格式（推荐）：price_factors + unit_prices + unit
+
+适用于简单定价场景，直接指定计价因子和单位价格。
+
+**示例 1：Token 定价（文本生成）**
+
+```yaml
+unit_values:
+  百万: 1000000
+fields:
+  model:
+    type: str
+    role: filter
+    label: 模型
+  uncache_tokens:
+    type: float
+    role: factor
+    label: 非缓存tokens
+  cached_tokens:
+    type: float
+    role: factor
+    label: 缓存tokens
+  completion_tokens:
+    type: float
+    role: factor
+    label: 输出tokens
+pricings:
+  # 非缓存输入定价
+  - price_factors: uncache_tokens
+    unit_prices: 6.0
+    unit: 百万
+    filters:
+      - model: qwen3.7-max
+  
+  # 缓存输入定价
+  - price_factors: cached_tokens
+    unit_prices: 1.2
+    unit: 百万
+    filters:
+      - model: qwen3.7-max
+  
+  # 输出定价
+  - price_factors: completion_tokens
+    unit_prices: 18.0
+    unit: 百万
+    filters:
+      - model: qwen3.7-max
+```
+
+**示例 2：视频生成定价（多维度过滤）**
+
+```yaml
+unit_values:
+  次: 1
+fields:
+  model:
+    type: str
+    role: filter
+    label: 模型
+  resolution:
+    type: str
+    role: filter
+    label: 分辨率
+  duration:
+    type: int
+    role: filter
+    label: 时长(秒)
+    value_mode: between
+  off_peak:
+    type: str
+    role: filter
+    label: 错峰执行
+  flat:
+    type: float
+    role: factor
+    label: 固定费用
+pricings:
+  - price_factors: flat
+    unit_prices: 85.0
+    unit: 次
+    filters:
+      - model: viduq2-pro
+      - resolution: 1080p
+      - duration: '1'
+      - off_peak: false
+  
+  - price_factors: flat
+    unit_prices: 43.0
+    unit: 次
+    filters:
+      - model: viduq2-pro
+      - resolution: 1080p
+      - duration: '1'
+      - off_peak: true
+  
+  - price_factors: duration
+    unit_prices: 0.56
+    unit: 秒
+    filters:
+      - model: viduq3-turbo
+      - resolution: 1080p
+      - off_peak: 0
+```
+
+#### 2. 旧格式：formula（公式计算）
+
+适用于复杂定价场景，使用 Python 表达式计算金额。
+
+**示例：按 Token 数量计算**
+
+```yaml
+fields:
+  model:
+    type: str
+    role: filter
+    label: 模型
+  prompt_tokens:
+    type: float
+    role: factor
+    label: 输入tokens
+  completion_tokens:
+    type: float
+    role: factor
+    label: 输出tokens
+pricings:
+  - model: gpt-4
+    formula: (3.2 * prompt_tokens + 16 * completion_tokens) / 1000000.0
+  
+  - model: gpt-3.5
+    formula: (0.5 * prompt_tokens + 1.5 * completion_tokens) / 1000000.0
+```
+
+### 关键规则
+
+1. **unit_values 必须定义**：在 pricing_data 顶部定义 `unit_values`，如 `百万: 1000000`，用于单位换算
+2. **unit_prices 存储展示价**：新格式中 `unit_prices` 直接存储展示价格（如 `6.0` 表示 6.0 元/百万），不需要再乘以单位值
+3. **filters 支持两种格式**：
+   - 列表格式：`filters: [{model: xxx}, {resolution: yyy}]`
+   - 字典格式：直接作为字段写在 pricing 条目中
+4. **value_mode 默认精确匹配**：不指定时做 `=` 精确匹配，可指定 `between`、`in`、`>`、`<` 等
+5. **formula 可引用任意字段**：旧格式中 formula 可引用 config_data 中的任意字段名
+6. **多条件匹配**：如果多条定价规则都匹配，全部返回（不是只返回第一条）
+
+---
+
 ## 关键设计要点
 
 1. **YAML 驱动定价规则**：所有定价逻辑用 YAML 描述，支持字段定义、选项、匹配模式、计算公式