amigos阿米奥机器人
API Reference

接入你的应用。

核心接口只有一个,以下为 0.1.0 版接口说明。

Endpoint 
https://jev.amigos-robot.com/v1/systemone

请求体:

{
 "state": "文本,或 JSON 对象/数组",
 "images": ["base64 串 或 http(s) URL 或 服务器本地路径"],
 "model": "jev-lite",
 "questions": {
 "<问题名>": {"type": "choice|score|noul", "instructions": "...", "criteria": ...}
 }
}
字段必填说明
state是状态信息:纯文本,或 JSON 对象/数组(服务端会序列化成文本)。受模型上下文长度 8192 token 限制,超长会被拒绝
images否最多 4 张,按数组顺序传给模型。三种来源任选:base64 串(裸串或 data URL)、 http(s) URL(服务端下载,超时 10 秒)、服务器本地路径。长边超过 1024px 的图会自动等比缩小。不支持视频
model否固定写 "jev-lite" 即可,仅回显
questions是键是问题名(只用于在答案里对应回你的问题,不进模型),值是问题定义,见下

① choice — 多选一

criteria 是一个非空对象:key 是选项名(答案里回显用),value 是该选项的描述。选项顺序即你书写顺序,最多 50 个。

"questions": {
 "下一步动作": {"type": "choice", "instructions": "机械臂当前应执行哪个动作?",
 "criteria": {"抓取": "目标物体在夹爪正下方且无障碍,直接闭合夹爪",
 "移动": "先移动夹爪到目标正上方再考虑抓取",
 "停止": "检测到人员靠近或异常情况,立即停下"}}
}

返回 choice(概率最高的选项)、probabilities(各选项概率,和为 1)、confidence(置信度,0~1,分布越集中越接近 1)、latency_ms。

② score — 有序等级打分

criteria 是长度 ≥2 的有序等级数组,从低到高排列。

"questions": {
 "抓取稳定性": {"type": "score", "instructions": "评估机械臂当前抓取的稳定程度",
 "criteria": ["不稳定", "较稳定", "非常稳定"]}
}

返回 score(概率加权后的期望下标,范围 [0, 档数-1],可落在两档之间)、probabilities(各档位概率)、legend(下标→档位映射)、confidence、latency_ms。

③ noul — 是/否二元

criteria 必须包含 true(是)和 false(否)两个键,value 是对应描述。

"questions": {
 "是否空抓": {"type": "noul", "instructions": "机械臂是否空抓?",
 "criteria": {"true": "夹爪闭合但没有抓到物体", "false": "夹爪抓到了物体"}}
}

返回 noul(P(是) 的概率,0~1)、confidence、latency_ms。

响应整体结构

{
 "model": "jev-lite",
 "latency_ms": 132.5,
 "answers": {
 "<问题名>": { "type": "...", "...": "见上方各类型说明" }
 }
}

Python 示例(带 base64 图片)

import base64, requests

with open("photo.jpg", "rb") as f:
 b64 = base64.b64encode(f.read()).decode()

r = requests.post("https://jev.amigos-robot.com/v1/systemone", json={
 "state": "机械臂执行抓取后的场景",
 "images": [b64],
 "model": "jev-lite",
 "questions": {
 "是否空抓": {"type": "noul", "instructions": "机械臂是否空抓?",
 "criteria": {"true": "夹爪闭合但没有抓到物体",
 "false": "夹爪抓到了物体"}}
 },
})
print(r.json()["answers"]["是否空抓"])
# {'type': 'noul', 'noul': 0.98, 'confidence': ..., 'latency_ms': ...}

错误码

状态码场景
200成功
422请求不合规:choice 选项超过 50 个;图像超过 4 张;图像下载/解码失败;问题类型或 criteria 格式不对;state + 图像总长度超过 8192;请求体字段类型错误
500服务内部异常(正常调用不应出现;遇到请带上出错时间反馈给维护者)

错误返回体统一为 {"detail": "<可读的错误信息>"}。

使用须知