快速入门 · Pauli 文档

输入 OpenQASM 3，输出正准 counts。完整的顺利路径；每个字段都在API 参考中，原始规范见 /openapi.json。

0 · 获取密钥

创建工作区，取得管理员密钥；下面的每个客户端都从环境变量读取密钥：

auth

export PAULI_API_KEY=pauli_sk_…   # shown once at creation; rotate any time

1 · Qiskit

注册表中的每台设备都是一个 Qiskit BackendV2：选一台、运行、按 Qiskit 自己的键序读取 counts。运行固定在您选定的后端上，绝不静默回退：

install

pip install qiskit-pauli   # Python ≥ 3.10

run_ghz.py

from qiskit import QuantumCircuit
from qiskit_pauli import PauliProvider

qc = QuantumCircuit(3, 3)                 # GHZ
qc.h(0); qc.cx(0, 1); qc.cx(0, 2)
qc.measure(range(3), range(3))

provider = PauliProvider()                # reads PAULI_API_KEY
backend = provider.least_busy(simulator=True)  # drop simulator=True for hardware
counts = backend.run(qc, shots=1000).result().get_counts()
print(counts)                             # {'000': 489, '111': 511}

本页其余部分都通过 provider.client 完成，它是每个后端之下完整的带类型客户端：金额是精确的 Decimal（传 float 会抛异常），每次提交自动携带幂等键，异常与下方的稳定错误码一一对应。

2 · 为整个设备群估价（免费）

一次调用即可在每台符合条件的设备上为您的电路估价，并给出预计队列、保真度与带理由的排除项：

estimate.py

from qiskit import qasm3

client = provider.client                  # the full pauli-sdk client
fleet = client.jobs.estimate(qasm3.dumps(qc), shots=1000)
for e in fleet.estimates:                 # cheapest first
    print(e.device, e.amount, e.predicted_queue_seconds, e.fidelity_score)
for x in fleet.excluded:                  # reasoned exclusions, complete
    print(x.device, x.reasons[0].code)

ionq.simulator 0.000000 1.0 1.0
ionq.qpu.forte-enterprise-1 2.700000 6871.0 0.953

3 · 按策略提交

从 cheapest、fastest、highest_fidelity、balanced 中选择；可钉住某台设备，也可按提供商、价格、队列或区域加约束。作业会立即返回路由决定与精确成本；每次提交都带有幂等键（不传则自动生成），因此重试绝不会重复提交：

submit.py

job = client.jobs.submit(qasm3.dumps(qc), shots=1000,
                         policy="highest_fidelity", only=["ionq"],
                         allow_simulator_fallback=True, max_spend_usd="10.00",
                         idempotency_key="exp-042-run-7",
                         webhook_url="https://example.com/hooks/pauli")
print(job.routing_decision.selected_device, job.cost_estimate.amount)

执行前的失败会回退到下一台最优设备（设 allow_fallback=False 可禁用）；每一跳都有记录，您只为真正执行的那台设备付费。

4 · 轮询，或使用 Webhook

wait

job.wait()   # jittered backoff to a terminal state; timeout=… to bound it
# created → validating → estimating → queued → transpiling → submitted → running → completed

指定 webhook_url（仅限 https）后，每次状态变更都会 POST 一次，并用提交密钥的 Webhook 密文（创建密钥时显示）签名；请按 X-Pauli-Event-Id 去重：

verify_webhook.py

import hashlib, hmac, time

def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    pairs = [p.split("=", 1) for p in header.split(",")]  # header: X-Pauli-Signature
    t = next(v for k, v in pairs if k == "t")
    if abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, v) for k, v in pairs if k == "v1")

SDK 已内置此验签流程：pauli_sdk.webhooks.unwrap(body, headers, secret=…)。

5 · 结果：统一的比特顺序

GET /v1/jobs/{id}/results

{
  "counts": {"000": 489, "111": 511},
  "bit_ordering": "cbit0_left",
  "register_map": {"c": ["q[0]", "q[1]", "q[2]"]},
  "metadata": {"provider_job_id": "…", "calibration_snapshot_id": "…"},
  "insights": {"shape": "cat_pair", "confidence": "high", "headline": "GHZ-like cat state: …"},
  "billing": {"billed_usd": "2.470000"}
}

counts 约定：每个键最左边的字符是最先声明的寄存器的经典比特 0；多个寄存器按声明顺序展平。所有提供商都归一到这一约定；分析代码永远不用分支。

Insights：直方图形态的参考分类（猫态、均匀分布、周期梳、Porter-Thomas 斑纹……），带通俗标题和考虑 shots 数的置信度，只由 counts 推导。仅作阅读辅助，绝非评分依据。

6 · 您自己的凭证（BYOK）

注册凭证（/console/credentials 或 PUT /v1/credentials/{provider}）后，该提供商上的作业将在您的账户下运行：提供商直接向您收费；您的钱包只支付平台服务费（定价）。估价、状态与结果都会显示 byok；回退绝不跨越计费模式。

7 · 智能体（MCP）

Model Context Protocol 位于 https://pauli.xyz/mcp（Streamable HTTP），使用同一个 bearer 密钥。工具与本页流程一一对应。

mcp client config

claude mcp add --transport http pauli https://pauli.xyz/mcp \
  --header "Authorization: Bearer $PAULI_API_KEY"

8 · 在智能体中付款

付费提交超出余额时返回 402 billing.insufficient_credits；其 detail 是一份付款挑战，写明缺口金额、充值端点以及如何确认到账。充值（充值返回托管的 checkout_url，由人来完成），然后用同一个 Idempotency-Key 重新提交。自动充值（PATCH /v1/billing/settings）会在作业遇到 402 之前从已保存的卡补足。MCP 工具结果原样携带同一份挑战。

另外两个 402，billing.monthly_cap_exceeded 与 billing.key_cap_exceeded，是您自设的上限，不带挑战。若支出符合预期，请调高上限。

错误

每个错误都是 {"error": {"code", "message", "detail?", "request_id"}}，错误码稳定；完整注册表见 /public/errors。联系支持时请附上 request_id。最先遇到的几个：

错误码	含义
program.invalid	OpenQASM 3 解析失败；detail 给出行与列。
routing.no_feasible_device	在您的约束下没有设备能运行该程序；detail 列出每台设备的原因。
billing.insufficient_credits	402：补足缺口后重新提交（第 8 节）。