快速开始

本页目录

用自己的程序直接调用 Marvnor，完成“保存一条事实 → 核验 → 删除本次测试记录”。无需下载客户端或安装 SDK。

不写代码接入？使用连接 AI 工具，配置方法见大模型接入。下面只介绍直接调用 API。

1. 准备 API Key

登录客户中心，创建并复制 API Key，确认账户有可用额度。统一使用环境变量 MARVNOR_API_TOKEN，不要把 Key 发给大模型或放进网页代码。

Windows PowerShell：

powershell

$env:MARVNOR_API_TOKEN = [System.Net.NetworkCredential]::new('', (Read-Host 'Marvnor API Key' -AsSecureString)).Password

macOS / Linux 的 Bash 终端（使用 zsh 时先运行 bash）：

bash

read -r -s -p 'Marvnor API Key: ' MARVNOR_API_TOKEN
export MARVNOR_API_TOKEN
printf '\n'

在同一终端运行下一步；变量只对本次终端及其启动的程序生效。示例需要 Python 3，无需第三方依赖；也可跳过环境变量，运行时按隐藏输入提示粘贴 Key。

2. 运行示例

将代码保存为 marvnor_demo.py。Windows 运行 py -3 marvnor_demo.py，macOS / Linux 运行 python3 marvnor_demo.py。示例产生少量真实 API 用量，只删除自己新建的演示记录，不会执行全部清空。

python

import getpass
import json
import os
import urllib.error
import urllib.request
import uuid

BASE_URL = "https://api.marvnor.com"
API_KEY = os.environ.get("MARVNOR_API_TOKEN") or getpass.getpass("Marvnor API Key: ")


def request(method, path, payload=None):
    body = None if payload is None else json.dumps(payload, ensure_ascii=False).encode("utf-8")
    req = urllib.request.Request(
        BASE_URL + path,
        data=body,
        method=method,
        headers={
            "Authorization": "Bearer " + API_KEY,
            "Content-Type": "application/json",
        },
    )
    try:
        with urllib.request.urlopen(req, timeout=60) as response:
            return json.load(response)
    except urllib.error.HTTPError as error:
        raise SystemExit(f"HTTP {error.code}（{path}）：请查看下方错误说明。") from None
    except (urllib.error.URLError, OSError):
        raise SystemExit(
            f"网络连接失败或超时（{path}）。请检查网络、代理/VPN 和 Python TLS 证书配置；"
            "不要关闭证书校验。程序没有自动重试。写入可能已保存，请保留测试编号按文档清理。"
        ) from None


demo_id = "demo-" + uuid.uuid4().hex
fact = {
    "source": demo_id,
    "relation": "status",
    "target": "paid",
    "client_record_id": demo_id,
}
print("本次测试编号：", demo_id)
written = request("POST", "/v1/relations", {"relations": [fact]})
record_id = written["record_ids"][0]
print("写入成功：", written["ok"])

query = {"questions": [{
    "id": "check",
    "source": demo_id,
    "relation": "status",
    "target": "paid",
}]}
try:
    answer = request("POST", "/v1/evaluate", query)["answers"]["check"]
    print("核验结果：", json.dumps(answer, ensure_ascii=False))
finally:
    deleted = request("POST", "/v1/relations/delete", {"record_ids": [record_id]})
    print("删除本次测试记录：", deleted["deleted_count"])

after = request("POST", "/v1/evaluate", query)["answers"]["check"]
print("删除后：", after["conclusion"])

3. 核对结果

正常情况下，写入后返回 TRUE、conflict: false，本次删除数量为 1，删除后查询为 UNKNOWN。答案只有 conclusion、conflict、reason、path、decision、evidence_kind 六字段。

如果写入时超时，记录可能已经保存。用打印出来的测试编号，按自定义编号删除清理，不要清空整个 Key。

401：检查 Key 是否有效。
402：检查可用额度。
400：按接口说明核对字段；429：按响应中的 Retry-After 等待；5xx：服务暂时异常，先确认写入状态，不重复提交。
UNKNOWN：核对命名、Key、范围和时间，不要当作否定结论。
conflict: true：核对冲突值，不让大模型自行择一。

遇到网络提示，先确认此电脑能打开 API 文档，再检查系统代理或 HTTP_PROXY / HTTPS_PROXY 指向的代理是否正在运行。浏览器能打开不代表 Python 使用了相同的代理或证书配置；TLS 失败时核对系统时间与 Python 的受信证书，不要关闭 HTTPS 校验。仍失败时把错误码、发生步骤和测试编号发给客服，不要发送 Key。

你已完成最小调用流程。正式接入时，在自己的业务系统保存原始事实、记录凭证和来源的对应表，再按大模型接入说明只发送当前问题及相关结果。