Draft · 接口设计草案 v0.1

开放 API 接口　设计草案

Programmable cloud workspace, compute and canvas

把工作站、算力与画布接入你自己的系统——这是设想，尚未实现

下面描述的是我们规划中的统一 REST 接口：覆盖工作站生命周期、GPU 任务提交、画布对象读写与智能体触发，配合密钥鉴权与 Webhook 回调，目标是可直接嵌入现有流水线。目前尚未开放，无法注册，也无法调用。

DRAFT · 拟议中的调用形态

# ⚠ 该端点尚未上线，以下请求不会返回任何数据
curl -X POST https://api.orbitwork.cloud/v1/jobs \
  -H "Authorization: Bearer $ORBITWORK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inference",
    "image": "orbitwork/base:latest",
    "gpu": { "tier": "pro", "count": 1 },
    "command": "python run.py --steps 30"
  }'

仅用于说明拟议中的接口形态：路径、字段、鉴权方式与返回结构都可能调整，且不保证最终按此实现。

Roadmap

规划中的接入流程

以下步骤描述的是我们希望最终达成的开发者体验，目前一步都还没实现，也没有可以申请的 API Key。

获取密钥

规划：控制台支持创建 API Key，并按需限定权限范围。

调用接口

规划：使用 Bearer Token 调用 REST 接口提交与管理任务。

接收回调

规划：配置 Webhook，任务状态变化实时推送到你的服务。

获取产物

规划：任务完成后通过接口或签名链接下载结果。

API Reference

拟议接口一览

下表是我们在规划阶段列出的接口范围，用于说明产品的能力边界。所有条目的状态均为「草案」，路径、参数与返回结构都可能改动。

当前状态：全部未实现。向这些路径发起请求不会得到 JSON 响应，也不会有鉴权或限流逻辑——它们现在只是文档里的文字。上线前我们会另发正式文档与变更说明。

方法	路径	说明	状态
POST	/v1/workspaces	创建云工作站实例	草案
GET	/v1/workspaces	列出当前账号下的工作站	草案
POST	/v1/workspaces/{id}/start	启动指定工作站	草案
POST	/v1/workspaces/{id}/stop	停止指定工作站	草案
POST	/v1/jobs	提交 GPU 任务（训练 / 推理 / 渲染）	草案
GET	/v1/jobs/{id}	查询任务状态与日志	草案
DELETE	/v1/jobs/{id}	取消并释放任务资源	草案
GET	/v1/gpus	查询可用算力档位与余量	草案
GET	/v1/canvases/{id}/nodes	读取画布节点	草案
POST	/v1/canvases/{id}/nodes	写入或更新画布节点	草案
POST	/v1/tasks	向调度智能体下达意图任务	草案
GET	/v1/usage	查询用量与费用明细	草案

Draft Examples

拟议中的调用示例

两段示例分别对应我们设想的 SDK 与裸 HTTP 调用方式。它们是设计稿，不是可复制运行的代码：orbitwork 这个包目前不存在，api.orbitwork.cloud 也没有后端服务。

JavaScript · 草案

// ⚠ orbitwork 包尚未发布，此示例仅为形态示意
import { OrbitWork } from "orbitwork";

const ow = new OrbitWork(process.env.ORBITWORK_KEY);

// 提交一个推理任务并等待结果
const job = await ow.jobs.create({
  type: "inference",
  gpu: { tier: "pro", count: 1 },
  command: "python run.py"
});

const done = await ow.jobs.waitFor(job.id, {
  timeout: 1800,
  onProgress: (p) => console.log(p.step)
});

console.log(done.artifacts);

Python · 草案

import os, requests

# ⚠ 该域名当前无后端，以下请求不会成功
BASE = "https://api.orbitwork.cloud/v1"
H = {"Authorization": f"Bearer {os.environ['ORBITWORK_KEY']}"}

# 1) 查看可用算力
tiers = requests.get(f"{BASE}/gpus", headers=H).json()

# 2) 提交训练任务
job = requests.post(f"{BASE}/jobs", headers=H, json={
    "type": "training",
    "gpu": {"tier": "ultra", "count": 4},
    "command": "torchrun train.py --epochs 10",
}).json()

# 3) 轮询状态
status = requests.get(f"{BASE}/jobs/{job['id']}", headers=H).json()
print(status["state"], status["metrics"])

Conventions

约定与限制

以下是我们为将来正式版设定的目标约定，属于设计意图说明，当前没有任何一项在生效。

鉴权

Authentication

所有请求需在 Header 中携带 Authorization: Bearer <API_KEY>。

错误码

Errors

使用标准 HTTP 状态码，错误体包含 code 与 message 字段。

限流

Rate Limit

按账号维度限流，响应头返回剩余配额；超限返回 429。

回调

Webhook

任务状态变化时推送事件，建议校验签名后处理。

接口尚未开放

OrbitWork 目前处于品牌与产品规划阶段，没有可申请的 API Key，也没有可用的端点。如果你想了解规划进展、反馈接口设计，或在开放后第一时间收到通知，欢迎来信。

邮件联系 [email protected] 返回品牌首页 →

开放 API 接口 设计草案