Overview
The Makers SDK provides both TypeScript and Python implementations, allowing platform providers to create projects and complete deployments through code. The SDK offers two initialization methods: using a Makers API Token or using a Tencent Cloud API key (SecretId / SecretKey). Regardless of the method used, the calling methods, parameters, and return values for features such as project management, environment variable configuration, deployment, and domains remain consistent.
Installation
The TypeScript runtime environment is Node.js 20+, and only ESM is published. The Python runtime environment is 3.10+.
npm install @edgeone/makers-sdk
pip install makers-sdk
Initializing with an API Token
1. Create an API Token in the console. For steps, see API Token.
2. Write the
MAKERS_API_TOKEN environment variable.3. Initialize the Makers SDK:
import { Makers } from "@edgeone/makers-sdk";const makers = new Makers({token: process.env.MAKERS_API_TOKEN,region: "china",});
import osfrom makers_sdk import Makersmakers = Makers(token=os.environ["MAKERS_API_TOKEN"],region="china",)
region is an optional parameter and must be consistent with the workspace that issued the API Token: "china" corresponds to the China site, and "global" corresponds to the International site. If region is not specified, the SDK automatically detects the China site (china) and the International site (global) in sequence and caches the result in the current Makers instance.Initializing with a Tencent Cloud API Key
To initialize with a Tencent Cloud API key, you need the SecretId, SecretKey, and Makers workspace ID (ZoneId).
1. Create a SecretId and SecretKey in API Key Management in the Tencent Cloud console, and write them to the
TENCENTCLOUD_SECRET_ID and TENCENTCLOUD_SECRET_KEY environment variables.For a sub-account, the following CAM permissions must be granted for projects, environment variables, deployments, and domains: teo:DescribePagesResources, teo:CreatePagesResources, teo:ModifyPagesResources, and teo:DeletePagesResources.
2. Obtain the ZoneId. A Makers workspace is automatically created when you activate Makers. Call the Tencent Cloud API
DescribeZones and filter by zone-type as pages to find the ZoneId of the workspace. Write the ZoneId to the EDGEONE_MAKERS_ZONE_ID environment variable.3. Initialize the Makers SDK:
import { Makers } from "@edgeone/makers-sdk";const makers = new Makers({credentials: {secretId: process.env.TENCENTCLOUD_SECRET_ID,secretKey: process.env.TENCENTCLOUD_SECRET_KEY,},zoneId: process.env.EDGEONE_MAKERS_ZONE_ID,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")
Constructor Parameters
Parameter names and types are given in the format of
TypeScript / Python.Parameter | Type | Required | Default Value | Description |
token | string / str | No | - | EdgeOne Makers API Token. Required when credentials is not passed in. |
timeout | number / float | No | 30 | Timeout of a single request, in seconds. |
retries | number / int | No | 3 | Maximum number of retries for query operations; write operations are not retried. |
logger | Logger | No | - | Used to output SDK logs. Pass in an object with the debug, info, warn, and error methods. If it is not passed in, no logs are output. |
credentials | { secretId, secretKey } / {"secret_id", "secret_key"} | No | - | Tencent Cloud API key. Both fields must be non-empty strings. |
zoneId / zone_id | string / str | No | - | Makers workspace ID. Required when credentials is used for authentication. |
region | "china" | "global" | No | - | Specifies the API request region: "china" for the China site, and "global" for the international site. |
Public Members
Member | Type | Description |
makers.projects | Projects | Project and Environment Variable Operations |
makers.deployments | Deployments | Deployment Operations |
makers.domains | Domains | Custom domains: create, query, and delete, as well as ownership verification, CNAME check, and HTTPS certificates. |
makers.tokens | Tokens | Issue tenant tokens ( tokens.create) |
makers.region | "china" | "global" or empty | Read-only. Pass in the China site (china) or global site (global) during construction. |
Type names are the types exported by TypeScript, while the corresponding Python namespaces are not exported as public types.
Error Handling
All errors inherit from
MakersError, with public fields code, cause, requestId / request_id, and httpStatus / http_status. Error messages are obtained through error.message in TypeScript and through str(error) in Python.Exception Type | Description |
AuthError | Invalid Token or Tencent Cloud API key, or no access permission. |
ValidationError | Invalid input parameters or validation errors returned by the server. Local validation is thrown before the request is sent. |
NotFoundError | The project, deployment, or Makers workspace does not exist. |
ConflictError | Resource conflict |
RateLimitError | Rate limit triggered |
UploadError | Failed to upload artifact |
TimeoutError | Timeout of a single request |
DeploymentTimeoutError | Timeout while waiting for the deployment to reach a final state (inherits from TimeoutError) |
import { Makers, MakersError, NotFoundError } from "@edgeone/makers-sdk";const makers = new Makers({token: process.env.MAKERS_API_TOKEN,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);}}
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)
Issuing a Tenant token
In deployment scenarios where platform-level credentials need to be isolated to reduce the risk of Makers API Token leakage, it is recommended to issue a permission-restricted tenant token through
tokens.create for deployment. When initializing the Makers SDK, you need to provide account-level credentials: the primary API Token created in the console, or a Tencent Cloud API key (credentials and zoneId). The SDK then issues a tenant token. Issued tenant tokens cannot be queried or deleted.Upon a successful call,
token, tokenId, and expired are returned. expired is the expiration time in Unix timestamp format (seconds). When re-issuing for the same tenantId, token and tokenId remain unchanged, while expired may be updated. If the parameters do not meet the requirements, a ValidationError is thrown before the request is initiated.Parameters
Parameter | Type | Required | Description |
tenantId / tenant_id | string / str | Yes | Tenant ID, up to 64 characters |
name | string / str | Yes | Token name, 1 to 128 characters in length |
expiresIn / expires_in | number / int | Yes | Validity period, in seconds, ranging from 10 to 315360000 |
Examples
Issue using an API Token:
import { Makers } from "@edgeone/makers-sdk";const platform = new Makers({token: process.env.MAKERS_API_TOKEN,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,)
Issue using a Tencent Cloud API key:
import { Makers } from "@edgeone/makers-sdk";const platform = new Makers({credentials: {secretId: process.env.TENCENTCLOUD_SECRET_ID,secretKey: process.env.TENCENTCLOUD_SECRET_KEY,},zoneId: process.env.EDGEONE_MAKERS_ZONE_ID,});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,)
Deployment Mode
In Vibe Coding scenarios, Makers provides two deployment methods: SDK and CLI.
Deployment Mode | Scenarios | Example |
Deploy via SDK | The platform backend obtains the generated code and directly publishes it online. | |
Deploy via CLI | Preview in the sandbox in real time, and publish online after confirming the effect. |
