在你的应用中直接调用 HTTPS API。本手册全程使用 curl 与 JSON。
访问与凭证
在账户门户注册账户、验证邮箱并创建 API 密钥。密钥只显示一次。多个密钥共享同一账户的文件、任务、钱包与配额。
使用 HTTPS,并在每个普通 API 请求中携带 Authorization: Bearer。密钥管理、账户限额、支付写入与运营操作需要安全浏览器会话。会话写入还需要同源的 Origin 请求头,以及来自 matvenus_csrf Cookie 的 X-CSRF-Token。普通的 * 作用域不授予运营访问权限。
将 MATVENUS_API_URL 设为你的平台源地址,把 MATVENUS_API_KEY 设为你的密钥,并保存在受保护的环境中。不要把凭证写入源文件或共享的命令输出。
curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" "$MATVENUS_API_URL/v1/me"
curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" "$MATVENUS_API_URL/v1/tools?offset=0&limit=20"
JSON 与文件
提交前先查看已发布的工具版本及其输入契约。REQUEST_PATH 必须指向你的 JSON 请求文件,其中包含 tool_id、tool_version 与 parameters。请按该版本调整参数;不存在通用的科研输入契约。
输入可以是纯 JSON、属于本账户的 READY file_id 引用、multipart 附件,或它们的组合。multipart 包含一个 payload JSON 字段与若干唯一命名的文件分部;每个上传引用都必须与对应分部匹配。文件内容不可变。
例如,文件槽可以使用 {"file_id":"FILE_UUID"},或使用 {"upload":"sequence_file"} 并附上 sequence_file 分部。嵌套与列表文件槽遵循工具契约。大文件字节保留在私有存储中。
下方的版本化示例给出完整的序列请求与 READY 文件请求两种 request.json。REST 上传响应会返回文件 id;引用前请确认状态为 READY。使用工具的实际字段名,不要使用本地路径或通用的 sequence_file 槽位。
curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" \ -F "file=@$FILE_PATH" "$MATVENUS_API_URL/v1/files"
提交与重试
为每个逻辑提交选定一个稳定的 SUBMISSION_KEY,并与原始请求一起保存。响应不确定后重试时两者都要复用。同一密钥且语义相同时返回原任务;请求内容改变则返回 409。新的科研任务需要新密钥。
HTTP 202 表示已持久受理,并固定了工具、绑定、价格与授权快照,同时完成最低金额冻结、输入保护和输出空间预留。它不代表执行或交付成功。请把返回的 id 保存为 JOB_ID。
省略 max_amount 时使用账户默认值,初始为 CNY 500.00。已受理的授权在执行期间不能提高。账户设置只对新建任务生效。
curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" -H "Idempotency-Key: $SUBMISSION_KEY" \ -H "Content-Type: application/json" --data-binary "@$REQUEST_PATH" "$MATVENUS_API_URL/v1/jobs"
状态、结果与取消
轮询记录的状态与阶段。取消请求与确认停止是两回事。在可信的执行与结算证据允许释放前,冻结会一直保留;结果未知时不得触发替代计算。
通过 /v1/jobs/{id}/input 显式读取已受理的归一化输入。任务元数据包含文件引用与摘要,而不是科研 JSON。通过 /v1/jobs/{id}/result 读取完整结构化输出,并通过授权的文件端点下载声明的输出文件。
有效的空结果(例如 hits=[])属于成功交付。尚未交付返回 409 RESULT_NOT_READY;仅输出文件类契约返回 404 RESULT_NOT_DEFINED。结果被删除或过期返回 410,并保留任务与费用摘要。绝不要把 410 理解为有效的空结果。
私有输入默认自就绪起保留 30 天,结果默认自交付起保留 30 天。活跃输入与尚未终结的源结果继续受保护。JSON 输入/结果与文件共享字节配额。
GET /v1/files/quota 返回本账户的 limit_bytes、used_bytes 与 reserved_bytes,包含私有 JSON 以及待处理的上传与任务输出预留。这些是账户总量,与当前文件分页无关。首次使用前,它返回配置的默认上限与零用量,且不会创建配额记录。账户门户显示相同的只读数值;不提供配额修改、CLI 命令或 MCP 工具。
curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" "$MATVENUS_API_URL/v1/jobs/$JOB_ID"
curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" "$MATVENUS_API_URL/v1/jobs/$JOB_ID/input"
curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" "$MATVENUS_API_URL/v1/jobs/$JOB_ID/result"
curl --silent --show-error --fail-with-body -X POST \ -H "Authorization: Bearer $MATVENUS_API_KEY" "$MATVENUS_API_URL/v1/jobs/$JOB_ID/cancel"
费用与余额
金额为 CNY 十进制字符串。赠额与充值余额及其冻结彼此独立;可用资金不含冻结。赠额先用,无有效期且不可退款。默认赠额 CNY 10.00 只发放一次,可配置。
按次工具在成功持久交付后计费一次,包含有效的空搜索结果。按时计费依据实际分配的资源时间,含初始化、不含排队时间。已确认的用户取消、超时以及资金或授权保护触发的停止按实际用时计费。平台、输入、工具与最终交付失败免费。
按时任务在原授权额度内追加冻结。若资金不足以继续执行,平台会请求停止,并在结算前确认停止。未知用量保持待定,而不是记为零。试点期间不提供在线充值与支付订单。
curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" "$MATVENUS_API_URL/v1/balance"
隐私与错误
科研输入与输出保留在私有存储中,不用于训练。长期保留的任务与账务记录只保存必要摘要;日志与消息不包含原始科研数据、API 密钥或长期下载链接。
错误返回 code、message 与 request_id。跨账户访问私有资源返回 404。求助时使用 request_id;诊断材料中不要包含凭证与科研数据。遇到 409 冲突与 410 过期请先检查,而不是自动重复写操作。
用量与原始消费
用量按任务创建时间统计。GET /v1/usage 返回满足筛选条件的完整合计与一页逻辑任务,按受理顺序倒序。total、settled_amount、held_amount 与 unsettled_jobs 覆盖全范围;items 只覆盖 offset/limit。重放仍是一个任务。此处的 settled_amount 指该范围内创建任务的最终费用,而不是该范围内结算的消费。
消费按原始 settle:job 账本记录时间统计。GET /v1/consumption 先合并赠额与充值来源行再统计任务,校验来源覆盖与最终费用,返回 settled_amount、gift_amount、paid_amount 与 settled_at。零费用结算仍保留记录。未结算任务没有结算时间,出现在用量中。充值、退款与后续审计调整不计入;调整后净费用与全范围导出不可用。
两个明细查询都接受 offset(默认 0)、limit(默认 50,最大 100)、tool_id、tool_version、api_key_id,或 no_api_key=true。两个密钥筛选互斥。已吊销密钥保留归属;他人账户的密钥返回 404。名称只是标签,分组由 ID 决定。这些是全账户报表,由所有已授权密钥共享,不是某个密钥的钱包或客户端渠道报表。
半开区间请使用带时区的 UTC 时刻:用量使用 created_from/created_before,消费使用 settled_from/settled_before。省略明细日期表示全部日期。门户默认显示浏览器 IANA 时区的最近 7 个日历日,截止到读取时刻;日历日可能是 23 或 25 小时。汇总端点必须同时给出两个边界,接受 timezone(默认 UTC),最多允许 366 个本地日历日。它们返回 range_from、range_before、timezone、observed_at、totals、days 以及完整的 by_tool/by_key 分组。用量还返回 by_status。分组按结算金额倒序,再按稳定 ID 与版本排序,最后返回全部分组。
每条报表语句观察同一个 PostgreSQL 快照。observed_at 标识该语句,而不是跨页面或独立请求共享的历史快照。刷新后合计可能因结算而变化。当前活跃(GET /v1/usage/current,state=active 或 needs_attention)忽略创建期间日期,接受相同的工具/版本/密钥范围与分页,并包含更早受理的任务。GET /v1/balance 是不受报表筛选影响的当前全账户快照;其时间戳为客户端显示的读取时间。
final_amount 为 null 表示未结算;0.00 是真实的已结算零。用量中旧的 usage_pending/usage_pending_jobs 字段表示未结算的按时计费任务,而不是已确认的异常。任务详情的 usage_pending 来自可信执行投影。未知资源用量永远不记为零。计费不使用客户端耗时。
消费的 coverage_gap_jobs 统计所选工具/密钥范围内,原始来源、时间或金额事实缺失或不一致的已结算任务,与日期边界无关。这类记录无法归属到已核实期间,因此不计入期间合计。计数大于零表示账单不完整;不会用某个完成日期替代。覆盖缺失时门户不显示完整的每日消费趋势。计数、零与不可用事实始终区分。
通过已授权会话或普通账户密钥以 usage:read 读取这些报表。受手机验证门禁的会话不能读取。新的 REST 报表不是 MCP 工具:get_usage 保留原参数与响应字段,包括原有的待定含义。新的 no_api_key 与 tool_version 筛选以及报表元数据仅限 REST。CLI 仍只有已记录的余额与任务命令;不隐含统计或账单导出命令。
curl --silent --show-error --fail-with-body --get \ -H "Authorization: Bearer $MATVENUS_API_KEY" \ --data-urlencode "created_from=2026-09-30T16:00:00Z" \ --data-urlencode "created_before=2026-10-23T04:00:00Z" \ --data-urlencode "offset=0" \ --data-urlencode "limit=20" \ "$MATVENUS_API_URL/v1/usage"
curl --silent --show-error --fail-with-body --get \ -H "Authorization: Bearer $MATVENUS_API_KEY" \ --data-urlencode "settled_from=2026-09-30T16:00:00Z" \ --data-urlencode "settled_before=2026-10-23T04:00:00Z" \ --data-urlencode "offset=0" \ --data-urlencode "limit=20" \ "$MATVENUS_API_URL/v1/consumption"
curl --silent --show-error --fail-with-body --get \ -H "Authorization: Bearer $MATVENUS_API_KEY" \ --data-urlencode "created_from=2026-09-30T16:00:00Z" \ --data-urlencode "created_before=2026-10-23T04:00:00Z" \ --data-urlencode "timezone=Asia/Shanghai" \ "$MATVENUS_API_URL/v1/usage/summary"
curl --silent --show-error --fail-with-body --get \ -H "Authorization: Bearer $MATVENUS_API_KEY" \ --data-urlencode "settled_from=2026-09-30T16:00:00Z" \ --data-urlencode "settled_before=2026-10-23T04:00:00Z" \ --data-urlencode "timezone=Asia/Shanghai" \ "$MATVENUS_API_URL/v1/consumption/summary"
curl --silent --show-error --fail-with-body --get \ -H "Authorization: Bearer $MATVENUS_API_KEY" \ --data-urlencode "state=active" \ --data-urlencode "offset=0" \ --data-urlencode "limit=20" \ "$MATVENUS_API_URL/v1/usage/current"
完整示例:蛋白性质
protein_properties_physicochemical@2026-10-14-candidate
正在检查该示例版本当前是否已发布…
用途与输入规则
从一条蛋白序列计算理化特征:长度、分子量、理论 pI 与氨基酸组成,以 JSON 返回。
该版本只返回理化特征,不生成蛋白结构,也不输出文件。公开示例是教学材料,不是一次新的计算,也不构成质量评估。
- sequence 与 fasta_file 必须且只能提供一个;另一个请省略或设为 null。同时提供或都不提供都会被拒绝。
- sequence 不能为空,且只能使用大写 ACDEFGHIKLMNPQRSTVWY。FASTA 必须包含一条非空序列并使用同一字母表;包含多条记录会被拒绝。
- task_name 固定为 Physical and chemical properties。省略时使用默认值,或按原样传入该常量;不支持其他任务。
- fasta_file 请使用属于本账户且状态为 READY 的文件。接受的格式为 fasta、fa 与 faa。本地路径不是 file_id。
- 工具输入上限为 134217728 字节。直接提交 JSON 任务(含元数据)上限为 131072 字节(128 KiB)。序列更大时请改用文件上传与 READY 引用。结构化结果上限为 65536 字节。
版本 2026-10-14-candidate。将下方完整公开请求体保存为 request.json。
将 MATVENUS_API_URL 设为你的 HTTPS 平台基础地址,并把 MATVENUS_API_KEY 放在受保护的环境中(或使用已有 CLI 登录)。为这个逻辑任务设置新的唯一 SUBMISSION_KEY;重试时保留同一密钥与完全相同的请求。新任务需要新密钥。
{
"tool_id": "protein_properties_physicochemical",
"tool_version": "2026-10-14-candidate",
"parameters": {
"sequence": "ACDEFGHIKLMNPQRSTVWY"
}
}REST API
请逐条执行命令:先核对确切版本并提交 request.json,再将 JOB_ID 设为 HTTP 202 回执中的 id。查询同一个任务,只有状态为 SUCCEEDED 后才能读取结果。
curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" \ "$MATVENUS_API_URL/v1/tools/protein_properties_physicochemical?version=2026-10-14-candidate" curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" \ -H "Idempotency-Key: $SUBMISSION_KEY" -H "Content-Type: application/json" \ --data-binary @request.json "$MATVENUS_API_URL/v1/jobs" curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" "$MATVENUS_API_URL/v1/jobs/$JOB_ID" curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" "$MATVENUS_API_URL/v1/jobs/$JOB_ID/result"
HTTP 202 表示已受理。即使客户端超时也请保留 Job ID。结果未就绪时返回 409,删除或过期后返回 410。失败或取消的任务可能没有结果。冲突重试返回 409;请检查原任务而非重新提交。
改用 FASTA 文件
将这份公开单记录样本保存为 public-sample.fasta,通过 REST 或 CLI 上传;MCP 不能上传二进制文件。确认返回的文件属于你的账户且状态为 READY。
此处展示的预期 JSON 对应直接序列输入,其 sequence_id 为 temp_sequence。使用 FASTA 输入时,sequence_id 来自记录头;本示例 FASTA 使用 public-sample。序列标识与平台任务 ID 是两回事。
>public-sample ACDEFGHIKLMNPQRSTVWY
先执行上传命令,再将 FILE_ID 设为返回的 id,并确认文件状态为 READY。
curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" \ -F "file=@public-sample.fasta" -F "purpose=input" "$MATVENUS_API_URL/v1/files" curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $MATVENUS_API_KEY" "$MATVENUS_API_URL/v1/files/$FILE_ID"
将文件 ID 占位符替换为该 READY 的 UUID,再存为 request.json 并用上面的 REST 或 CLI 步骤提交。这个不同的逻辑任务需要使用新的提交密钥。此时省略 sequence。
{
"tool_id": "protein_properties_physicochemical",
"tool_version": "2026-10-14-candidate",
"parameters": {
"fasta_file": {
"file_id": "REPLACE_WITH_READY_FILE_UUID"
}
}
}公开样本来源
仓库中的版本化材料;这些样本不能证明工具当前可用,以启用目录为准。
worker_groups/protein-properties-physicochemical/candidate-contract.jsonSHA-256: 17f0d36cc81729a3dcf225813df8253213faf19905ec99409962d1d33632497eworker_groups/protein-properties-physicochemical/public/sequence-request.jsonSHA-256: 83bbe6829d85d48aa0446a8646232b97012af7d058707a232c9057f7b1a1abe4worker_groups/protein-properties-physicochemical/public/expected-sequence-result.jsonSHA-256: 0353c5c39d8d9a9f0ae278655ba536f99611e112a41d3a064d8df885b76cb7f2worker_groups/protein-properties-physicochemical/public/public-sample.fastaSHA-256: 27b4df93ee69cfe9d6d92bc808a99f21a8272c20b3daab602138ec0d94e5df83
理解 JSON 结果
公开序列的完整预期输出。这是已存储的公开样本,不是本页面执行的计算。该版本没有输出文件。
{
"data": {
"sequence_id": "temp_sequence",
"sequence_length": 20,
"molecular_weight": 2395.71,
"theoretical_pI": 6.78,
"aromaticity": 0.15,
"instability_index": 84.74,
"gravy": -0.49,
"secondary_structure_fraction": {
"helix": 0.25,
"turn": 0.25,
"sheet": 0.35
},
"amino_acid_composition": {
"A": 0.05,
"C": 0.05,
"D": 0.05,
"E": 0.05,
"F": 0.05,
"G": 0.05,
"H": 0.05,
"I": 0.05,
"K": 0.05,
"L": 0.05,
"M": 0.05,
"N": 0.05,
"P": 0.05,
"Q": 0.05,
"R": 0.05,
"S": 0.05,
"T": 0.05,
"V": 0.05,
"W": 0.05,
"Y": 0.05
}
},
"success": true
}| 名称 | 类型 | 必填 | 说明 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
success | true | 是 | 有效的交付结果要求 success=true 且 data 非空。空对象对该工具不是有效结果。 · 固定为 true | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data | object | 是 | 不允许其他属性 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.sequence_id | string | 是 | 结果中的序列标识,与平台任务 ID 不同。 · 最短长度 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.sequence_length | integer | 是 | 以氨基酸残基计的序列长度。 · 最小值 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.molecular_weight | number | 是 | 分子量。契约未声明单位,待维护者确认。 · 大于 0 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.theoretical_pI | number | 是 | 理论等电点(pI),范围 0–14。 · 0–14(含边界) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.aromaticity | number | 是 | 芳香性数值,范围 0–1。以原始比值显示,不是百分比。 · 0–1(含边界) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.instability_index | number | 是 | 报告的不稳定指数;不推断稳定性评级。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.gravy | number | 是 | 报告的 GRAVY 亲水性指数;不推断质量评级。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.secondary_structure_fraction · 3 个字段 · 必填螺旋、转角与折叠的占比,各自 0–1。它们不必相加为 1,也不代表已生成的结构。 · 不允许其他属性
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data.amino_acid_composition · 20 个字段 · 必填二十种氨基酸的占比,各自 0–1。二十个字母键均为必填;0.05 表示占比 5%。 · 不允许其他属性
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||