概览
Makers SDK 提供 TypeScript 与 Python 两种实现，让平台方以代码方式创建项目并完成部署。SDK 提供两种初始化方式：使用 Makers API Token，或使用腾讯云 API 密钥（SecretId / SecretKey）。无论采用哪种方式，项目管理、环境变量配置、部署、及域名等功能的调用方法、参数和返回值均保持一致。
安装
TypeScript 运行环境为 Node.js 20+，仅发布 ESM。Python 运行环境为 3.10+。
npm install @edgeone/makers-sdk
pip install makers-sdk
使用 API Token 初始化
1. 在控制台创建 API Token，步骤见 API Token。
2. 写入环境变量
MAKERS_API_TOKEN。3. 初始化 Makers SDK：
import { Makers } from "@edgeone/makers-sdk";const apiToken = process.env.MAKERS_API_TOKEN;if (!apiToken) {throw new Error("MAKERS_API_TOKEN is required.");}const makers = new Makers({token: apiToken,region: "china",});
import osfrom makers_sdk import Makersmakers = Makers(token=os.environ["MAKERS_API_TOKEN"],region="china",)
region 为可选参数，须与签发该 API Token 的工作空间一致："china" 对应中国站，"global" 对应国际站。若未指定 region，SDK 将依次自动探测中国站（china）与国际站（global）并将结果缓存在当前 Makers 实例中。使用腾讯云 API 密钥初始化
使用腾讯云 API 密钥初始化时需要 SecretId、SecretKey 和 Makers 工作空间 ID（ZoneId）。
1. 在腾讯云控制台的 API 密钥管理 创建 SecretId 与 SecretKey，写入环境变量
TENCENTCLOUD_SECRET_ID 与 TENCENTCLOUD_SECRET_KEY。如果是子账号，项目、环境变量、部署与域名需要授予 teo:DescribePagesResources、teo:CreatePagesResources、teo:ModifyPagesResources 与 teo:DeletePagesResources CAM 权限；通过 DescribeZones 查询工作空间 ID 时，需要授予 teo:DescribeZones 权限。
2. 获取 ZoneId。开通 Makers 时会自动创建一个 Makers 工作空间。调用腾讯云 API
DescribeZones 并按 zone-type 为 pages 过滤即可查到该工作空间的 ZoneId。将 ZoneId 写入环境变量 EDGEONE_MAKERS_ZONE_ID。3. 初始化 Makers SDK：
import { Makers } from "@edgeone/makers-sdk";const secretId = process.env.TENCENTCLOUD_SECRET_ID;const secretKey = process.env.TENCENTCLOUD_SECRET_KEY;const zoneId = process.env.EDGEONE_MAKERS_ZONE_ID;if (!secretId || !secretKey || !zoneId) {throw new Error("TENCENTCLOUD_SECRET_ID, TENCENTCLOUD_SECRET_KEY, and EDGEONE_MAKERS_ZONE_ID are required.",);}const makers = new Makers({credentials: { secretId, secretKey },zoneId,region: "global",});
import osfrom makers_sdk import Makersmakers = Makers(credentials={"secret_id": os.environ["TENCENTCLOUD_SECRET_ID"],"secret_key": os.environ["TENCENTCLOUD_SECRET_KEY"],},zone_id=os.environ["EDGEONE_MAKERS_ZONE_ID"],region="global")
构造参数
参数名与类型以
TypeScript / Python 的形式给出。参数 | 类型 | 必填 | 默认值 | 说明 |
token | string / str | - | - | EdgeOne Makers API Token。未传 credentials 时必填 |
timeout | number / float | 否 | 30 | 单次请求超时，单位为秒 |
retries | number / int | 否 | 3 | 查询类最大重试次数；写操作不重试 |
logger | Logger | 否 | - | 用于输出 SDK 日志。传入带 debug、info、warn、error 方法的对象，未传入时不输出日志 |
credentials | CloudApiCredentials / dict | 否 | - | 腾讯云 API 密钥。两个字段都必须是非空字符串。 |
zoneId / zone_id | string / str | - | - | Makers 工作空间 ID，使用 credentials 鉴权时必填 |
region | "china" | "global" | 否 | - | 指定 API 请求区域： "china" 为国内站，"global" 为国际站 |
公开成员
成员 | 类型 | 说明 |
makers.projects | Projects | 项目与环境变量操作 |
makers.deployments | Deployments | 部署操作 |
makers.domains | Domains | 自定义域名：创建、查询、删除，以及归属校验、CNAME 检查与 HTTPS 证书。 |
makers.tokens | Tokens | 签发租户 Token（ tokens.create） |
makers.region | "china" | "global" 或空 | 只读，构造时传入的中国站（china）或国际站（global） |
makers.kv | Kv | KV 命名空间查询与记录管理，仅支持腾讯云 API 密钥鉴权 |
类型名为 TypeScript 导出的类型，Python 的对应命名空间不作为公开类型导出。
错误处理
SDK 定义的错误类型以
MakersError 为基类，公开字段为 code、cause，以及 requestId / request_id 和 httpStatus / http_status。错误信息在 TypeScript 中通过 error.message 获取，在 Python 中通过 str(error) 获取。异常类 | 说明 |
AuthError | Token 或腾讯云 API 密钥无效，或无权访问 |
ValidationError | 入参不合法或服务端返回校验错误。本地校验在发请求前抛出 |
NotFoundError | 项目、部署或 Makers 工作空间不存在 |
ConflictError | 资源冲突 |
RateLimitError | 触发限流 |
UploadError | 上传制品失败 |
TimeoutError | 单次请求超时 |
DeploymentTimeoutError | 等待部署到达终态超时（继承 TimeoutError） |
import { Makers, MakersError, NotFoundError } from "@edgeone/makers-sdk";const apiToken = process.env.MAKERS_API_TOKEN;if (!apiToken) {throw new Error("MAKERS_API_TOKEN is required.");}const makers = new Makers({token: apiToken,region: "china",});try {await makers.projects.get({ projectId: "missing" });} catch (error) {if (error instanceof NotFoundError) {console.error(error.code, error.requestId, error.httpStatus);} else if (error instanceof MakersError) {console.error(error.code, error.message, error.requestId);} else {throw error;}}
import osfrom makers_sdk import Makers, MakersError, NotFoundErrormakers = Makers(token=os.environ["MAKERS_API_TOKEN"],region="china",)try:makers.projects.get(project_id="missing")except NotFoundError as error:print(error.code, error.request_id, error.http_status)except MakersError as error:print(error.code, str(error), error.request_id)
签发租户 Token
在需要隔离平台级凭证，降低 Makers API Token 泄漏风险的部署场景中，建议通过
tokens.create 签发权限受限的租户 Token 进行部署。初始化 Makers SDK 时，需传入账号级凭证：在控制台创建的主 API Token，或腾讯云 API 密钥（credentials 与 zoneId），再由 SDK 签发租户 Token。已签发的租户 Token 不支持查询或删除。调用成功后返回
token、tokenId / token_id 和 expired。expired 为过期时间，格式为 Unix 时间戳（秒）。对同一 tenantId / tenant_id 再次签发时，token 与 tokenId / token_id 不变，expired 可能更新。参数不符合要求时，将在发起请求前抛出 ValidationError。参数
参数 | 类型 | 必填 | 说明 |
tenantId / tenant_id | string / str | 是 | 租户标识，长度为 1–64 个字符 |
name | string / str | 是 | Token 名称，长度为 1–128 个字符 |
expiresIn / expires_in | number / int | 是 | 有效期，单位为秒；需为整数，取值范围为 10–315360000 |
示例
使用 API Token 签发：
import { Makers } from "@edgeone/makers-sdk";const apiToken = process.env.MAKERS_API_TOKEN;if (!apiToken) {throw new Error("MAKERS_API_TOKEN is required.");}const platform = new Makers({token: apiToken,region: "china",});const { token, tokenId, expired } = await platform.tokens.create({tenantId: "user-open-id",name: "user-open-id",expiresIn: 86400,});
import osfrom makers_sdk import Makersplatform = Makers(token=os.environ["MAKERS_API_TOKEN"],region="china",)created = platform.tokens.create(tenant_id="user-open-id",name="user-open-id",expires_in=86400,)
使用腾讯云 API 密钥签发：
import { Makers } from "@edgeone/makers-sdk";const secretId = process.env.TENCENTCLOUD_SECRET_ID;const secretKey = process.env.TENCENTCLOUD_SECRET_KEY;const zoneId = process.env.EDGEONE_MAKERS_ZONE_ID;if (!secretId || !secretKey || !zoneId) {throw new Error("TENCENTCLOUD_SECRET_ID, TENCENTCLOUD_SECRET_KEY, and EDGEONE_MAKERS_ZONE_ID are required.",);}const platform = new Makers({credentials: { secretId, secretKey },zoneId,});const { token, tokenId, expired } = await platform.tokens.create({tenantId: "user-open-id",name: "user-open-id",expiresIn: 86400,});
import osfrom makers_sdk import Makersplatform = Makers(credentials={"secret_id": os.environ["TENCENTCLOUD_SECRET_ID"],"secret_key": os.environ["TENCENTCLOUD_SECRET_KEY"],},zone_id=os.environ["EDGEONE_MAKERS_ZONE_ID"],)created = platform.tokens.create(tenant_id="user-open-id",name="user-open-id",expires_in=86400,)
部署方式
在 Vibe Coding 场景中，Makers 提供 SDK 和 CLI 两种部署方式：
