从仿真画面，
接入动作预测。

视觉动作 API · 实验版

kine-a1

两张 RGB256 仿真画面与 state8 输入，返回 50×7 动作。用于指定仿真操作任务的接口集成与对照实验，尚未通过完整任务验收，不保证任务成功。

在线调用 ↗ · 完整输入协议与模型卡 ↗ · 充值 / 余额 ↗

下载下列两个文件到同一目录，将机器人当前原始相机PNG保存为agent.png和wrist.png，把下面state替换为同一仿真时刻的末端位置XYZ、轴角XYZ、两个夹爪关节位置：

curl -fsS https://kineworld.com/sdk/kinejing_client.py -o kinejing_client.py
curl -fsS https://kineworld.com/sdk/visual_action.py -o visual_action.py
export KINEJING_API_KEY='你的 API Key'
python visual_action.py --image agent.png --wrist wrist.png \
  --state '[0.0,0.0,0.5,0.0,0.0,0.0,0.02,-0.02]' --ack-experimental

脚本会显示幂等编号。网络中断后，输入文件和state保持不变，并加--idempotency-key 原编号重试，最多扣一次。HTTP错误不表示任务效果；模型输出不得直接用于真实机器人。

从状态出发，预测动作后果

kinejing-state-pusht-v1

三成员模型集成，权重在勘境服务器本地执行。输入两帧推手位置、T 形物体位置与角度，以及后续动作目标；输出 1 至 16 步状态，每步 0.1 秒。无需外部预训练模型或视觉编码器。

32 个新测试 episode 的前三步合并 T 块位置 RMSE 为 9.54 像素，对照 ridge 为 16.10、静止预测为 24.64。多步测试使用根据真实状态反馈采集的记录动作，其中包含未来状态信息；结果仅支持这套模拟分布下的离线预测比较。

阅读模型卡、评估与限制 ↗ · 查看闭环测试的负结果 ↗ · 模型清单与权重身份 ↗

注册 → 充值 → 创建 Key → 调用

1. 在开发者控制台注册并登录。
2. 打开充值 / 余额，选择金额后使用支付宝付款。确认收款后自动增加 API 可用余额，无需等待公司银行结算。
3. 在控制台创建 API Key，并保存完整密钥；完整密钥只显示一次。
4. 从你的服务端执行下面的示例，或打开在线调用页。成功调用按控制台确认的规则计量，响应返回预测与用量收据。示例状态是合成数值，不能证明模型效果。

POST https://kineworld.com/v1/rollouts

以下为 Bash 示例，使用 Python 3 生成唯一幂等编号。将 Key 替换为你在控制台创建的密钥。

export KINEJING_API_KEY='替换为你的 API Key'
cat > request.json <<'JSON'
{
  "model": "kinejing-state-pusht-v1",
  "state_schema": "pusht-512xy-angle-rad-v1",
  "action_schema": "pusht-absolute-xy-10hz-v1",
  "context_states": [
    [230.0, 230.0, 256.0, 256.0, 0.1],
    [231.0, 232.0, 256.0, 256.0, 0.1]
  ],
  "actions": [[280.0, 280.0], [290.0, 280.0], [300.0, 280.0]]
}
JSON
IDEMPOTENCY_KEY=$(python3 -c 'import uuid; print(uuid.uuid4())')
curl --fail-with-body https://kineworld.com/v1/rollouts \
  -H "Authorization: Bearer $KINEJING_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json

集成应用时将密钥保存在服务端环境变量，不要硬编码进网页、客户端安装包或公开仓库。本站在线演示允许你在可信设备手填临时 Key，仅在页面内存使用并发送给同源 API；用后清除或撤销。为每个新预测生成新编号；网络结果不确定时，先查调用记录，再使用原编号重试。

ACCOUNT RECOVERY

提前保存一次性离线恢复码

登录控制台后，打开“账号安全”，输入当前密码并主动生成一组 8 枚恢复码。完整码仅显示一次，请保存在你控制的离线位置或密码管理器；平台只存摘要，不能再次取回完整码。重新生成整组码后，旧组全部失效。

忘记密码时，在登录页选择恢复入口，填写账户邮箱、尚未使用的恢复码与新密码。成功后需要重新登录，原有会话和全部 API Key 失效；请重新创建应用所需的 Key。余额、订单和历史收据保留，已接受的在途预测仍可能完成并正常计量。每枚码只可使用一次，怀疑泄露时请登录后轮换整组。

当前没有邮件验证或邮件找回。未提前保存可用恢复码且忘记密码时，此自助流程无法恢复账户；支持人员不会仅凭一个未验证邮箱交付账号。不要向支持人员发送密码、Key 或恢复码。

状态和动作使用原始坐标

核对预测，也核对用量

成功响应中，predicted_states 的形状为 [T, 5]，字段顺序与输入状态相同；time_step_seconds 为 0.1。响应同时包含模型、权重摘要、billing 与用量收据，便于复现和排查。

不提供免费调用。每次成功调用按控制台确认的规则计量，余额不足时不能调用；失败推理释放预留款项。在充值 / 余额使用支付宝充值，确认收款后自动增加 API 可用余额，无需等待公司银行结算。该页面显示可用余额、充值订单和付款状态；调用费用可在控制台查看。微信支付暂未开放。对公转账需按控制台订单操作，财务核对公司网银真实到账后入账。

计算完成并记录成功后，客户端网络中断仍可能已结算。控制台保留调用元数据，不保留完整输入或预测结果供重放。详情见 API 条款与隐私说明。

PYTHON CLIENT

下载客户端，直接发起预测

Python 3.10 及以上，无需第三方依赖。将 kinejing_client.py 与 rollout.py 下载到同一目录，在终端设置自己的 KINEJING_API_KEY，运行 python rollout.py。示例使用公开的合成状态，不代表真实客户任务验证。

from kinejing_client import KineJingClient

client = KineJingClient()  # 从 KINEJING_API_KEY 读取
result = client.rollout(
    context_states=[[230,230,256,256,0.1], [231,232,256,256,0.1]],
    actions=[[280,280], [290,280], [300,280]],
)
print(result["predicted_states"])

客户端保留同一个幂等编号，依据重试调度预算，最多重试两次连接错误、429 或暂时不可用响应。401、402、409、422 直接报错；限流遵循服务返回的 Retry-After，预算不够则停止；网络超时受 socket、DNS 与操作系统语义影响，并非硬性总墙钟时限。请保留异常中的幂等编号，响应丢失后用相同内容和编号恢复，不要为不确定的请求立即换新编号。

FILE INPUT & RECOVERY

用自己的状态文件调用

下载 Python 客户端、rollout_file.py 和 状态 JSON 模板，放在同一目录。将模板改为你按上方协议采集的两帧状态和动作。模板本身是合成数据，不能作为模型效果证据。

python rollout_file.py prepare --input request.state.example.json --run-dir my-run
python rollout_file.py run --run-dir my-run

第一步不需要 Key，也不联网：校验输入并在新目录中保存固定请求及幂等编号。第二步使用环境变量 KINEJING_API_KEY 中的个人密钥调用官网，成功时将响应和收据写入 my-run/result.json，成功时从可用余额扣费。

超时或中断后，保留目录和原 Key，再运行第二条命令，恢复同一请求。已有匹配结果则从本地读取，不再调用。不要修改记录或为结果不明的调用另建目录。活动锁或结果片段会阻止盲目重发；仅在确认原进程已停止后手动移除遗留的 active.lock，保留并检查未完成结果。

文件中保存你选择的输入、输出与收据，不保存 Key。请放在受限目录，勿上传或提交 Git。摘要仅检查记录一致性，不是可信签名；本机锁和文件同步不提供跨电脑协调或断电保证。该样例不改变模型能力和收费规则。

RELIABILITY & SCOPE

可追踪、可恢复，范围明确

应用响应头提供 X-Request-ID 和 X-KineJing-API-Version。错误 JSON 保留 detail，另提供 error.type、error.message 和 request_id。反馈故障时提供请求编号，勿发送密码或完整 Key。代理层拒绝的请求可能由 Nginx 返回，格式可能不同。

客户端默认发送 X-KineJing-Replay: recover。已完成付费调用的同一 Key、幂等编号和请求内容，使用固定模型重新计算输出，不新增收据或重复扣费；历史赠送调用不能重新执行（402 trial_disabled），旧记录保留；idempotent_replay: true 表示恢复结果，预测的 request_id 与原收据一致，响应头编号标识本次尝试。它不保存原始输入或输出，也不是读取缓存；耗时等运行元数据可能变化。仍在执行或已经释放的失败请求返回 409，应先检查收据；已明确失败并退款后，可用新编号重新发起。

当前仍是单机研究预览：模型限定二维 PushT 状态协议，没有任意图像/视频输入或真实机器人效果保证；暂不提供 SLA、邮件找回、自动银行到账核销或异机容灾承诺。已提供需提前保存的一次性离线恢复码，详见账户恢复说明。收费使用前请按 模型卡验证自己的任务。即时健康检查只表示当前在线，不代表长期可用率。

原有三视角特征预测接口

kinejing-dynamics-v0.1

POST https://kineworld.com/v1/predict

保留原有动作条件特征研究模型。视觉特征依赖 Meta DINOv2；勘境训练的是预测部分，输出为九个时刻的数值特征。它与上方状态模型使用不同协议，不能互换输入。

请求中的 model 使用本节模型名。同样使用 Bearer Key 和唯一幂等编号。响应包含 predicted_features，不生成视频，不直接控制机器人。零向量结构模板只用于接口检查，不能作为模型效果证据。