API Documentation

To facilitate flexible usage of GPU resources, the platform provides instance-related functionality through API calls, currently available only to enterprise users.

API Overview

The platform provides the following APIs externally:

API	Description
Get Available GPU Types	Query the current available GPU types on the platform
Get Images	Query the images available to the current account, including official and custom images
Create Instance	Create an instance. According to the platform's recommendation rules, choose the most suitable machine to execute the creation plan.
Query Operation Result	Query the result of an instance operation
Query Instances	Query and return instances that are not released
Instance Operations	OpenAPI supports starting, stopping, restarting, releasing, and setting custom ports for instances. More complex operations should be performed via the web console.

How to Call the API

1. Apply for Enterprise Qualification

Currently, APIs are only open to enterprise users. If you have not activated enterprise qualification, please go to the Account Center to submit an enterprise certification application.

2. Create API Key

API calls require an API key. You can create one in "Account Center - OpenAPI Key". After adding, the key will be downloaded locally. It cannot be downloaded again later. Please keep it safe and do not disclose it.

3. Endpoints

The endpoint is the request address for calling the API. The platform currently provides the following server call address:

Request Address	Protocol Type
`https://api-cloud.gpugeek.com`	HTTPS

4. Authentication

All API interfaces require authentication by including the API key in the header.
The header format is as follows:

{
  "gz-api-token":"test123abcxxxxxxxxx"
}

Here gz-api-token is the custom header key of the platform.

5. Response Results

All API responses are returned in JSON format (request/response header: Content-Type: application/json).
The general structure is as follows:

{
  "code": 0,
  "message": "success",
  "traceid": "",
  "data": {}
}

Response field descriptions:

Field	Description
code	Response code. 0 means success. Other values are error codes. Refer to the appendix for error code details.
message	"success" for successful requests. Otherwise, specific business error information.
data	Returned business data

API Details

1. Get Platform GPU Types

Description

Request URI: /api/v1/openapi/gpu/list
Request Method: GET

Request Parameters
None

Response Parameters

Name	Type	Description
gpus	`Array<string>`	Array of GPU types, GPU types are consistent

Response Example

{
    "code": 0,
    "message": "success",
    "traceid": "",
    "data": {
        "gpus": [
            "G40-24G",
            "G30-24G",
            "A100-PCIE-40G"
        ]
    }
}

2. Get Available Datacenter IDs

Description

Request URI: /api/v1/openapi/datacenter/list
Request Method: GET

Request Parameters
None

Response Parameters

Name	Type	Description
datacenters	`Array<Datacenter>`	Array of datacenters

Datacenter

Name	Type	Description
name	String	Datacenter name
dcId	String	Datacenter ID

Response Example

{
  "code": 0,
  "message": "success",
  "traceid": "57cbd46995d11318814a78746318bc32",
  "data": {
    "datacenters": [
      {
        "name": "Suqian-B",
        "dcId": "suqian-b"
      },
      {
        "name": "Qingyang-A",
        "dcId": "qingyang-a"
      },
      {
        "name": "USA-Dallas-N",
        "dcId": "dallas-n"
      }
    ]
  }
}

3. Get Images

Description

Request URI: /api/v1/openapi/image/list
Request Method: GET

Request Parameters
None

Response Parameters
Image Parameter Description

Name	Type	Description
type	String	Image type: user / official. user: backup image, official: official image
imageId	String	Image ID, used for instance creation
name	String	Image name

Response Example

{
    "code": 0,
    "message": "success",
    "traceid": "90223a7f6632b1176c74fa17445cfe0e",
    "data": {
        "images": [
            {
                "type": "official",
                "name": "torch2.1.1-cuda12.1.0-py3.10",
                "imageId": "torch2.1.1-cuda12.1.0-py3.10"
            },
            {
                "type": "user",
                "name": "testimage",
                "imageId": "123abc"
            }
        ]
    }
}

3. Create Instance

Description

Request URI: /api/v1/openapi/instance/create
Request Method: POST

Request Parameters
Body

Name	Type	Required	Description
type	Integer	Yes	Type value. Currently only supports type=2
gpuName	String	Yes	GPU type. Can be queried through the GPU list API or from the official website
skuName	String	Yes	Payment method. Options: pay-as-you-go (payg), bidding, daily, weekly, monthly
gpuNum	Integer	Yes	Number of GPUs to rent
cpuNum	Integer	No	Number of CPU cores allocated per GPU
memory	Integer	No	Memory allocated per GPU
diskType	String	No	Disk type (SSD/NVME)
tags	`Array<String>`	No	Query machines with specific tags
imageId	String	Yes	Image ID used to create the instance, can be queried from available images
autoRenew	Boolean	No	Whether to enable auto-renewal upon expiration. Default true for payg, false for prepaid methods
duration	Integer	No	Rental duration for prepaid instances. Default = 1
name	String	No	Instance name
servicePort	`Array<Integer>`	No	Custom TCP service ports, up to 3 total (TCP+HTTP)
httpServicePort	`Array<Integer>`	No	Custom HTTP service ports, up to 3 total (TCP+HTTP)
cmd	String	No	Startup command
env	String	No	Environment variables
dryRun	Boolean	No	Dry run. If true, only perform machine selection and price check
dcId	String	No	Datacenter ID
systemDiskSize	Integer	No	System disk size (GB). Default = 30GB
dataDiskSize	Integer	No	Data disk size (GB). Default = 20GB

Response Parameters
Data

Name	Type	Description
instanceId	Int64	Instance ID. 0 if dryRun=true
operationId	Int64	Current operation ID. 0 if dryRun=true
spec	`Object<Spec>`	Instance specification

Spec

Name	Type	Description
gpuName	String	GPU name
vram	String	GPU memory size (GB)
skuName	String	Payment type: payg, bidding, daily, weekly, monthly
price	String	Price
cpuName	String	CPU model
cpuCoreNum	int	CPU cores (allocated proportionally by GPU count)
memorySize	int	Memory size (allocated proportionally by GPU count)
payByVoucher	int	Voucher payment supported: 1, not supported: 0
regionName	String	Region
dcId	String	Datacenter ID

Response Example

{
    "code": 0,
    "message": "success",
    "traceid": "905b8753fb3db11760f67138872918cb",
    "data": {
        "InstanceId": 512300905672709,
        "operationId": 512303116840965,
        "spec": {
            "gpuName": "G30-24G",
            "vram": "10G",
            "skuName": "payg",
            "price": "10",
            "cpuCoreNum": 16,
            "cpuName": "Intel Xeon Processor (Skylake, IBRS)",
            "memorySize": 17179869184,
            "payByVoucher": 1,
            "regionName": "East China",
            "dcId": "suqian-b"
        }
    }
}

4. Query Operation Status

Description

Request URI: /api/v1/openapi/instance/op/result
Request Method: POST

Request Parameters
Body

Name	Type	Required	Description
ids	`Array<int>`	Yes	List of operation IDs

Response Parameters
Operation

Name	Type	Description
instanceId	Int64	Instance ID
status	int	Operation status: in progress = 1, success = 2, failure = 3
action	String	Current operation
operationId	String	Current operation ID
isCompleted	int	Whether the operation is completed: 1 = completed, 0 = not completed
startTime	String	Start time
completeTime	String	Completion time

Response Example

{
    "code": 0,
    "message": "success",
    "traceid": "287bfb0b8e3fb11797f57d7a4f92b05b",
    "data": {
        "operations": [
            {
                "instanceId": 512300905672709,
                "operationId": 512303116840965,
                "action": "stop",
                "status": 2,
                "isCompleted": 1,
                "startTime": "2024-02-06 17:06:45",
                "completeTime": "2024-02-06 17:06:47"
            }
        ]
    }
}

5. Query Instance List

Description

Request URI: /api/v1/openapi/instance/query
Request Method: GET

Request Parameters
Query

Name	Type	Required	Description
status	String	No	Instance status. Options: stopd, running, creating
instanceId	Int	No	Query a specific instance
pn	Integer	No	Page number
ps	Integer	No	Page size (default = 20)

Response Parameters

Name	Type	Description
instances	`Array<Instance>`	Array of instances
total	Integer	Total count

Instance

Name	Type	Description
instanceId	int64	Instance ID
name	String	Custom instance name
imageId	String	Image ID
status	String	Instance status
isPending	Int	Whether an operation is in progress. 1 = in progress
gpuName	String	GPU name
gpuNum	Integer	Number of GPUs
availableGpuNum	Int	Available GPUs on the host machine
skuName	String	Rental method: payg, daily, weekly, monthly, card_less (start without GPU)
createdAt	String	Creation time
cpuCoreNum	Int	CPU cores
memorySize	Int64	Memory size, in Bytes
systemDiskSize	Int64	Allocated system disk space (root directory /), in Bytes
systemDiskUsedSize	Int64	Used system disk space (root directory /), in Bytes
dataDiskSize	Int64	Allocated data disk space (/gz-data), in Bytes
dataDiskUsedSize	Int64	Used data disk space (/gz-data), in Bytes
sshCmd	String	SSH login command
sshPwd	String	SSH login password
notebookUrl	String	JupyterLab Notebook access URL
tensorboardUrl	String	Tensorboard access URL
customServices	`Array<String>`	Custom TCP port access URLs (array, each element is the access URL for a port)
httpServices	`Array<String>`	Custom HTTP port access URLs (array, each element is the access URL for a port)
operationId	Int64	Most recent operation ID
dcId	String	Datacenter ID
isStartable	Boolean	Whether the instance can be directly started, determined by the host machine status and available GPUs

Response Example

{
    "code": 0,
    "message": "success",
    "traceid": "3082737a3085b5177f74d5555f57a69f",
    "data": {
        "instances": [
            {
                "instanceId": 504838617333765,
                "name": "testname",
                "status": "stopd",
                "imageId": "stable-diffusion-webui_v1.7.0",
                "isPending": 0,
                "gpuName": "G40-24G",
                "gpuNum": 0,
                "skuName": "payg",
                "operationId": 511642810499077,
                "cpuCoreNum": 1,
                "memorySize": 2147483648,
                "systemDiskSize": 32212254720,
                "systemDiskUsedSize": 4311059,
                "dataDiskSize": 53687091200,
                "dataDiskUsedSize": 0,
                "sshCmd": "ssh -p 59064 root@xxxxx",
                "sshPwd": "Q3rDHh7QEwgYsuPxYSdVbE9zzKQQW45e",
                "notebookUrl": "http://xxxxx:42757/lab?token=f4jzygqwno3fecinx9arnetu",
                "tensorboardUrl": "http://xxxxx:44634",
                "customServices": [
                    "http://xxxxx:48548"
                ],
                "httpServices": [
                    "https://504838617333765-http-8099.northwest1.gpugeek.com:8443"
                ],
                "createdAt": "2024-01-16 14:53:38",
                "dcId": "qingyang-a",
                "availableGpuNum": 8,
                "isStartable": true
            }
        ],
        "total": 1
    }
}

6. Instance Operations

Description

Request URI: /api/v1/openapi/instance/action
Request Method: POST

Request Parameters
Body

Name	Type	Required	Description
instanceId	Int64	Yes	Instance ID
action	String	Yes	Instance operation type. Supported actions: stop (shutdown), start (boot), restart (reboot), release (terminate), set_port (set custom ports)
ports	`Array<Int>`	Required if action=set_port	Internal TCP port array. Up to 3 (TCP+HTTP) can be opened simultaneously. This operation resets and replaces existing TCP port mappings. Empty array deletes mappings.
httpPorts	`Array<Int>`	Required if action=set_port	Internal HTTP port array. Up to 3 (TCP+HTTP) can be opened simultaneously. This operation resets and replaces existing HTTP port mappings. Empty array deletes mappings.

Response Parameters

Name	Type	Description
operationId	Int64	Operation ID

Response Example

{
    "code": 0,
    "message": "success",
    "traceid": "3082737a3085b5177f74d5555f57a69f",
    "data": {
      "operationId": 511642810499077
    }
}

Appendix

1. Common Response Structure

{
  "code": 0,
  "message": "success",
  "traceid": "180114fedf26b1177b44121fa5c1e5d9",
  "data": {}
}

2. HTTP Status Codes

Status Code	Meaning	Description
404	Not Found	Request URI does not exist
403	Forbidden	Request not authorized
200	OK	Request successful
500	Internal Server Error	Server error

3. Common Error Codes

Error Code	Message	Description
10001	Internal Server Error	Undefined internal server error. Contact support for assistance
10002	Not logged in or login expired	Usually occurs when the request header is missing gz-api-token
10005	Parameter error	Parameter validation error
10135	Instance operation error	Instance operation error. Error details are in the message

API Overview​

How to Call the API​

1. Apply for Enterprise Qualification​

2. Create API Key​

3. Endpoints​

4. Authentication​

5. Response Results​

API Details​

1. Get Platform GPU Types​

2. Get Available Datacenter IDs​

3. Get Images​

3. Create Instance​

4. Query Operation Status​

5. Query Instance List​

6. Instance Operations​

Appendix​

1. Common Response Structure​

2. HTTP Status Codes​

3. Common Error Codes​

API Overview

How to Call the API

1. Apply for Enterprise Qualification

2. Create API Key

3. Endpoints

4. Authentication

5. Response Results

API Details

1. Get Platform GPU Types

2. Get Available Datacenter IDs

3. Get Images

3. Create Instance

4. Query Operation Status

5. Query Instance List

6. Instance Operations

Appendix

1. Common Response Structure

2. HTTP Status Codes

3. Common Error Codes