Elastic Deployment API Documentation

New APIs: Set Scheduling Blacklist and Get Regional GPU Inventory

To use the Elastic Deployment API, you must first authenticate your organization. For more information on Elastic Deployment, please refer to the documentation.

The API server host address is: https://api.webcal.com

Authentication

Where to find the token: Console -> Settings -> Developer Token

headers = {"Authorization": "token"}

Obtaining the Image

Images are custom images created and saved within WebCal; they can be created and saved via the webcal.com website. Importing images from external sources is not currently supported. For information on using the platform’s basic public images, see the appendix at the end of this document.

Request

POST /api/v1/dev/image/private/list

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
page_index	Int	Yes	Page Number
page_size	Int	Yes	Number of entries per page
offset	Int	No	Start offset of the query

Examples:

{
    "page_index": 1,
    "page_size": 10,
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data -> list	List<Response对象>

Response object parameters:

Parameter	Data Type	Notes
id	Int	Image ID
image_name	String	Image Name
image_uuid	String	Image UUID

Examples:

{
    "code": "Success",
    "msg": ""
    "data": {
        "list": [
            {
                "id": 111,
                "image_uuid": "image-db8346e037",
                "image_name": "image name",
            }
        ],
        "page_index": 1,
        "page_size": 10,
        "max_page": 1,
        "offset": 0,
    },
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/image/private/list"
body = {
    "page_index": 1,
    "page_size": 10,
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

Create a Deployment

Request

POST /api/v1/dev/deployment

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
name	String	Yes	Deployment Name
deployment_type	String	Yes	Deployment type. Supports ReplicaSet, Job, and Container
replica_num	Int	Required for ReplicaSet and Job	The number of container replicas to create; required for ReplicaSet and Job
parallelism_num	Int	Required for Job	Capacity of containers running simultaneously during deployment
reuse_container	Bool	No	Whether to reuse stopped containers; this can significantly speed up container creation
reuse_container_scope	String	No	Accepted values: all/deployment; default is all. Controls the scope of container reuse. When set to all, containers from all deployments within the account can be reused; when set to deployment, containers are reused only within the current deployment
service_port_protocol	String	No	Deprecated (please use service_6006_port_protocol and service_6008_port_protocol)
container_template	Container Template object	Yes

Container Template object:

Parameter	Data Type	Required	Notes
region_sign	String	Yes	Deprecated. Please use the dc_list field below
dc_list	list<String>	Yes	Regions (data_center) where containers can be scheduled; multiple regions can be specified. Refer to the appendix at the bottom of the documentation for region parameter values
service_6006_port_protocol	String	No	Sets the port mapping protocol for port 6006. Acceptable values are http/tcp; the default is http
service_6008_port_protocol	String	No	Sets the port mapping protocol for port 6008. Acceptable values are http/tcp; the default is http
cuda_v	Int	No	Deprecated. Use the cuda_v_from and cuda_v_to fields below
cuda_v_from	Int	Yes	The range of CUDA versions supported by the scheduler’s GPU driver. For example, the integer 112 represents CUDA version 11.2. See the CUDA Version appendix at the end of this document for detailed rules
cuda_v_to	Int	Yes	Same as above
gpu_name_set	List<String>	Yes	Schedulable GPU models. Refer to the GPU model names displayed when creating an elastic deployment on the reference webpage
gpu_num	Int	Yes	Number of GPUs required to create the container
memory_size_from	Int	Yes	The range of schedulable container memory sizes. Unit: GB
memory_size_to	Int	Yes	Same as above
cpu_num_from	Int	Yes	The range of schedulable CPU cores. Unit: 1vCPU
cpu_num_to	Int	Yes	Same as above
price_from	Int	Yes	A configurable price range. Unit: yuan * 1000; for example, enter 100 for 0.1 yuan
price_to	Int	Yes	Same as above
image_uuid	String	Yes	UUID of a private image or a public base image on the platform (see the appendix at the end of this document)
cmd_before_shutdown	String	No	Execute this command, as you configured it, before stopping the container. Note that this command has a 5-second timeout; if it times out, the container will be stopped immediately
cmd	String	Yes	Container startup command

Examples:

{
    "name": "api自动创建",
    "deployment_type": "ReplicaSet",
    "replica_num": 2,
    "reuse_container": true,
    "container_template": {
        "dc_list": ["westDC2", "westDC3"],
        "gpu_name_set": [
            "RTX 4090"
        ],
        "cuda_v_from": 113,
        "cuda_v_to": 128,
        "gpu_num": 1,
        "cpu_num_from": 1,
        "cpu_num_to": 100,
        "memory_size_from": 1,
        "memory_size_to": 256,
        "cmd": "sleep 100",
        "price_from": 100,  # 基准价格：0.1元/小时
        "price_to": 9000, # 基准价格：9元/小时
        "image_uuid": "image-db8346e037"
    }
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	Response object

Response object parameters:

Parameter	Data Type	Notes
deployment_uuid	String	Deployment UUID

Examples:

{
    "code": "Success",
    "msg": "",
    "data": {
        "deployment_uuid": "833f1cd5a764fa3"
    }
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment"

# 创建ReplicaSet类型部署
body = {
    "name": "api自动创建",
    "deployment_type": "ReplicaSet",
    "replica_num": 2,
    "reuse_container": True,
    "container_template": {
        "dc_list": ["westDC2", "westDC3"],
        "gpu_name_set": ["RTX 4090"],
        "gpu_num": 1,
        "cuda_v_from": 113,
        "cuda_v_to": 128,
        "cpu_num_from": 1,
        "cpu_num_to": 100,
        "memory_size_from": 1,
        "memory_size_to": 256,
        "cmd": "sleep 100",
        "price_from": 10,
        "price_to": 9000,
        "image_uuid": "image-db8346e037",
    },
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

# 附：
# 如果创建Job类型部署，Body为：
{
    "name": "api自动创建",
    "deployment_type": "Job",
    "replica_num": 4,
    "parallelism_num": 1,
    "reuse_container": True,
    "container_template": {
        "dc_list": ["westDC2", "westDC3"],
        "gpu_name_set": ["RTX 4090"],
        "gpu_num": 1,
        "cuda_v_from": 113,
        "cuda_v_to": 128,
        "cpu_num_from": 1,
        "cpu_num_to": 100,
        "memory_size_from": 1,
        "memory_size_to": 256,
        "cmd": "sleep 10",
        "price_from": 10,
        "price_to": 9000,
        "image_uuid": "image-db8346e037",
    },
}

# 如果创建Container类型部署，Body为：
{
    "name": "api自动创建",
    "deployment_type": "Container",
    "reuse_container": True,
    "container_template": {
        "dc_list": ["westDC2", "westDC3"],
        "gpu_name_set": ["RTX 4090"],
        "gpu_num": 1,
        "cuda_v": 113,
        "cpu_num_from": 1,
        "cpu_num_to": 100,
        "memory_size_from": 1,
        "memory_size_to": 256,
        "cmd": "sleep 100",
        "price_from": 10,
        "price_to": 9000,
        "image_uuid": "image-db8346e037",
    },
}

Retrieve the deployment list

POST /api/v1/dev/deployment/list

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
page_index	Int	Yes	Page Number
page_size	Int	Yes	Number of entries per page
name	String	No	Filters by name; fuzzy search is not supported. "name" refers to the deployment name set during creation
status	String	No	Filter by deployment status. If left blank, all records are filtered; pass `running` to filter records in deployment, or `stopped` to filter stopped records
deployment_uuid	String	No	Optional; allows filtering by deployment UUID

Examples:

{
    "page_index": 1,
    "page_size": 10,
}

Response

The meanings of these fields are the same as those for the parameters used when creating and deploying.

Examples:

{
    "code": "Success",
    "data": {
        "list": [
            {
                "id": 214,
                "uid": 58,
                "uuid": "53a677bb3e281b8",
                "name": "xxxx",
                "deployment_type": "Container",
                "status": "stopped",
                "replica_num": 1,
                "parallelism_num": 1,
                "reuse_container": true,
                "service_port_protocol": "http",
                "starting_num": 0,
                "running_num": 0,
                "finished_num": 2,
                "image_uuid": "image-db8346e037",
                "template": {
                    "region_sign": "",
                    "dc_list": [
                        "westDC2",
                        "westDC3"
                    ],
                    "gpu_name_set": [
                        "Tesla V100-SXM2-32GB"
                    ],
                    "gpu_num": 1,
                    "image_uuid": "image-db8346e037",
                    "image_name": "xxxx",
                    "cmd": "sleep 100",
                    "memory_size_from": 1073741824,
                    "memory_size_to": 274877906944,
                    "cpu_num_from": 1,
                    "cpu_num_to": 100,
                    "price_from": 10,
                    "price_to": 9000,
                    "cuda_v_from": 113,
                    "cuda_v_to": 128,
                },
                "price_estimates": 0,
                "created_at": "2023-01-05T20:34:07+08:00",
                "updated_at": "2023-01-05T20:34:07+08:00",
                "stopped_at": null
            }
        ],
        "page_index": 1,
        "page_size": 10,
        "offset": 0,
        "max_page": 1,
        "result_total": 3,
        "page": 1
    },
    "msg": ""
}

Querying Container Events

You can poll this API to retrieve the latest container events by setting the offset parameter in your request.

Request

POST /api/v1/dev/deployment/container/event/list

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID
deployment_container_uuid	String	No	Container UUID, optional
page_index	Int	Yes	Page Number
page_size	Int	Yes	Number of entries per page
offset	Int	No	Start offset of the query

Examples:

{
    "deployment_uuid": "da497aea1eb8343",
    "deployment_container_uuid": "",
    "page_index": 1,
    "page_size": 10,
    "offset": 0
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data -> list	list<Response对象>

Response object parameters:

Parameter	Data Type	Notes
deployment_container_uuid	String	Container UUID
status	String	Container status type
created_at	String	Time the status occurred

Examples:

{
    "code": "Success",
    "data": {
        "list": [
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "shutdown",
                "created_at": "2022-12-13T16:42:45+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "shutting_down",
                "created_at": "2022-12-13T16:42:40+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "running",
                "created_at": "2022-12-13T16:34:57+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "oss_merged",
                "created_at": "2022-12-13T16:34:55+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "starting",
                "created_at": "2022-12-13T16:34:55+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "created",
                "created_at": "2022-12-13T16:34:54+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "creating",
                "created_at": "2022-12-13T16:34:47+08:00"
            }
        ],
        "page_index": 1,
        "page_size": 10,
        "offset": 0,
        "max_page": 1,
    },
    "msg": ""
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/container/event/list"
body = {
    "deployment_uuid": "424446e02893b5f",
    "deployment_container_uuid": "",
    "page_index": 0,
    "page_size": 10,
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

Query Containers

If you need to retrieve the container's UUID from within the container, you can do so by accessing the value of the environment variable WebCalContainerUUID.

Request

POST /api/v1/dev/deployment/container/list

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID
container_uuid	String	No	Filter by container UUID
date_from	String	No	Filter container creation date range
date_to	String	No	Filter container creation time range
gpu_name	String	No	Filter by GPU model
cpu_num_from	Int	No	Filter by range of container CPU cores
cpu_num_to	Int	No	Filter by range of container CPU cores
memory_size_from	Int	No	Filter container memory size range
memory_size_to	Int	No	Filter container memory size range
price_from	Float	No	Filter container base price range
price_to	Float	No	Filter container base price range
released	bool	No	Whether to query instances that have already been released
status	List <String>	No	Filter containers by a specific status; you can set multiple different status filters
page_index	Int	Yes	Default value 0
page_size	Int	Yes	Default value 10
offset	Int	No	Start offset of the query

Examples:

{
    "deployment_uuid": "da497aea1eb8343",
    "page_index": 1,
    "page_size": 10
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data -> list	list<Response对象>

Response object parameters:

Parameter	Data Type	Notes
uuid	String	Container UUID
version	String	The container version, used to distinguish containers created from different images, etc. The system will automatically generate this when updating the deployment, or you can enter it yourself
data_center	String	Data Center (Region)
deployment_uuid	String	Deployment UUID
machine_id	String	Host UUID
status	String	Container status
gpu_name	String	GPU Model
gpu_num	Int	Number of GPUs
cpu_num	Int	Number of CPUs
memory_size	Int	Memory size, in bytes
image_uuid	String	Image UUID
price	Float	Base price, in yuan*1000
info	Info object
started_at	String	Start time
stopped_at	String	Stop time
created_at	String	Creation Time
updated_at	String	Last Updated

Info object:

Parameter	Data Type	Notes
ssh_command	String	SSH login command
root_password	String	SSH password
service_6006_port_url	String	Service address that maps container port 6006 to the public network
service_6008_port_url	String	Maps container port 6008 to the public service address
service_url	String	(Deprecated; please use service_6006_port_url and service_6008_port_url)
proxy_host	String	(Deprecated; please use service_6006_port_url and service_6008_port_url)
custom_port	Int	(Deprecated; please use service_6006_port_url and service_6008_port_url)

Examples:

{
    "code": "Success",
    "msg": "",
    "data": {
        "list": [
            {
                "id": 195,
                "uuid": "53a677bb3e281b8-f94411a60c-63c24009",
                "data_center": "westDC2",
                "machine_id": "f94411a60c",
                "deployment_uuid": "da497aea1eb8343",
                "status": "running",
                "gpu_name": "TITAN Xp",
                "gpu_num": 1,
                "cpu_num": 4,
                "memory_size": 2147483648,
                "image_uuid": "image-db8346e037",
                "price": 1881,
                "info": {
                    "ssh_command": "ssh -p 21305 root@region-1.webcal.com",
                    "root_password": "xxxxxxxxxx",
                    "service_6006_port_url": "https://region-1.webcal.com:21294",
                    "service_6008_port_url": "region-1.webcal.com:21295",
                },
                "started_at": "2022-12-13T16:43:03+08:00",
                "stopped_at": null,
                "created_at": "2022-12-13T16:42:50+08:00",
                "updated_at": "2022-12-13T16:43:03+08:00"
            }
        ],
        "page_index": 1,
        "page_size": 10,
        "max_page": 1,
    },
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/container/list"
body = {
    "deployment_uuid": "424446e02893b5f",
    "container_uuid": "",
    "date_from": "",
    "date_to": "",
    "gpu_name": "",
    "cpu_num_from": 0,
    "cpu_num_to": 0,
    "memory_size_from": 0,
    "memory_size_to": 0,
    "price_from": 0,
    "price_to": 0,
    "released": False,
    "status": ["running"],
    "page_index": 1,
    "page_size": 10,
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

Stop a Container

In addition to allowing the system to automatically scale the number of replicas and manage container lifecycles, this interface supports stopping a specific container. If you want to stop a container without automatically starting a new one to maintain the number of replicas, you can achieve this by passing decrease_one_replica_num=true, which stops the container and reduces the number of replicas by one.Note that the decrease_one_replica_num parameter is only valid for ReplicaSet-type deployments.

Request

PUT /api/v1/dev/deployment/container/stop

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_container_uuid	String	Yes	Deployed container UUID
decrease_one_replica_num	Boolean	No	For ReplicaSet deployments, whether to simultaneously reduce the number of replicas by 1
no_cache	Boolean	No	Specifies whether this container should not be added to the cache pool for reuse after it stops (if "Reuse container" was not selected when creating the deployment, this field has no practical effect).The default is "No," meaning that if container reuse is enabled for the deployment, this container will be reused the next time after it stops
cmd_before_shutdown	String	No	Executes the command you provide before stopping the container. Note that this command has a 5-second execution timeout; if it times out, the container will be stopped immediately.If the `cmd_before_shutdown` field was also set when creating the deployment, the value in this interface will override the value in the deployment and be executed (in extremely rare cases, both may be executed)

Examples:

{
     "deployment_container_uuid": "da497aea1eb8343-f94411a60c-a394fb30",
     "decrease_one_replica_num": false,
     "no_cache": false,
     "cmd_before_shutdown": "sleep 5"
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	empty

Examples:

{
    "code": "Success",
    "msg": "",
    "data": null
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/container/stop"
body = {
    "deployment_container_uuid": "da497aea1eb8343-f94411a60c-ec630659",
    "decrease_one_replica_num": False,
    "no_cache": False,
    "cmd_before_shutdown": "sleep 5"
}
response = requests.put(url, json=body, headers=headers)
print(response.content.decode())

Setting the Number of Replicas

Request

PUT /api/v1/dev/deployment/replica_num

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID
replica_num	Int	Yes	Number of replicas. Supported only for the ReplicaSet deployment type

Examples:

{
    "deployment_uuid": "xxx",
    "replica_num": 10
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	empty

Examples:

{
    "code": "Success",
    "msg": "",
    "data": null
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/replica_num"
body = {
    "deployment_uuid": "5be3045703152b9",
    "replica_num": 16
}
response = requests.put(url, json=body, headers=headers)
print(response.content.decode())

Stop Deployment

Request

PUT /api/v1/dev/deployment/operate

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID
operate	String	Yes	Operation type. Currently, the only valid value is: "stop"

Examples:

{
    "deployment_uuid": "xxx",
    "operate": "stop"
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	empty

Examples:

{
    "code": "Success",
    "msg": "",
    "data": null
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/operate"
body = {
    "deployment_uuid": "5be3045703152b9",
    "operate": "stop"
}
response = requests.put(url, json=body, headers=headers)
print(response.content.decode())

Delete Deployment

If you attempt to delete a deployment while it is still running, the system will first stop the deployment and then delete it.

Request

DELETE /api/v1/dev/deployment

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID

Examples:

{
    "deployment_uuid": "xxx"
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	empty

Examples:

{
    "code": "Success",
    "msg": "",
    "data": null
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment"
body = {
    "deployment_uuid": "5be3045703152b9"
}
response = requests.delete(url, json=body, headers=headers)
print(response.content.decode())

Setting Up the Scheduling Blacklist

If an unknown exception occurs in a container during scheduling or use, you can set the host where that container resides to a "scheduling disabled" status (this status is automatically lifted after 24 hours by default, though you can adjust this timeframe). Once set, none of your deployments will be scheduled on that host for the duration of this period.

Request

POST /api/v1/dev/deployment/blacklist

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_container_uuid	String	Yes	Container UUID
expire_in_minutes	Int	No	Blacklist expiration time. Specified in minutes; the default is 24 hours, and the maximum value is 30 days
comment	String	No	Remarks

Examples:

{
    "deployment_container_uuid": "xxx",
    "expire_in_minutes": 60,
    "comment": "开机缓慢，禁止在该主机上调度容器"
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	empty

Examples:

{
    "code": "Success",
    "msg": "",
    "data": null
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/blacklist"
body = {
    "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
    "expire_in_minutes": 60,
    "comment": "开机缓慢，禁止在该主机上调度容器"
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

Retrieve the active scheduling blacklist

If you have set up a scheduling blacklist via the API /api/v1/dev/deployment/blacklist, you can use this endpoint to query the list of blacklists that are still active.

Request

GET /api/v1/dev/deployment/blacklist

No request parameters in the body

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	List object

Response object parameters:

Parameter	Data Type	Notes
created_at	Timestamp	Time when the blacklist was "first" set
updated_at	Timestamp	Multiple blacklist updates will overwrite the expiration time and update this value. This represents the time the blacklist was last updated
data_center	String	Region
expired_time	Timestamp	Expiration Time
machine_id	String	Host ID
msg	String	Notes provided when setting the blacklist

Examples:

{
    "created_at": "2025-03-25T17:42:55+08:00",
    "data_center": "westDC2",
    "expired_time": "2025-03-26T17:48:11+08:00",
    "machine_id": "24fb4ca36a",
    "msg": "",
    "updated_at": "2025-03-25T17:48:11+08:00"
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/blacklist"
response = requests.get(url, headers=headers)
print(response.content.decode())

Retrieving Elastic Deployment GPU Inventory

Request

POST /api/v1/dev/machine/region/gpu_stock

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
region_sign	String	Yes	See the identifier codes for different regions in the appendix
cuda_v	Int	No	Deprecated. Use the cuda_v_from and cuda_v_to fields below
cuda_v_from	Int	No	Filters machines by the range of CUDA versions supported by their GPU drivers. For example, the integer 112 represents CUDA version 11.2. See the CUDA Version appendix at the end of this document for detailed rules
cuda_v_to	Int	No	Same as above
gpu_name_set	List<String>	No	Filter schedulable GPU models. Refer to the GPU model names displayed when creating an elastic deployment via the web interface
memory_size_from	Int	No	Filter the range of schedulable container memory sizes. Unit: GB
memory_size_to	Int	No	Same as above
cpu_num_from	Int	No	Filter the range of schedulable CPU cores. Unit: 1vCPU
cpu_num_to	Int	No	Same as above
price_from	Int	No	Filter the price range for schedulable resources. Unit: yuan * 1000; for example, enter 100 for 0.1 yuan
price_to	Int	No	Same as above

Note: When filtering, the number of GPUs is filtered by inventory based on the default assumption of scheduling a single card. If the query shows an inventory of 2 cards, they may be on two different machines; if a container requires 2 cards, it may not be possible to schedule it.

Examples:

{
    "region_sign": "westDC2",
    "cuda_v_from": 117,
    "cuda_v_to": 128
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data -> list	List

Response object parameters:

Parameter	Data Type	Notes
GPU Model	Inventory Object

Inventory Object Parameters:

Parameter	Data Type	Notes
idle_gpu_num	Int	Number of idle GPUs
total_gpu_num	Int	Total Count

Examples:

{
    "code": "Success",
    "msg": "",
    "data": [
        {
            "RTX 4090": {
                "idle_gpu_num": 215,
                "total_gpu_num": 2285
            }
        },
        {
            "RTX 3080 Ti": {
                "idle_gpu_num": 20,
                "total_gpu_num": 392
            }
        },
        {
            "RTX A4000": {
                "idle_gpu_num": 6,
                "total_gpu_num": 24
            }
        }
    ]
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/machine/region/gpu_stock"
body = {
    "region_sign": "westDC2",
    "cuda_v": 117
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

Retrieve data on purchased time-based packages

Request

GET /api/v1/dev/deployment/ddp/overview

Request parameters:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	List object

Response object parameters:

Parameter	Data Type	Notes
gpu_type	String	GPU Model
total	Int	Total duration of unused time packages; used time packages are not included in the count. Unit: seconds
balance	Int	Remaining time in the unused time package, in seconds
dc_list	String	Region. If a duration package for this GPU model covers multiple regions, they are separated by commas, for example: "westDC2,westDC3"

Examples:

{
    "code": "Success",
    "data": [
        {
            "gpu_type": "RTX 4090",
            "total": 86400,
            "balance": 83829,
            "dc_list": "westDC2,westDC3"
        }
    ],
    "msg": ""
}

Python Code

import requests
headers = {
    "Authorization": "您的token"
}
url = "https://api.webcal.com/api/v1/dev/deployment/ddp/overview"
params = {"deployment_uuid": "your uuid"}
response = requests.get(url, params=params, headers=headers)
print(response.content.decode())

Appendix

1. Create values for the dc_list or region_sign parameters during deployment. After the container starts, you can map the region using the value of the WebCalDataCenter environment variable within the container.

Region	region_sign value
Northwest Enterprise Zone (Recommended)	westDC2
Northwest Zone B	westDC3
Beijing Zone A	beijingDC1
Beijing Zone B	beijingDC2
L20 Zone (formerly Beijing Zone C)	beijingDC4
V100 Zone (formerly South China Zone A)	beijingDC3
Inner Mongolia Zone A	neimengDC1
Foshan District	foshanDC1
Chongqing Zone A	chongqingDC1
3090 Zone	yangzhouDC1
Inner Mongolia Zone B	neimengDC3

2. Public base image UUID

Image UUID	Framework	Image
base-image-12be412037	PyTorch	cuda11.1-cudnn8-devel-ubuntu18.04-py38-torch1.9.0
base-image-u9r24vthlk	PyTorch	cuda11.3-cudnn8-devel-ubuntu20.04-py38-torch1.10.0
base-image-l374uiucui	PyTorch	cuda11.3-cudnn8-devel-ubuntu20.04-py38-torch1.11.0
base-image-l2t43iu6uk	PyTorch	cuda11.8-cudnn8-devel-ubuntu20.04-py38-torch2.0.0
base-image-0gxqmciyth	TensorFlow	cuda11.2-cudnn8-devel-ubuntu18.04-py38-tf2.5.0
base-image-uxeklgirir	TensorFlow	cuda11.2-cudnn8-devel-ubuntu20.04-py38-tf2.9.0
base-image-4bpg0tt88l	TensorFlow	cuda11.4-py38-tf1.15.5
base-image-mbr2n4urrc	Miniconda	cuda11.6-cudnn8-devel-ubuntu20.04-py38
base-image-qkkhitpik5	Miniconda	cuda10.2-cudnn7-devel-ubuntu18.04-py38
base-image-h041hn36yt	Miniconda	cuda11.1-cudnn8-devel-ubuntu18.04-py38
base-image-7bn8iqhkb5	Miniconda	cudagl11.3-cudnn8-devel-ubuntu20.04-py38
base-image-k0vep6kyq8	Miniconda	cuda9.0-cudnn7-devel-ubuntu16.04-py36
base-image-l2843iu23k	TensorRT	cuda11.8-cudnn8-devel-ubuntu20.04-py38-trt8.5.1
base-image-l2t43iu6uk	TensorRT	cuda11.8-cudnn8-devel-ubuntu20.04-py38-torch2.0.0
...	...	For more newly released images, please contact customer service

3. CUDA version value

CUDA Version	Parameter values (integers) for the `cuda_v_from` and `cuda_v_to` fields
11.8	118
12.0	120
12.1	121
12.2	122
And so on	...

Note: If your framework uses CUDA version 11.5,and it is not listed among the available options above, select the lowest available version compatible with your required CUDA version—in this case, 11.8. Since newer driver versions are backward compatible with older CUDA versions, they will function normally; however, selecting a version that is too high will narrow the range of schedulable machines and reduce the number of available GPUs.

4. Environment variables within the container

key	value description
WebCalContainerUUID	Container UUID
WebCalDeploymentUUID	Deployment UUID
WebCalDataCenter	Region data_center

New APIs: Set Scheduling Blacklist and Get Regional GPU Inventory

To use the Elastic Deployment API, you must first authenticate your organization. For more information on Elastic Deployment, please refer to the documentation.

The API server host address is: https://api.webcal.com

Authentication

Where to find the token: Console -> Settings -> Developer Token

headers = {"Authorization": "token"}

Obtaining the Image

Images are custom images created and saved within WebCal; they can be created and saved via the webcal.com website. Importing images from external sources is not currently supported. For information on using the platform’s basic public images, see the appendix at the end of this document.

Request

POST /api/v1/dev/image/private/list

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
page_index	Int	Yes	Page Number
page_size	Int	Yes	Number of entries per page
offset	Int	No	Start offset of the query

Examples:

{
    "page_index": 1,
    "page_size": 10,
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data -> list	List<Response对象>

Response object parameters:

Parameter	Data Type	Notes
id	Int	Image ID
image_name	String	Image Name
image_uuid	String	Image UUID

Examples:

{
    "code": "Success",
    "msg": ""
    "data": {
        "list": [
            {
                "id": 111,
                "image_uuid": "image-db8346e037",
                "image_name": "image name",
            }
        ],
        "page_index": 1,
        "page_size": 10,
        "max_page": 1,
        "offset": 0,
    },
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/image/private/list"
body = {
    "page_index": 1,
    "page_size": 10,
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

Create a Deployment

Request

POST /api/v1/dev/deployment

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
name	String	Yes	Deployment Name
deployment_type	String	Yes	Deployment type. Supports ReplicaSet, Job, and Container
replica_num	Int	Required for ReplicaSet and Job	The number of container replicas to create; required for ReplicaSet and Job
parallelism_num	Int	Required for Job	Capacity of containers running simultaneously during deployment
reuse_container	Bool	No	Whether to reuse stopped containers; this can significantly speed up container creation
reuse_container_scope	String	No	Accepted values: all/deployment; default is all. Controls the scope of container reuse. When set to all, containers from all deployments within the account can be reused; when set to deployment, containers are reused only within the current deployment
service_port_protocol	String	No	Deprecated (please use service_6006_port_protocol and service_6008_port_protocol)
container_template	Container Template object	Yes

Container Template object:

Parameter	Data Type	Required	Notes
region_sign	String	Yes	Deprecated. Please use the dc_list field below
dc_list	list<String>	Yes	Regions (data_center) where containers can be scheduled; multiple regions can be specified. Refer to the appendix at the bottom of the documentation for region parameter values
service_6006_port_protocol	String	No	Sets the port mapping protocol for port 6006. Acceptable values are http/tcp; the default is http
service_6008_port_protocol	String	No	Sets the port mapping protocol for port 6008. Acceptable values are http/tcp; the default is http
cuda_v	Int	No	Deprecated. Use the cuda_v_from and cuda_v_to fields below
cuda_v_from	Int	Yes	The range of CUDA versions supported by the scheduler’s GPU driver. For example, the integer 112 represents CUDA version 11.2. See the CUDA Version appendix at the end of this document for detailed rules
cuda_v_to	Int	Yes	Same as above
gpu_name_set	List<String>	Yes	Schedulable GPU models. Refer to the GPU model names displayed when creating an elastic deployment on the reference webpage
gpu_num	Int	Yes	Number of GPUs required to create the container
memory_size_from	Int	Yes	The range of schedulable container memory sizes. Unit: GB
memory_size_to	Int	Yes	Same as above
cpu_num_from	Int	Yes	The range of schedulable CPU cores. Unit: 1vCPU
cpu_num_to	Int	Yes	Same as above
price_from	Int	Yes	A configurable price range. Unit: yuan * 1000; for example, enter 100 for 0.1 yuan
price_to	Int	Yes	Same as above
image_uuid	String	Yes	UUID of a private image or a public base image on the platform (see the appendix at the end of this document)
cmd_before_shutdown	String	No	Execute this command, as you configured it, before stopping the container. Note that this command has a 5-second timeout; if it times out, the container will be stopped immediately
cmd	String	Yes	Container startup command

Examples:

{
    "name": "api自动创建",
    "deployment_type": "ReplicaSet",
    "replica_num": 2,
    "reuse_container": true,
    "container_template": {
        "dc_list": ["westDC2", "westDC3"],
        "gpu_name_set": [
            "RTX 4090"
        ],
        "cuda_v_from": 113,
        "cuda_v_to": 128,
        "gpu_num": 1,
        "cpu_num_from": 1,
        "cpu_num_to": 100,
        "memory_size_from": 1,
        "memory_size_to": 256,
        "cmd": "sleep 100",
        "price_from": 100,  # 基准价格：0.1元/小时
        "price_to": 9000, # 基准价格：9元/小时
        "image_uuid": "image-db8346e037"
    }
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	Response object

Response object parameters:

Parameter	Data Type	Notes
deployment_uuid	String	Deployment UUID

Examples:

{
    "code": "Success",
    "msg": "",
    "data": {
        "deployment_uuid": "833f1cd5a764fa3"
    }
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment"

# 创建ReplicaSet类型部署
body = {
    "name": "api自动创建",
    "deployment_type": "ReplicaSet",
    "replica_num": 2,
    "reuse_container": True,
    "container_template": {
        "dc_list": ["westDC2", "westDC3"],
        "gpu_name_set": ["RTX 4090"],
        "gpu_num": 1,
        "cuda_v_from": 113,
        "cuda_v_to": 128,
        "cpu_num_from": 1,
        "cpu_num_to": 100,
        "memory_size_from": 1,
        "memory_size_to": 256,
        "cmd": "sleep 100",
        "price_from": 10,
        "price_to": 9000,
        "image_uuid": "image-db8346e037",
    },
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

# 附：
# 如果创建Job类型部署，Body为：
{
    "name": "api自动创建",
    "deployment_type": "Job",
    "replica_num": 4,
    "parallelism_num": 1,
    "reuse_container": True,
    "container_template": {
        "dc_list": ["westDC2", "westDC3"],
        "gpu_name_set": ["RTX 4090"],
        "gpu_num": 1,
        "cuda_v_from": 113,
        "cuda_v_to": 128,
        "cpu_num_from": 1,
        "cpu_num_to": 100,
        "memory_size_from": 1,
        "memory_size_to": 256,
        "cmd": "sleep 10",
        "price_from": 10,
        "price_to": 9000,
        "image_uuid": "image-db8346e037",
    },
}

# 如果创建Container类型部署，Body为：
{
    "name": "api自动创建",
    "deployment_type": "Container",
    "reuse_container": True,
    "container_template": {
        "dc_list": ["westDC2", "westDC3"],
        "gpu_name_set": ["RTX 4090"],
        "gpu_num": 1,
        "cuda_v": 113,
        "cpu_num_from": 1,
        "cpu_num_to": 100,
        "memory_size_from": 1,
        "memory_size_to": 256,
        "cmd": "sleep 100",
        "price_from": 10,
        "price_to": 9000,
        "image_uuid": "image-db8346e037",
    },
}

Retrieve the deployment list

POST /api/v1/dev/deployment/list

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
page_index	Int	Yes	Page Number
page_size	Int	Yes	Number of entries per page
name	String	No	Filters by name; fuzzy search is not supported. "name" refers to the deployment name set during creation
status	String	No	Filter by deployment status. If left blank, all records are filtered; pass `running` to filter records in deployment, or `stopped` to filter stopped records
deployment_uuid	String	No	Optional; allows filtering by deployment UUID

Examples:

{
    "page_index": 1,
    "page_size": 10,
}

Response

The meanings of these fields are the same as those for the parameters used when creating and deploying.

Examples:

{
    "code": "Success",
    "data": {
        "list": [
            {
                "id": 214,
                "uid": 58,
                "uuid": "53a677bb3e281b8",
                "name": "xxxx",
                "deployment_type": "Container",
                "status": "stopped",
                "replica_num": 1,
                "parallelism_num": 1,
                "reuse_container": true,
                "service_port_protocol": "http",
                "starting_num": 0,
                "running_num": 0,
                "finished_num": 2,
                "image_uuid": "image-db8346e037",
                "template": {
                    "region_sign": "",
                    "dc_list": [
                        "westDC2",
                        "westDC3"
                    ],
                    "gpu_name_set": [
                        "Tesla V100-SXM2-32GB"
                    ],
                    "gpu_num": 1,
                    "image_uuid": "image-db8346e037",
                    "image_name": "xxxx",
                    "cmd": "sleep 100",
                    "memory_size_from": 1073741824,
                    "memory_size_to": 274877906944,
                    "cpu_num_from": 1,
                    "cpu_num_to": 100,
                    "price_from": 10,
                    "price_to": 9000,
                    "cuda_v_from": 113,
                    "cuda_v_to": 128,
                },
                "price_estimates": 0,
                "created_at": "2023-01-05T20:34:07+08:00",
                "updated_at": "2023-01-05T20:34:07+08:00",
                "stopped_at": null
            }
        ],
        "page_index": 1,
        "page_size": 10,
        "offset": 0,
        "max_page": 1,
        "result_total": 3,
        "page": 1
    },
    "msg": ""
}

Querying Container Events

You can poll this API to retrieve the latest container events by setting the offset parameter in your request.

Request

POST /api/v1/dev/deployment/container/event/list

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID
deployment_container_uuid	String	No	Container UUID, optional
page_index	Int	Yes	Page Number
page_size	Int	Yes	Number of entries per page
offset	Int	No	Start offset of the query

Examples:

{
    "deployment_uuid": "da497aea1eb8343",
    "deployment_container_uuid": "",
    "page_index": 1,
    "page_size": 10,
    "offset": 0
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data -> list	list<Response对象>

Response object parameters:

Parameter	Data Type	Notes
deployment_container_uuid	String	Container UUID
status	String	Container status type
created_at	String	Time the status occurred

Examples:

{
    "code": "Success",
    "data": {
        "list": [
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "shutdown",
                "created_at": "2022-12-13T16:42:45+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "shutting_down",
                "created_at": "2022-12-13T16:42:40+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "running",
                "created_at": "2022-12-13T16:34:57+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "oss_merged",
                "created_at": "2022-12-13T16:34:55+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "starting",
                "created_at": "2022-12-13T16:34:55+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "created",
                "created_at": "2022-12-13T16:34:54+08:00"
            },
            {
                "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
                "status": "creating",
                "created_at": "2022-12-13T16:34:47+08:00"
            }
        ],
        "page_index": 1,
        "page_size": 10,
        "offset": 0,
        "max_page": 1,
    },
    "msg": ""
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/container/event/list"
body = {
    "deployment_uuid": "424446e02893b5f",
    "deployment_container_uuid": "",
    "page_index": 0,
    "page_size": 10,
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

Query Containers

If you need to retrieve the container's UUID from within the container, you can do so by accessing the value of the environment variable WebCalContainerUUID.

Request

POST /api/v1/dev/deployment/container/list

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID
container_uuid	String	No	Filter by container UUID
date_from	String	No	Filter container creation date range
date_to	String	No	Filter container creation time range
gpu_name	String	No	Filter by GPU model
cpu_num_from	Int	No	Filter by range of container CPU cores
cpu_num_to	Int	No	Filter by range of container CPU cores
memory_size_from	Int	No	Filter container memory size range
memory_size_to	Int	No	Filter container memory size range
price_from	Float	No	Filter container base price range
price_to	Float	No	Filter container base price range
released	bool	No	Whether to query instances that have already been released
status	List <String>	No	Filter containers by a specific status; you can set multiple different status filters
page_index	Int	Yes	Default value 0
page_size	Int	Yes	Default value 10
offset	Int	No	Start offset of the query

Examples:

{
    "deployment_uuid": "da497aea1eb8343",
    "page_index": 1,
    "page_size": 10
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data -> list	list<Response对象>

Response object parameters:

Parameter	Data Type	Notes
uuid	String	Container UUID
version	String	The container version, used to distinguish containers created from different images, etc. The system will automatically generate this when updating the deployment, or you can enter it yourself
data_center	String	Data Center (Region)
deployment_uuid	String	Deployment UUID
machine_id	String	Host UUID
status	String	Container status
gpu_name	String	GPU Model
gpu_num	Int	Number of GPUs
cpu_num	Int	Number of CPUs
memory_size	Int	Memory size, in bytes
image_uuid	String	Image UUID
price	Float	Base price, in yuan*1000
info	Info object
started_at	String	Start time
stopped_at	String	Stop time
created_at	String	Creation Time
updated_at	String	Last Updated

Info object:

Parameter	Data Type	Notes
ssh_command	String	SSH login command
root_password	String	SSH password
service_6006_port_url	String	Service address that maps container port 6006 to the public network
service_6008_port_url	String	Maps container port 6008 to the public service address
service_url	String	(Deprecated; please use service_6006_port_url and service_6008_port_url)
proxy_host	String	(Deprecated; please use service_6006_port_url and service_6008_port_url)
custom_port	Int	(Deprecated; please use service_6006_port_url and service_6008_port_url)

Examples:

{
    "code": "Success",
    "msg": "",
    "data": {
        "list": [
            {
                "id": 195,
                "uuid": "53a677bb3e281b8-f94411a60c-63c24009",
                "data_center": "westDC2",
                "machine_id": "f94411a60c",
                "deployment_uuid": "da497aea1eb8343",
                "status": "running",
                "gpu_name": "TITAN Xp",
                "gpu_num": 1,
                "cpu_num": 4,
                "memory_size": 2147483648,
                "image_uuid": "image-db8346e037",
                "price": 1881,
                "info": {
                    "ssh_command": "ssh -p 21305 root@region-1.webcal.com",
                    "root_password": "xxxxxxxxxx",
                    "service_6006_port_url": "https://region-1.webcal.com:21294",
                    "service_6008_port_url": "region-1.webcal.com:21295",
                },
                "started_at": "2022-12-13T16:43:03+08:00",
                "stopped_at": null,
                "created_at": "2022-12-13T16:42:50+08:00",
                "updated_at": "2022-12-13T16:43:03+08:00"
            }
        ],
        "page_index": 1,
        "page_size": 10,
        "max_page": 1,
    },
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/container/list"
body = {
    "deployment_uuid": "424446e02893b5f",
    "container_uuid": "",
    "date_from": "",
    "date_to": "",
    "gpu_name": "",
    "cpu_num_from": 0,
    "cpu_num_to": 0,
    "memory_size_from": 0,
    "memory_size_to": 0,
    "price_from": 0,
    "price_to": 0,
    "released": False,
    "status": ["running"],
    "page_index": 1,
    "page_size": 10,
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

Stop a Container

Request

PUT /api/v1/dev/deployment/container/stop

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_container_uuid	String	Yes	Deployed container UUID
decrease_one_replica_num	Boolean	No	For ReplicaSet deployments, whether to simultaneously reduce the number of replicas by 1
no_cache	Boolean	No	Specifies whether this container should not be added to the cache pool for reuse after it stops (if "Reuse container" was not selected when creating the deployment, this field has no practical effect).The default is "No," meaning that if container reuse is enabled for the deployment, this container will be reused the next time after it stops
cmd_before_shutdown	String	No	Executes the command you provide before stopping the container. Note that this command has a 5-second execution timeout; if it times out, the container will be stopped immediately.If the `cmd_before_shutdown` field was also set when creating the deployment, the value in this interface will override the value in the deployment and be executed (in extremely rare cases, both may be executed)

Examples:

{
     "deployment_container_uuid": "da497aea1eb8343-f94411a60c-a394fb30",
     "decrease_one_replica_num": false,
     "no_cache": false,
     "cmd_before_shutdown": "sleep 5"
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	empty

Examples:

{
    "code": "Success",
    "msg": "",
    "data": null
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/container/stop"
body = {
    "deployment_container_uuid": "da497aea1eb8343-f94411a60c-ec630659",
    "decrease_one_replica_num": False,
    "no_cache": False,
    "cmd_before_shutdown": "sleep 5"
}
response = requests.put(url, json=body, headers=headers)
print(response.content.decode())

Setting the Number of Replicas

Request

PUT /api/v1/dev/deployment/replica_num

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID
replica_num	Int	Yes	Number of replicas. Supported only for the ReplicaSet deployment type

Examples:

{
    "deployment_uuid": "xxx",
    "replica_num": 10
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	empty

Examples:

{
    "code": "Success",
    "msg": "",
    "data": null
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/replica_num"
body = {
    "deployment_uuid": "5be3045703152b9",
    "replica_num": 16
}
response = requests.put(url, json=body, headers=headers)
print(response.content.decode())

Stop Deployment

Request

PUT /api/v1/dev/deployment/operate

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID
operate	String	Yes	Operation type. Currently, the only valid value is: "stop"

Examples:

{
    "deployment_uuid": "xxx",
    "operate": "stop"
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	empty

Examples:

{
    "code": "Success",
    "msg": "",
    "data": null
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/operate"
body = {
    "deployment_uuid": "5be3045703152b9",
    "operate": "stop"
}
response = requests.put(url, json=body, headers=headers)
print(response.content.decode())

Delete Deployment

If you attempt to delete a deployment while it is still running, the system will first stop the deployment and then delete it.

Request

DELETE /api/v1/dev/deployment

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID

Examples:

{
    "deployment_uuid": "xxx"
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	empty

Examples:

{
    "code": "Success",
    "msg": "",
    "data": null
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment"
body = {
    "deployment_uuid": "5be3045703152b9"
}
response = requests.delete(url, json=body, headers=headers)
print(response.content.decode())

Setting Up the Scheduling Blacklist

Request

POST /api/v1/dev/deployment/blacklist

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
deployment_container_uuid	String	Yes	Container UUID
expire_in_minutes	Int	No	Blacklist expiration time. Specified in minutes; the default is 24 hours, and the maximum value is 30 days
comment	String	No	Remarks

Examples:

{
    "deployment_container_uuid": "xxx",
    "expire_in_minutes": 60,
    "comment": "开机缓慢，禁止在该主机上调度容器"
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	empty

Examples:

{
    "code": "Success",
    "msg": "",
    "data": null
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/blacklist"
body = {
    "deployment_container_uuid": "da497aea1eb8343-f94411a60c-1502e6e2",
    "expire_in_minutes": 60,
    "comment": "开机缓慢，禁止在该主机上调度容器"
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

Retrieve the active scheduling blacklist

If you have set up a scheduling blacklist via the API /api/v1/dev/deployment/blacklist, you can use this endpoint to query the list of blacklists that are still active.

Request

GET /api/v1/dev/deployment/blacklist

No request parameters in the body

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	List object

Response object parameters:

Parameter	Data Type	Notes
created_at	Timestamp	Time when the blacklist was "first" set
updated_at	Timestamp	Multiple blacklist updates will overwrite the expiration time and update this value. This represents the time the blacklist was last updated
data_center	String	Region
expired_time	Timestamp	Expiration Time
machine_id	String	Host ID
msg	String	Notes provided when setting the blacklist

Examples:

{
    "created_at": "2025-03-25T17:42:55+08:00",
    "data_center": "westDC2",
    "expired_time": "2025-03-26T17:48:11+08:00",
    "machine_id": "24fb4ca36a",
    "msg": "",
    "updated_at": "2025-03-25T17:48:11+08:00"
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/deployment/blacklist"
response = requests.get(url, headers=headers)
print(response.content.decode())

Retrieving Elastic Deployment GPU Inventory

Request

POST /api/v1/dev/machine/region/gpu_stock

Place the request parameters in the Body; the parameter details are as follows:

Parameter	Data Type	Required	Notes
region_sign	String	Yes	See the identifier codes for different regions in the appendix
cuda_v	Int	No	Deprecated. Use the cuda_v_from and cuda_v_to fields below
cuda_v_from	Int	No	Filters machines by the range of CUDA versions supported by their GPU drivers. For example, the integer 112 represents CUDA version 11.2. See the CUDA Version appendix at the end of this document for detailed rules
cuda_v_to	Int	No	Same as above
gpu_name_set	List<String>	No	Filter schedulable GPU models. Refer to the GPU model names displayed when creating an elastic deployment via the web interface
memory_size_from	Int	No	Filter the range of schedulable container memory sizes. Unit: GB
memory_size_to	Int	No	Same as above
cpu_num_from	Int	No	Filter the range of schedulable CPU cores. Unit: 1vCPU
cpu_num_to	Int	No	Same as above
price_from	Int	No	Filter the price range for schedulable resources. Unit: yuan * 1000; for example, enter 100 for 0.1 yuan
price_to	Int	No	Same as above

Note: When filtering, the number of GPUs is filtered by inventory based on the default assumption of scheduling a single card. If the query shows an inventory of 2 cards, they may be on two different machines; if a container requires 2 cards, it may not be possible to schedule it.

Examples:

{
    "region_sign": "westDC2",
    "cuda_v_from": 117,
    "cuda_v_to": 128
}

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data -> list	List

Response object parameters:

Parameter	Data Type	Notes
GPU Model	Inventory Object

Inventory Object Parameters:

Parameter	Data Type	Notes
idle_gpu_num	Int	Number of idle GPUs
total_gpu_num	Int	Total Count

Examples:

{
    "code": "Success",
    "msg": "",
    "data": [
        {
            "RTX 4090": {
                "idle_gpu_num": 215,
                "total_gpu_num": 2285
            }
        },
        {
            "RTX 3080 Ti": {
                "idle_gpu_num": 20,
                "total_gpu_num": 392
            }
        },
        {
            "RTX A4000": {
                "idle_gpu_num": 6,
                "total_gpu_num": 24
            }
        }
    ]
}

Python Code

import requests
headers = {
    "Authorization": "您的token",
    "Content-Type": "application/json"
}
url = "https://api.webcal.com/api/v1/dev/machine/region/gpu_stock"
body = {
    "region_sign": "westDC2",
    "cuda_v": 117
}
response = requests.post(url, json=body, headers=headers)
print(response.content.decode())

Retrieve data on purchased time-based packages

Request

GET /api/v1/dev/deployment/ddp/overview

Request parameters:

Parameter	Data Type	Required	Notes
deployment_uuid	String	Yes	Deployment UUID

Response

Response parameters:

Parameter	Data Type	Notes
code	String	Response code; "Success" upon success
msg	String	Error message; empty on success
data	List object

Response object parameters:

Parameter	Data Type	Notes
gpu_type	String	GPU Model
total	Int	Total duration of unused time packages; used time packages are not included in the count. Unit: seconds
balance	Int	Remaining time in the unused time package, in seconds
dc_list	String	Region. If a duration package for this GPU model covers multiple regions, they are separated by commas, for example: "westDC2,westDC3"

Examples:

{
    "code": "Success",
    "data": [
        {
            "gpu_type": "RTX 4090",
            "total": 86400,
            "balance": 83829,
            "dc_list": "westDC2,westDC3"
        }
    ],
    "msg": ""
}

Python Code

import requests
headers = {
    "Authorization": "您的token"
}
url = "https://api.webcal.com/api/v1/dev/deployment/ddp/overview"
params = {"deployment_uuid": "your uuid"}
response = requests.get(url, params=params, headers=headers)
print(response.content.decode())

Appendix

Region	region_sign value
Northwest Enterprise Zone (Recommended)	westDC2
Northwest Zone B	westDC3
Beijing Zone A	beijingDC1
Beijing Zone B	beijingDC2
L20 Zone (formerly Beijing Zone C)	beijingDC4
V100 Zone (formerly South China Zone A)	beijingDC3
Inner Mongolia Zone A	neimengDC1
Foshan District	foshanDC1
Chongqing Zone A	chongqingDC1
3090 Zone	yangzhouDC1
Inner Mongolia Zone B	neimengDC3

2. Public base image UUID

Image UUID	Framework	Image
base-image-12be412037	PyTorch	cuda11.1-cudnn8-devel-ubuntu18.04-py38-torch1.9.0
base-image-u9r24vthlk	PyTorch	cuda11.3-cudnn8-devel-ubuntu20.04-py38-torch1.10.0
base-image-l374uiucui	PyTorch	cuda11.3-cudnn8-devel-ubuntu20.04-py38-torch1.11.0
base-image-l2t43iu6uk	PyTorch	cuda11.8-cudnn8-devel-ubuntu20.04-py38-torch2.0.0
base-image-0gxqmciyth	TensorFlow	cuda11.2-cudnn8-devel-ubuntu18.04-py38-tf2.5.0
base-image-uxeklgirir	TensorFlow	cuda11.2-cudnn8-devel-ubuntu20.04-py38-tf2.9.0
base-image-4bpg0tt88l	TensorFlow	cuda11.4-py38-tf1.15.5
base-image-mbr2n4urrc	Miniconda	cuda11.6-cudnn8-devel-ubuntu20.04-py38
base-image-qkkhitpik5	Miniconda	cuda10.2-cudnn7-devel-ubuntu18.04-py38
base-image-h041hn36yt	Miniconda	cuda11.1-cudnn8-devel-ubuntu18.04-py38
base-image-7bn8iqhkb5	Miniconda	cudagl11.3-cudnn8-devel-ubuntu20.04-py38
base-image-k0vep6kyq8	Miniconda	cuda9.0-cudnn7-devel-ubuntu16.04-py36
base-image-l2843iu23k	TensorRT	cuda11.8-cudnn8-devel-ubuntu20.04-py38-trt8.5.1
base-image-l2t43iu6uk	TensorRT	cuda11.8-cudnn8-devel-ubuntu20.04-py38-torch2.0.0
...	...	For more newly released images, please contact customer service

3. CUDA version value

CUDA Version	Parameter values (integers) for the `cuda_v_from` and `cuda_v_to` fields
11.8	118
12.0	120
12.1	121
12.2	122
And so on	...

4. Environment variables within the container

key	value description
WebCalContainerUUID	Container UUID
WebCalDeploymentUUID	Deployment UUID
WebCalDataCenter	Region data_center