> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 计量器配置

> GET /v1/meters — 查询 App 计费计量器（公开端点）

查询指定 App 的计费计量器（Meter）配置。Meter 定义了事件名到积分价格的映射关系，是 Events API 扣费的依据。

```
GET https://api.profy.cn/v1/meters?app_uuid={app_uuid}
```

## 认证

<Note>
  此端点**无需认证**，是公开接口。你可以在客户端直接调用以获取 Meter 配置，向用户展示功能定价。
</Note>

## 查询参数

<ParamField query="app_uuid" type="string" required>
  App 的 UUID。在创建 App 时生成，可在 App 设置页面找到。
</ParamField>

## 请求示例

<CodeGroup>
  ```python Python theme={null}
  import httpx

  async with httpx.AsyncClient() as http:
      resp = await http.get(
          "https://api.profy.cn/v1/meters",
          params={"app_uuid": "your-app-uuid"},
      )
      meters = resp.json()["meters"]
      for m in meters:
          print(f"事件: {m['eventName']} → {m['priceCredits']} 积分")
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch(
    "https://api.profy.cn/v1/meters?app_uuid=your-app-uuid"
  );
  const { meters } = await resp.json();

  for (const m of meters) {
    console.log(`事件: ${m.eventName} → ${m.priceCredits} 积分`);
  }
  ```

  ```bash curl theme={null}
  curl "https://api.profy.cn/v1/meters?app_uuid=your-app-uuid"
  ```
</CodeGroup>

## 响应

```json theme={null}
{
  "meters": [
    {
      "eventName": "image_generation",
      "priceCredits": 50,
      "description": "每次图片生成"
    },
    {
      "eventName": "video_render",
      "priceCredits": 200,
      "description": "每次视频渲染"
    },
    {
      "eventName": "export_pdf",
      "priceCredits": 10,
      "description": "每次 PDF 导出"
    }
  ]
}
```

## Meter 对象

| 字段             | 类型               | 说明                             |
| -------------- | ---------------- | ------------------------------ |
| `eventName`    | `string`         | 事件名称，在 `POST /v1/events` 中使用此值 |
| `priceCredits` | `number`         | 每次事件扣除的积分数                     |
| `description`  | `string \| null` | Meter 的文字描述                    |

<Note>
  Meter 的具体积分价格由 App 开发者在袋袋 Studio 中配置。以产品内实时显示为准。
</Note>

## 使用场景

### 在 App 中展示价格

在用户使用付费功能之前，调用此端点展示积分价格：

```typescript theme={null}
async function loadPricing(appUuid: string) {
  const resp = await fetch(
    `https://api.profy.cn/v1/meters?app_uuid=${appUuid}`
  );
  const { meters } = await resp.json();
  return new Map(meters.map((m: any) => [m.eventName, m.priceCredits]));
}

const pricing = await loadPricing("your-app-uuid");
const imagePrice = pricing.get("image_generation"); // 50
```

### 在上报前校验事件名

```python theme={null}
async def report_event(client, event_name: str, idem_key: str):
    async with httpx.AsyncClient() as http:
        resp = await http.get(
            "https://api.profy.cn/v1/meters",
            params={"app_uuid": "your-app-uuid"},
        )
        valid = {m["eventName"] for m in resp.json()["meters"]}

    if event_name not in valid:
        raise ValueError(f"未知事件: {event_name}")

    return await client.events.report(event_name, idempotency_key=idem_key)
```

## 与 Events API 的关系

```
Meters API (GET)                Events API (POST)
  查询 Meter 配置          →      上报事件
  [eventName, price]              [event, idempotency_key]
                                        ↓
                                  根据 eventName 匹配 Meter
                                        ↓
                                  按 priceCredits 扣除积分
```

1. 在袋袋 Studio 中为 App 配置 Meter（事件名 + 价格）
2. App 通过 `GET /v1/meters` 获取配置，在界面展示价格
3. 用户使用付费功能时，App 通过 `POST /v1/events` 上报事件
4. 袋袋根据 Meter 配置扣除用户积分

## 错误码

| HTTP 状态码 | 说明                 |
| -------- | ------------------ |
| `400`    | 缺少 `app_uuid` 查询参数 |

## 下一步

<CardGroup cols={2}>
  <Card title="上报计费事件" icon="bolt" href="/zh/developers/api/events">
    上报自定义计费事件
  </Card>

  <Card title="构建袋袋 App" icon="grid-2" href="/zh/developers/app-development">
    完整的 App 开发流程
  </Card>
</CardGroup>