API 文档

FieldQuantum API

乾坤云对外 HTTP API。一份 OpenQASM 2.0 电路 + 一个 token,直送量子云。

1. 认证

登录 /account/api-token 生成 token,格式 fq_<32hex>。所有请求 header 带:

Authorization: Bearer fq_xxx...

一个账号一个 token;重新生成会让旧 token 立刻失效。明文只在生成时显示一次,DB 只存 sha256 hash。

2. 提交任务 POST /api/v1/fieldquantum/task/run

Body(JSON):

{
  "qasm": "OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\ncreg c[2];\nh q[0];\ncx q[0],q[1];\nmeasure q -> c;\n",
  "mode": "sample",          // sample | expectation,默认 sample
  "shots": 1024,             // sample 模式必填
  // expectation 模式专属:
  "param_names":  ["theta"],
  "param_values": [1.5708],
  "hamiltonian": [
    { "coeff": 1.0,  "pauli": "ZZ" },
    { "coeff": -0.5, "pauli": "XI" }
  ]
}

响应:

{ "task_id": 123, "status": "submitted" }

后续用 task_id 拉状态 / 结果。

3. 查状态 GET /api/v1/fieldquantum/task/status/{id}

{
  "task_id": 123,
  "status":  "queued",      // submitted/queued/running/finished/failed/error
  "fqd_task_id": "603b549d-..."
}

建议轮询间隔 ≥ 3 秒。FieldQuantum 内部每 10 秒主动跟下游云算力对账,过短间隔不会让结果更早返回。

4. 拿结果 GET /api/v1/fieldquantum/task/result/{id}

finished 状态:

{
  "task_id": 123,
  "status":  "finished",
  "result": { /* 透传下游 shape — sample 模式返 counts;expectation 返 energy/expectations */ }
}

failed/error 状态:

{
  "task_id": 123,
  "status":  "failed",
  "error":   "..."
}

还在跑(queued/running/submitted)→ HTTP 425 Too Early:

{
  "error":   "result_not_ready",
  "status":  "queued",
  "message": "任务尚未完成,先调 /task/status/{id} 等到 status=finished"
}

5. 任务列表 GET /api/v1/fieldquantum/task/list?limit=20

{
  "items": [
    {
      "task_id":    123,
      "status":     "finished",
      "created_at": "2026-05-25T16:00:00Z",
      "updated_at": "2026-05-25T16:01:30Z"
    },
    ...
  ],
  "total": 42
}

limit 默认 20,最大 100。返当前 token 对应账号的全部任务。

6. 错误码

7. Python 示例

pythonimport time
import requests

BASE = "https://api.fieldquantum.tech/api/v1/fieldquantum"
TOKEN = "fq_xxx..."  # 从 /account/api-token 复制
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# 1) 提交
qasm = """OPENQASM 2.0;
include "qelib1.inc";
qreg q[2]; creg c[2];
h q[0]; cx q[0], q[1];
measure q -> c;
"""
r = requests.post(f"{BASE}/task/run", headers=HEADERS, json={
    "qasm": qasm, "mode": "sample", "shots": 1024,
})
r.raise_for_status()
task_id = r.json()["task_id"]
print("submitted", task_id)

# 2) 轮询(≥ 3s 间隔)
while True:
    s = requests.get(f"{BASE}/task/status/{task_id}", headers=HEADERS).json()
    print(s["status"])
    if s["status"] in ("finished", "failed", "error"):
        break
    time.sleep(3)

# 3) 拿结果
res = requests.get(f"{BASE}/task/result/{task_id}", headers=HEADERS).json()
print(res)