智能体计算机 API

基础 URL

https://api.rebyte.ai/v1

认证

每个请求都需要一个 API_KEY 标头。从设置 > API 密钥获取您的密钥。

curl https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_your_key_here"

标头名称不区分大小写。API_KEY、api-key 和 x-api-key 都有效。

端点

Method	Path	Description
POST	`/tasks`	创建任务
GET	`/tasks`	列出任务
GET	`/tasks/:id`	获取带状态和提示历史的任务
POST	`/tasks/:id/prompts`	发送后续提示
PATCH	`/tasks/:id/visibility`	更改任务可见性
DELETE	`/tasks/:id`	软删除任务
GET	`/tasks/:id/events`	执行事件的 SSE 流
POST	`/files`	获取签名文件上传 URL
POST	`/webhooks`	注册 Webhook
GET	`/webhooks`	列出 Webhook
GET	`/webhooks/:id`	获取 Webhook 详情
DELETE	`/webhooks/:id`	删除 Webhook
所有路径都相对于基础 URL (`https://api.rebyte.ai/v1`)。

任务

创建任务

POST /tasks

创建一个新任务。默认情况下，会预置一个新的 VM (智能体计算机)。传递 workspaceId 以在现有工作区上运行任务——这会跳过预置过程，速度会快得多。

此调用会阻塞，直到 VM 预置完成并提交第一个提示。

请求体：

Field	Type	Required	Description
`prompt`	string	Yes	任务描述（最多 100,000 个字符）
`executor`	string	No	`claude` (default), `gemini`, `codex`, `opencode`
`model`	string	No	执行器的模型层级。参见模型。
`workspaceId`	string	No	要重用的现有工作区的 UUID
`files`	object[]	No	来自 `POST /files` 的文件。每个：`{"id": "...", "filename": "..."}`
`skills`	string[]	No	技能 slug（例如，`["deep-research", "pdf"]`）
`githubUrl`	string	No	`owner/repo` 格式的 GitHub 仓库
`branchName`	string	No	分支名称（默认值：`main`）

curl -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a REST API with Express and add tests",
    "executor": "claude",
    "skills": ["deep-research"],
    "githubUrl": "your-org/your-repo"
  }'

响应 (201)：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
  "url": "https://app.rebyte.ai/run/550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "createdAt": "2026-01-28T12:00:00.000Z"
}

保存响应中的 workspaceId，以便在同一智能体计算机上创建后续任务：

# First task -- provisions a new VM
RESP=$(curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" -H "Content-Type: application/json" \
  -d '{"prompt": "Set up the project"}')
WS_ID=$(echo $RESP | jq -r '.workspaceId')

# Second task -- reuses the same VM (much faster)
curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" -H "Content-Type: application/json" \
  -d "{\"prompt\": \"Now add tests\", \"workspaceId\": \"$WS_ID\"}"

模型

可用模型取决于执行器：

Executor	Available Models	Default
`claude`	`claude-sonnet-4.6`, `claude-opus-4.6`, `gemini-3.1-pro`, `gpt-5.3-codex`, `gpt-5.4`, `minimax-m2.7`, `kimi-k2.5`, `glm-5`, `gemini-3-flash`	`claude-sonnet-4.6`
`codex`	`gpt-5.4`, `gpt-5.3-codex`	`gpt-5.4`
`gemini`	`auto-gemini-3` (auto-routes between flash and pro)	`auto-gemini-3`
`opencode`	Same as `claude`	`gemini-3.1-pro`

使用 BYOK（自带 API 密钥）时，只有执行器原生提供商的模型可用（例如，使用 BYOK 的 claude 执行器只能获得 claude-sonnet-4.6 和 claude-opus-4.6）。

列出任务

GET /tasks?limit=50&offset=0

返回通过 API 创建的任务，按创建时间排序（最新优先）。

Param	Type	Default	Description
`limit`	number	50	每页结果数（最多 100）
`offset`	number	0	分页偏移量

curl "https://api.rebyte.ai/v1/tasks?limit=10" \
  -H "API_KEY: rbk_xxx"

响应：

{
  "data": [
    {
      "id": "550e8400-...",
      "url": "https://app.rebyte.ai/run/550e8400-...",
      "title": "Build REST API with Express",
      "executor": "claude",
      "model": "claude-sonnet-4.6",
      "createdAt": "2026-01-28T12:00:00.000000+00:00",
      "completedAt": "2026-01-28T12:05:00.000000+00:00"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

获取任务

GET /tasks/:id

返回完整的任务详情，包括提示历史和派生状态。

curl https://api.rebyte.ai/v1/tasks/550e8400-... \
  -H "API_KEY: rbk_xxx"

响应：

{
  "id": "550e8400-...",
  "url": "https://app.rebyte.ai/run/550e8400-...",
  "status": "running",
  "title": "Build REST API with Express",
  "executor": "claude",
  "model": "claude-sonnet-4.6",
  "createdAt": "2026-01-28T12:00:00.000000+00:00",
  "completedAt": null,
  "prompts": [
    {
      "id": "660e8400-...",
      "status": "running",
      "submittedAt": "2026-01-28T12:05:00.000000+00:00",
      "completedAt": null
    },
    {
      "id": "550e8400-...",
      "status": "succeeded",
      "submittedAt": "2026-01-28T12:00:01.000000+00:00",
      "completedAt": "2026-01-28T12:03:00.000000+00:00"
    }
  ]
}

任务状态 从提示状态派生：

Status	Condition
`running`	任何提示处于 `pending` 或 `running` 状态
`completed`	所有提示都已终止，最新提示为 `succeeded`
`failed`	所有提示都已终止，最新提示为 `failed`
`canceled`	所有提示都已终止，最新提示为 `canceled`

发送后续提示

POST /tasks/:id/prompts

向正在运行或已完成的任务发送后续提示。如果 VM 已停止，它将自动恢复。

Field	Type	Required	Description
`prompt`	string	Yes	后续提示（最多 100,000 个字符）
`skills`	string[]	No	此提示的附加技能 slug

curl -X POST https://api.rebyte.ai/v1/tasks/550e8400-.../prompts \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Now add authentication with JWT"}'

响应 (201)：

{
  "promptId": "770f9500-..."
}

流式传输事件 (SSE)

GET /tasks/:id/events

为任务的最新提示打开一个 Server-Sent Events 流。事件包括智能体输出（stdout、stderr）、工具调用和完成信号。

curl -N https://api.rebyte.ai/v1/tasks/550e8400-.../events \
  -H "API_KEY: rbk_xxx"

该流发出两种事件类型：

event — 执行事件（智能体输出、工具调用）
done — 带有完成状态的最终事件，然后流关闭

更改可见性

PATCH /tasks/:id/visibility

Field	Type	Required	Description
`visibility`	string	Yes	`private` (私有), `shared` (共享), or `public` (公开)

Level	Who can view
`private`	只有 API 密钥所有者
`shared`	所有组织成员（默认）
`public`	任何拥有链接的人（只读）

curl -X PATCH https://api.rebyte.ai/v1/tasks/550e8400-.../visibility \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "public"}'

当设置为 public 时，响应包含一个用于未经认证访问的 shareUrl。

删除任务

DELETE /tasks/:id

软删除任务。返回 204 No Content。

curl -X DELETE https://api.rebyte.ai/v1/tasks/550e8400-... \
  -H "API_KEY: rbk_xxx"

文件

上传文件以附加到任务。使用两步签名 URL 流程。

步骤 1：获取上传 URL

POST /files

Field	Type	Required	Description
`filename`	string	Yes	文件名（最多 255 个字符）
`contentType`	string	No	MIME 类型（默认值：`application/octet-stream`）

响应 (201)：

{
  "id": "550e8400-...",
  "filename": "data.csv",
  "uploadUrl": "https://storage.googleapis.com/...",
  "maxFileSize": 52428800
}

上传 URL 在 1 小时后过期。

步骤 2：上传文件

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @data.csv

步骤 3：附加到任务

在创建任务时，传递步骤 1 中的 id 和 filename：

{
  "prompt": "Analyze the uploaded data",
  "files": [
    {"id": "550e8400-...", "filename": "data.csv"}
  ]
}

文件在执行开始时会自动复制到任务的 VM 中。

Webhook

当任务事件发生时接收 HTTP POST 通知。Webhook 是通用的——它们会针对您组织中的所有任务触发，无论这些任务是通过 API、UI 还是任何其他渠道创建的。

事件

Event	Fires when
`task.created`	创建新任务时
`task.running`	智能体开始执行时
`task.completed`	任务成功完成时
`task.failed`	任务失败时
`task.canceled`	任务被用户取消时

创建 Webhook

POST /webhooks

Field	Type	Required	Description
`url`	string	Yes	HTTPS 端点 URL
`events`	string[]	Yes	要订阅的事件
`description`	string	No	人类可读的标签（最多 500 个字符）
`secret`	string	No	预共享密钥（最多 500 个字符）。设置后，每次交付时都会作为 `X-Webhook-Secret` 标头包含在内。

# Webhook without secret
curl -X POST https://api.rebyte.ai/v1/webhooks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["task.completed", "task.failed"]
  }'

# Webhook with pre-shared secret
curl -X POST https://api.rebyte.ai/v1/webhooks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["task.completed", "task.failed"],
    "secret": "my-shared-secret-value"
  }'

响应 (201)：

{
  "id": "880e8400-...",
  "url": "https://your-server.com/webhook",
  "events": ["task.completed", "task.failed"],
  "description": null,
  "hasSecret": true,
  "isActive": true,
  "createdAt": "2026-01-28T12:00:00.000Z",
  "lastTriggeredAt": null,
  "failureCount": 0
}

行为说明：

重复 URL：两次注册相同的 URL 会返回现有 Webhook（幂等）
限制：每个组织最多 3 个 Webhook。第 4 个会返回 limit_exceeded。
密钥存储：密钥值永远不会在任何响应中返回。只暴露 hasSecret: true/false。

列出 Webhook

GET /webhooks

返回您组织的所有 Webhook 及其状态信息（lastTriggeredAt、failureCount、isActive）。密钥永远不会暴露。

获取 Webhook

GET /webhooks/:id

删除 Webhook

DELETE /webhooks/:id

返回 204 No Content。已删除的 Webhook 会立即停止接收交付。

交付

当任务事件与 Webhook 订阅的事件匹配时，Rebyte 会向 Webhook URL 发送一个 HTTP POST 请求。

有效载荷：

{
  "event": "task.completed",
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1706443200,
  "data": {
    "status": "succeeded",
    "taskUrl": "https://app.rebyte.ai/run/550e8400-...",
    "result": "Created CSV file with 10 Hacker News posts..."
  }
}

status — 提示状态：pending (task.created)、running (task.running)、succeeded (task.completed)、failed (task.failed)、canceled (task.canceled)
taskUrl — Rebyte UI 中任务的直接链接（始终存在）
result — 最终 AI 输出文本（在终止事件中存在：task.completed、task.failed、task.canceled；在 task.created 和 task.running 中不存在）

调用 GET /tasks/:id 获取完整的任务详情，包括提示历史。

交付标头：

Header	Always present	Description
`Content-Type`	是	`application/json`
`X-Webhook-Signature`	是	Base64 编码的 RSA-SHA256 签名
`X-Webhook-Timestamp`	是	Unix 时间戳（秒）
`X-Webhook-Secret`	仅当配置了密钥时	您在创建时设置的预共享密钥值

超时：交付在 10 秒后超时。

故障处理：

交付是即发即弃的——失败时不会自动重试
非 2xx 响应会增加 failureCount
在连续 10 次失败后，Webhook 会自动禁用 (isActive: false)
成功交付会将 failureCount 重置为 0

签名验证

每次交付都使用您组织的 RSA-2048 密钥对进行签名，无论是否配置了预共享密钥。

工作原理：

Rebyte 连接 {timestamp}.{body}（例如，1706443200.{"event":"task.completed",...}）
使用您组织的私钥通过 RSA-SHA256 签署字符串
在 X-Webhook-Signature 中发送 Base64 编码的签名

获取您的公钥：联系支持人员或从 Rebyte 控制面板检索。RSA-2048 密钥对在首次创建 Webhook 时自动生成，并为组织持久保存。

验证示例 (Node.js)：

const crypto = require('crypto');

function verifyWebhook(rawBody, timestamp, signature, publicKey) {
  const payload = `${timestamp}.${rawBody}`;
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(payload);
  return verifier.verify(publicKey, signature, 'base64');
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const rawBody = req.body; // must be raw string, not parsed JSON
  const timestamp = req.headers['x-webhook-timestamp'];
  const signature = req.headers['x-webhook-signature'];

  if (!verifyWebhook(rawBody, timestamp, signature, PUBLIC_KEY)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  console.log(`Task ${event.taskId}: ${event.event}`);
  res.status(200).send('OK');
});

验证示例 (Python)：

from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
import base64

def verify_webhook(raw_body: str, timestamp: str, signature: str, public_key_pem: str) -> bool:
    public_key = serialization.load_pem_public_key(public_key_pem.encode())
    payload = f"{timestamp}.{raw_body}".encode()
    try:
        public_key.verify(
            base64.b64decode(signature),
            payload,
            padding.PKCS1v15(),
            hashes.SHA256()
        )
        return True
    except Exception:
        return False

两层安全

Webhook 支持两种可同时使用的独立验证方法：

Method	Header	How it works	Use case
RSA signature	`X-Webhook-Signature`	证明有效载荷来自 Rebyte 的加密证据	防篡改验证
Pre-shared secret	`X-Webhook-Secret`	您在创建时设置的静态字符串，在每次交付中回显	简单的共享密钥检查

RSA 签名始终存在。预共享密钥是可选的——如果您想要更简单的验证路径，请在创建 Webhook 时设置它。

轮询示例

完整示例：创建一个任务，轮询直到完成，然后发送一个后续提示。

# Create task
TASK_ID=$(curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Write a Python CLI that converts CSV to JSON"}' | jq -r '.id')

echo "Task: https://app.rebyte.ai/run/$TASK_ID"

# Poll until done
while true; do
  STATUS=$(curl -s https://api.rebyte.ai/v1/tasks/$TASK_ID \
    -H "API_KEY: rbk_xxx" | jq -r '.status')
  echo "Status: $STATUS"
  [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]] && break
  sleep 5
done

# Send a follow-up
curl -s -X POST https://api.rebyte.ai/v1/tasks/$TASK_ID/prompts \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Now add support for nested JSON objects"}'

错误格式

所有错误都遵循此结构：

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body"
  }
}

Code	HTTP Status	Description
`missing_api_key`	401	未提供 `API_KEY` 标头
`invalid_api_key`	401	无效或过期的 API 密钥
`validation_error`	400	请求体验证失败
`not_found`	404	资源不存在或不可访问
`limit_exceeded`	400	组织限制已达到（例如，最大 Webhook 数量）
`agent_disabled`	403	此组织禁用了请求的执行器
`internal_error`	500	服务器端故障

速率限制

API 目前不强制执行每个密钥的速率限制。每个 POST /tasks 都会预置一个真实的 VM，因此成本随使用量而变化。请使用 Webhook 而非频繁轮询来减少不必要的请求。