← 全部范例范例 01
调用前先预估：免费为任何操作报价
你将构建： 一个两步模式：先为调用报价，再对照预算检查，通过后才真正执行。最终你会得到一个可以包裹目录中任何操作的辅助函数。
| 分类 | API 基础 |
|---|---|
| 使用的操作 | POST /v1/data/{action}:estimatePOST /v1/data/contacts/find-email |
| 积分 | 免费 —— 这些端点从不计费 |
| 测试密钥可用 | 是 —— 可在 qk_test_ 上运行，零积分 |
| 预计耗时 | ~5 分钟 |
| 前置条件 | 一个工作区、一把 qk_test_ 或 qk_live_ 密钥，以及 curl 或任意 HTTP 客户端。 |
预估端点
每个计费操作都有对应的预估。取操作路径，追加 :estimate，再发送你本来就要发送的同一个请求体。你会拿到这次具体调用的积分成本，而询问本身不收费。
estimate.sh
# Append :estimate to any action path. Costs nothing.
curl -X POST https://api.qannasapi.com/v1/data/contacts/find-email:estimate \
-H "Authorization: Bearer $QANNAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "Jane Doe, Acme Logistics"}'读取报价
响应使用标准信封 —— status、request_id、data —— 报价就在 data 里。由于预估免费，预估响应上的 X-Credits-Charged 恒为 0。
estimate response
# < HTTP/1.1 200 OK
# < X-Credits-Charged: 0 # asking is always free
{
"status": "OK",
"request_id": "req_...",
"data": { /* the quote for this exact call */ }
}报价、检查、再运行
有用的形态是一道闸门：先预估，与你自己的预算比较，通过了才执行。两次调用用的是同一个请求体，所以这道闸门只多花你一次请求，零积分。
quote_then_call.py
import os, requests
API = "https://api.qannasapi.com"
HEADERS = {"Authorization": f"Bearer {os.environ['QANNAS_API_KEY']}"}
def quote_then_call(action, body, budget):
# 1 — free quote, same body as the real call
quote = requests.post(
f"{API}/v1/data/{action}:estimate", json=body, headers=HEADERS
).json()
# 2 — gate on your own budget before spending anything
if cost_of(quote) > budget:
raise RuntimeError("quote exceeds budget")
# 3 — run it
return requests.post(
f"{API}/v1/data/{action}", json=body, headers=HEADERS
)工作流的报价方式相同
服务端工作流用 dry_run 代替 :estimate 后缀 —— 发送 dry_run: true 就能拿到逐步明细，且不会真正执行。同样的思路，同样的零成本。
workflow-quote.sh
# Workflows use dry_run instead of a :estimate suffix.
curl -X POST https://api.qannasapi.com/v1/data/workflows/lead-list \
-H "Authorization: Bearer $QANNAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inputs": {"industry": "logistics"}, "limit": 25, "dry_run": true}'
# < X-Credits-Charged: 0 # a dry run never bills小结
| 模式 | 做法 |
|---|---|
| 为操作报价 | POST /v1/data/{action}:estimate，带上你打算发送的请求体 |
| 为工作流报价 | POST /v1/data/workflows/{name}，带 dry_run: true |
| 预估的成本 | 零 —— 预估的 X-Credits-Charged 恒为 0 |
| 信封 | { status, request_id, data } —— 预估与真实调用完全一致 |
| 这个数字的含义 | 最坏情况，假设每一步都能找到结果 |
上线检查清单
- 把昂贵的或由用户触发的调用放在预估闸门之后。
- 按预估做预算，再按 X-Credits-Charged 对账。
- 余额为零时报价依然可用 —— 预估永远免费。
- 预估要发送与真实调用相同的请求体，否则报价不会吻合。
下一步
先运行预估。它不花任何费用，用的正是计量器将要套用的那套算术。