Cleer
申请接入

方式一 · 快速开始

quickstart.sh
curl -X POST https://api.cleerscience.com/v1/token \\
  -H "Content-Type: application/json" \\
  -d '{"grant_type": "client_credentials",
       "app_id": "app_xxx", "app_secret": "您的AppSecret"}'
→ {"access_token": "at-…", "expires_in": 7200}

curl -X POST …/v1/uploads -H "Authorization: Bearer $TOKEN" \\
  -H "Idempotency-Key: $(uuidgen)" \\
  -d '{"filename": "sample.csv", "content_type": "text/csv",
       "size": 102400, "sha256": "文件SHA-256"}'

curl -X POST …/v1/analyses -H "Authorization: Bearer $TOKEN" \\
  -H "Idempotency-Key: $(uuidgen)" \\
  -d '{"algorithm_id": "spectro-xrd-analysis",
       "inputs": [{"asset_id": "ast_…", "version": 1}]}'
→ 202 {"analysis_id": "run_…", "status": "queued"}

完整接入示例(Python,可直接运行)

下面是一段自足的端到端脚本:换 Token → 直传文件(含 SHA-256 锚定)→ 创建分析(幂等)→ 轮询到终态 → 逐份下载产物 → 查询用量。零第三方依赖(仅标准库),复制后替换 APP_ID / APP_SECRET / FILE_PATH 即可跑通。

e2e_demo.py(Python 3 标准库)
#!/usr/bin/env python3
"""Cleer 开放 API 端到端示例:Token → 直传 → 创建分析 → 轮询 → 下载产物 → 用量。
仅用 Python 标准库;替换 APP_ID / APP_SECRET / FILE_PATH 后可直接运行。
"""
import hashlib, json, mimetypes, time, uuid
import urllib.request, urllib.error

BASE = "https://api.cleerscience.com/v1"
APP_ID, APP_SECRET = "app_xxx", "sk_您的AppSecret"
FILE_PATH = "sample.csv"                       # 待分析文件
ALGORITHM = "spectro-xrd-analysis"             # 算法目录中选定的算法
TOKEN = ""


def call(method, path, headers=None, body=None, raw=None):
    """统一请求:JSON 体或原始字节(multipart),返回 (状态码, JSON|bytes)。"""
    req = urllib.request.Request(
        BASE + path, method=method,
        data=json.dumps(body).encode() if body is not None else raw,
        headers={"Content-Type": "application/json", **(headers or {})})
    try:
        resp = urllib.request.urlopen(req, timeout=120)
        data = resp.read()
        ct = resp.headers.get("content-type", "")
        return resp.status, json.loads(data) if ct.startswith("application/json") else data
    except urllib.error.HTTPError as e:
        try:
            return e.code, json.loads(e.read())
        except Exception:
            return e.code, {}


def bearer():
    return {"Authorization": "Bearer " + TOKEN}


# ① 用 AppID + AppSecret 换取 2 小时有效的 Bearer Token(贵司服务端保管 Secret)
code, tok = call("POST", "/token", body={
    "grant_type": "client_credentials",
    "app_id": APP_ID, "app_secret": APP_SECRET,
})
assert code == 200, tok
TOKEN = tok["access_token"]

# ② 直传文件(multipart 表单,携带 SHA-256 —— 平台分析前做完整性校验)
content = open(FILE_PATH, "rb").read()
sha256 = hashlib.sha256(content).hexdigest()
b = uuid.uuid4().hex  # multipart boundary
form = (f"--{b}\r\nContent-Disposition: form-data; name=\"sha256\"\r\n\r\n{sha256}\r\n"
       f"--{b}\r\nContent-Disposition: form-data; name=\"target_algorithm_id\"\r\n\r\n{ALGORITHM}\r\n"
       f"--{b}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"{FILE_PATH}\"\r\n"
       f"Content-Type: {mimetypes.guess_type(FILE_PATH)[0] or 'application/octet-stream'}\r\n\r\n")
raw = form.encode() + content + f"\r\n--{b}--\r\n".encode()
code, up = call("POST", "/uploads/direct",
                headers={**bearer(), "Content-Type": f"multipart/form-data; boundary={b}"},
                raw=raw)
assert code == 201, up
asset_ref = up["asset_ref"]                    # {"asset_id": "ast_…", "version": 1}

# ③ 创建分析(Idempotency-Key 让网络重试安全:同键不产生重复任务/计费)
code, created = call("POST", "/analyses",
                     headers={**bearer(), "Idempotency-Key": uuid.uuid4().hex},
                     body={"algorithm_id": ALGORITHM, "inputs": [asset_ref]})
assert code == 202, created
run_id = created["analysis_id"]
print("分析任务已受理:", run_id, created["status"])

# ④ 轮询到终态(建议 2s → 5s → 10s 退避;此处简化为固定 5s)
TERMINAL = {"succeeded", "failed", "cancelled", "timed_out"}
status = ""
while status not in TERMINAL:
    time.sleep(5)
    code, st = call("GET", f"/analyses/{run_id}", headers=bearer())
    status = st["status"]
print("终态:", status)
if status != "succeeded":
    raise SystemExit(f"任务失败:{json.dumps(st, ensure_ascii=False)[:500]}")

# ⑤ 读取结果信封并逐份下载产物(download_url 限时有效,从信封中取)
code, env = call("GET", f"/analyses/{run_id}/result", headers=bearer())
assert code == 200, env
# 输入锚点对账:结果回传的 sha256 与我们上传时申报的一致
assert env["inputs"][0]["sha256"] == sha256
for art in env["artifacts"]:
    url = art["download_url"]                 # 形如 …/v1/analyses/{id}/artifacts/{aid}/download
    code, data = call("GET", "/v1/" + url.split("/v1/", 1)[1], headers=bearer())
    assert code == 200
    open(art["filename"], "wb").write(data)
    print("已下载产物:", art["filename"],
          "sha256一致" if hashlib.sha256(data).hexdigest() == art["sha256"] else "校验失败")

# ⑥ 查询用量(by_algorithm / by_user 双维度,可做贵司自己的用户级计费)
code, usage = call("GET", "/usage", headers=bearer())
print("用量:", json.dumps(usage, ensure_ascii=False, indent=2))

机器可读契约(OpenAPI 3.1,Postman / Swagger / openapi-generator 可直接导入):下载 OpenAPI 规范(YAML)

怎么知道某算法要传什么参数?

调用 GET /v1/algorithms 查看目录,每个算法带三块信息:input_schema(接受的文件类型与数量——上传前先对照,格式不符会返回 422)、parameters_schema(运行参数定义)、mode(standard=提交即等结果;conversational=对话式,参数预填见右侧"对话式算法"章)。

目录中 parameters_schema 为空的算法(XRD/Raman/XPS/IR/MS/TEM)表示无必填参数,不传 parameters 字段即按默认配置运行;有参数定义的算法(如 NMR 的 mode/formula)按 schema 传 parameters,缺必填项在创建时即返回 422 并指明缺失字段,不会产生空等任务。