API 总览与认证 - 阿里云百炼 Agent Studio

Sandbox API 兼容 E2B 协议，提供沙箱实例的生命周期管理与模版管理能力。管控面请求经百炼 AI 网关转发。

前提条件

API 基地址按工作空间与地域拼装：

https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/agentstudio/sandbox

全部请求通过 HTTP Header 携带百炼 API Key：

Authorization: Bearer <your-api-key>

使用 E2B SDK 时，SDK 必填的 X-API-Key / api_key 仅用于满足 E2B 协议格式，百炼侧不使用它做业务鉴权。推荐填写 e2b_${ALIYUN_UID}。

兼容 E2B 协议的接口返回体贴近 E2B 原生响应结构，不封装为百炼统一 Result<T> 结构。

能力	方法	路径
创建实例	`POST`	`/sandboxes`
列举实例	`GET`	`/v2/sandboxes`
获取实例	`GET`	`/sandboxes/{sandboxID}`
连接实例	`POST`	`/sandboxes/{sandboxID}/connect`
暂停实例	`POST`	`/sandboxes/{sandboxID}/pause`
恢复实例	`POST`	`/sandboxes/{sandboxID}/resume`
释放实例	`DELETE`	`/sandboxes/{sandboxID}`

能力	方法	路径
创建模版	`POST`	`/v3/templates`
列举模版	`GET`	`/v2/templates`
获取模版	`GET`	`/templates/{templateCode}`
更新模版	`PUT`	`/templates/{templateCode}`
获取构建状态	`GET`	`/templates/{templateCode}/builds/{buildID}/status`
删除模版	`DELETE`	`/templates/{templateCode}`

调用出错时，接口返回的错误响应如下：

{
  "code": 100004,
  "message": "参数缺失",
  "requestID": "request-id"
}

常见 HTTP 状态码含义如下：

Sandbox 当前对外提供兼容 E2B 协议的 HTTP API。各接口的方法、路径与响应结构贴近 E2B 官方定义，除更新模版为百炼自定义协议外，其余接口的通用字段与语义可参阅 E2B 官方 API 文档：

本文仅列出百炼侧已支持的接口与百炼扩展字段。百炼侧的鉴权、Endpoint 与扩展配置以本文为准；通用协议字段可对照 E2B 官方文档理解。

除直接调用 REST 接口外，还可通过 E2B 官方 SDK 接入。详见实例管理与使用。