跳至主要内容
Glows.ai
API docs by Redocly

GLOWS SDK HTTP API 文件 (v1)

GLOWS SDK v1 在 /sdk/v1 下提供執行個體生命週期、映像提交、資源規格、網路與快照 API。

驗證使用 Authorization: Bearer <token> header 中的 SDK token。伺服器也接受 Authorization query parameter，並在 JWT 驗證前將其複製到 header。

應用程式錯誤會以包含 code 與 msg 的 JSON body 回傳。多數應用程式錯誤使用 HTTP status 200；速率限制可能以純文字 body 回傳 HTTP 429。

此契約描述公開的 SDK HTTP API 介面。

Instance

建立、查詢、列出、統計與取消由 SDK 建立的運算執行個體。

查詢單一執行個體

透過 request_id 或 meta_key 查詢執行個體。

request_id 是 create/list/query response 回傳的 instanceID。伺服器接受像 ins-... 這類 resource ID，也接受舊版 hash ID fallback。meta_key 是建立時以 custom_meta_key 提供的全域唯一 自訂 key。

Authorizations:
bearerAuth
query Parameters
request_id
string <= 64 characters
Example: request_id=ins-boyqp4g8

以 instance.instanceID 回傳的 instance resource ID，或舊版 hash ID fallback。

meta_key
string <= 64 characters
Example: meta_key=order.123456

使用者提供的全域唯一 custom_meta_key。

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
object (VisibleInstance)

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": "",
  • "instance": {
    }
}

透過 SDK 建立執行個體

從映像或快照建立容器或 VM 執行個體。

Authorizations:
bearerAuth
Request Body schema: application/json
required
One of
from_image_id
required
string <= 64 characters

Base image resource ID。

gpu_name
required
string <= 128 characters

GPU 型號名稱。

custom_meta_key
required
string <= 64 characters

用於冪等性業務查詢的全域唯一自訂 Key。

instance_category
required
string (InstanceCategory)
Default: "container"
Enum: "container" "vm"
region_name
required
string <= 128 characters

對應到 platform domain 的必填區域顯示/名稱值。

remark
string <= 32 characters

備註。

cmd
string <= 512 characters

執行個體啟動命令。

envs
string <= 512 characters

環境變數字串，例如 foo=bar;tik=tok。

ports
string

ports 用於設定實例需開放的服務端口。若同時設定 public_ip_id，可自定義實例內部端口與 Bind IP 對外端口的映射。

  • port：實例內部服務端口
  • exposePort：Bind IP 對外暴露端口
  • protocol：端口協議類型，如 TCP / UDP
unit_qty
integer <int64> >= 0
Default: 1

要請求的 GPU/CPU 資源單位數量。0 或省略時預設為一個單位。 適用於 GPU 與 CPU 執行個體建立。 當提供 base_resource.resource_id 或 base_resource.unit_spec，且 base_resource.unit_qty 大於零時，base_resource.unit_qty 會覆寫此值。

object (CreateInstanceBaseResource)

會直接轉換為 base resource descriptor 的 base resource description。resource_id 是 base64 編碼的 machine class tag，不是 SDK res-... resource ID。unit_spec fields 會複製 到同一個 base resource。若 unit_qty 大於零，會覆寫頂層 unit_qty； 0 或省略時保留頂層值。只有 unit_qty 的 base_resource object 不足以 啟用 base-resource creation；請包含 resource_id 或 unit_spec。

object (CreateInstanceExtraResource)

Extra resources 不包含 resource_id 或 GPU 相關欄位。

net_ids
Array of strings <= 1 items [ items <= 64 characters ]

listNetworks 回傳的 private network ID。目前伺服器支援一個網路。

network_type
integer <int32> (NetworkType)
Enum: 0 1 2 3 4 5 6 7

數值型 network type。在 SDK network API 中，為了相容性，省略或 0 表示 mesh/UserVXLAN； 6 表示 list operations 使用的 NAT4 public-IP 網路。

public_ip_id
string <= 64 characters

Public/NAT network resource ID。提供且有效時，伺服器會強制 network_type 為 NAT4。

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
object (VisibleInstance)

Request samples

Content type
application/json
Example
{
  • "from_image_id": "img-87p9kq26",
  • "custom_meta_key": "order.123456",
  • "remark": "this is from sdk",
  • "envs": "foo=bar",
  • "gpu_name": "NVIDIA GeForce RTX 4090",
  • "unit_qty": 2,
  • "instance_category": "container",
  • "region_name": "Region-01",
  • "ports": "[{\"port\":7890,\"protocol\":2}]"
}

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": "",
  • "instance": {
    }
}

透過 SDK 取消執行個體

透過 request_id 或 meta_key 取消執行個體。

伺服器只會取消已驗證 SDK 使用者擁有，且以 SDK source semantics 建立的執行個體。 無效 ID、非本人擁有的執行個體，以及缺少 query parameters 都會回傳 ParamIllegal。

Authorizations:
bearerAuth
query Parameters
request_id
string <= 64 characters
Example: request_id=ins-boyqp4g8

以 instance.instanceID 回傳的 instance resource ID，或舊版 hash ID fallback。

meta_key
string <= 64 characters
Example: meta_key=order.123456

使用者提供的全域唯一 custom_meta_key。

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": ""
}

依狀態統計執行個體

回傳已驗證 SDK 使用者的稀疏 status-to-count map。

Authorizations:
bearerAuth

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
object

從 status name 到 instance count 的稀疏 map。

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "stats": {
    }
}

列出執行個體

列出已驗證 SDK 使用者的執行個體。

伺服器 binding 要求 page 與 per_page。per_page 不得大於 20。 傳入空的 statuses list 會回傳所有狀態。未知的 status name 目前會被伺服器忽略。

Authorizations:
bearerAuth
query Parameters
page
required
integer <uint32> >= 1
Example: page=1

從 1 開始的頁碼。

per_page
required
integer <uint32> [ 1 .. 20 ]
Example: per_page=10

分頁大小。目前伺服器會拒絕大於 20 的值。

ascending
boolean
Default: false

為 true 時依建立時間升冪排序；為 false 時降冪排序。

statuses
Array of strings (NodeStatusName)
Items Enum: "InvalidNodeStatus" "Pending" "Running" "Exited" "Finished" "Rebooted" "Canceling" "Unavail" "Pausing" "Paused" "Resuming" "Snapshotted" "ExitSnapshotted" "Migrating" "Checkpointed" "SchedInit" "SchedQueued" "PriceChanged"

可重複的狀態篩選，例如 statuses=Running&statuses=Pending。

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
object (Pagination)
Array of objects (VisibleInstance)

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "instances": [
    ]
}

Image

提交一個容器映像 registry 連結，並列出 SDK 可見的映像。

提交一個容器映像連結

為已驗證 SDK 使用者提交單一容器 registry 映像連結。

SDK 介面只接受 image_link。伺服器會以 registry URL provider semantics 建立一個使用者擁有的私有映像， 並回傳編碼後的 image resource ID。

Authorizations:
bearerAuth
Request Body schema: application/json
required
image_link
required
string <= 512 characters

單一 registry image link。空白字元會被拒絕。

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
image_id
string

編碼後的 image resource ID，例如 img-...。

name
string

伺服器產生的 image name。

Request samples

Content type
application/json
{
  • "image_link": "registry.example.com/team/runtime:cuda12.2"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "image_id": "img-87p9kq26",
  • "name": "sdk-10001-1726810944000000000-runtime"
}

刪除 SDK 擁有的映像

刪除已驗證 SDK 使用者擁有的私有映像。

伺服器接受像 img-... 這類編碼後的 image resource ID，驗證擁有權、解析 backing image store， 然後呼叫 image manager delete flow。公開映像與其他使用者擁有的映像會被拒絕。

Authorizations:
bearerAuth
Request Body schema: application/json
required
image_id
required
string <= 64 characters

編碼後的 image resource ID，例如 img-...。

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string

Request samples

Content type
application/json
{
  • "image_id": "img-87p9kq26"
}

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": ""
}

列出 SDK 可見的映像

Authorizations:
bearerAuth
query Parameters
page
integer <uint32> >= 0
Default: 1
Example: page=1

從 1 開始的頁碼。省略或傳入 0 會使用第 1 頁。

per_page
integer <uint32> [ 0 .. 20 ]
Default: 20
Example: per_page=10

分頁大小。省略或傳入 0 會使用伺服器預設值 20；大於 20 的值會被拒絕。

owned
boolean
Default: false

為 true 時，只回傳已驗證使用者擁有的映像。

keywords
string <= 100 characters

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
object (Pagination)
Array of objects (SDKImageInfo)

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "images": [
    ]
}

Spec

依區域列出建立執行個體可用的資源規格。

列出資源規格

Authorizations:
bearerAuth
query Parameters
machine_category
required
integer <int32> (MachineCategory)
Enum: 0 1 2 3

機器資源類別篩選。

from_image_id
required
string <= 64 characters
Example: from_image_id=img-87p9kq26

用於列出相容映像 specs 的 image resource ID。

page
integer <uint32> >= 0
Default: 1
Example: page=1

從 1 開始的頁碼。省略或傳入 0 會使用第 1 頁。

per_page
integer <uint32> [ 0 .. 20 ]
Default: 20
Example: per_page=10

分頁大小。省略或傳入 0 會使用伺服器預設值 20；大於 20 的值會被拒絕。

region_name
string <= 128 characters
Example: region_name=Region-01

選填的區域顯示/名稱值。省略時會跨區域列出 specs。

by_region
boolean
Default: false

依區域分組 response。在此模式下，分頁套用於區域。

instance_category
integer <int32> (SpecInstanceCategory)
Enum: 0 1

選填的 container/VM 篩選。省略時不依 instance category 篩選。

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
object (Pagination)
Array of objects (SpecInfo)

當 by_region 為 false 或省略時填入；當 by_region 為 true 時為空。

Array of objects (RegionSpecs)

當 by_region 為 true 時填入；當 by_region 為 false 或省略時為空。

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "specs": [
    ],
  • "regions": [ ]
}

Network

建立 mesh 網路、列出 mesh 或擁有的 NAT4 public-IP 網路，並將執行個體附加到 mesh 網路。

建立 mesh 網路

建立使用者 mesh 網路。network_type 是面向 SDK 的整數 enum；建立 mesh 時可省略或傳入 0。 SDK HTTP API 不開放 NAT4 建立。

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string <= 32 characters
region_name
required
string <= 128 characters
network_type
integer <int32> (NetworkType)
Enum: 0 1 2 3 4 5 6 7

數值型 network type。在 SDK network API 中，為了相容性，省略或 0 表示 mesh/UserVXLAN； 6 表示 list operations 使用的 NAT4 public-IP 網路。

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
network_id
string

編碼後的 network resource ID，例如 net-...。

Request samples

Content type
application/json
{
  • "network_type": 0,
  • "name": "train-mesh",
  • "region_name": "Region-01"
}

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": "",
  • "network_id": "net-od7pv75w"
}

列出 mesh 網路或擁有的 public-IP NAT4 網路

列出使用者擁有的網路。省略 network_type 或傳入 0 可列出 mesh 網路。傳入 6 (NAT4) 可列出使用者購買的 public IP 網路。

此 endpoint 回傳已擁有的 NAT4/public-IP 網路，不是可購買的 EIP pool。

Authorizations:
bearerAuth
query Parameters
page
integer <uint32> >= 0
Default: 1
Example: page=1

從 1 開始的頁碼。省略或傳入 0 會使用第 1 頁。

per_page
integer <uint32> [ 0 .. 20 ]
Default: 20
Example: per_page=10

分頁大小。省略或傳入 0 會使用伺服器預設值 20；大於 20 的值會被拒絕。

network_type
integer <int32> (NetworkType)
Enum: 0 1 2 3 4 5 6 7

mesh/UserVXLAN 可省略或傳入 0；NAT4 public IP 網路請傳入 6。

domain
integer <int32> (Domain)
Default: 0

Domain 數值。預設 domain 可省略或傳入 0。

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
object (Pagination)
Array of objects (VisibleNetwork)

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "networks": [
    ]
}

將既有執行個體加入 mesh 網路

將一個或多個使用者擁有的既有執行個體附加到使用者擁有的 mesh 網路。重複的 instance_ids 會在 quota 檢查前被忽略。目前 request 最多接受 10 個 instance ID。

Authorizations:
bearerAuth
Request Body schema: application/json
required
network_id
required
string <= 64 characters
instance_ids
required
Array of strings [ 1 .. 10 ] items [ items <= 64 characters ]

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
network_id
string
endpoint_ids
Array of strings

Request samples

Content type
application/json
{
  • "network_id": "net-od7pv75w",
  • "instance_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "network_id": "net-od7pv75w",
  • "endpoint_ids": [
    ]
}

列出網路 endpoints

Authorizations:
bearerAuth
query Parameters
network_id
required
string <= 64 characters
Example: network_id=net-od7pv75w
page
integer <uint32> >= 0
Default: 1
Example: page=1

從 1 開始的頁碼。省略或傳入 0 會使用第 1 頁。

per_page
integer <uint32> [ 0 .. 20 ]
Default: 20
Example: per_page=10

分頁大小。省略或傳入 0 會使用伺服器預設值 20；大於 20 的值會被拒絕。

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
object (Pagination)
Array of objects (SDKNetworkEndpoint)

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "endpoints": [
    ]
}

Snapshot

為 SDK 管理的執行個體建立快照，並列出 SDK 使用者擁有的快照。

為執行中的執行個體建立快照

使用伺服器設定的 SDK Snapshot Volume，為執行中的執行個體建立一個或多個快照。

Authorizations:
bearerAuth
Request Body schema: application/json
required
instance_id
required
string <= 64 characters
name
string <= 32 characters

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
snapshot_ids
Array of strings
instance_id
string
status
string

快照建立後的執行個體狀態名稱；目前成功 response 使用 Pausing。

Request samples

Content type
application/json
{
  • "instance_id": "ins-boyqp4g8",
  • "name": "checkpoint-001"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "snapshot_ids": [
    ],
  • "instance_id": "ins-boyqp4g8",
  • "status": "Pausing"
}

列出快照

Authorizations:
bearerAuth
query Parameters
page
integer <uint32> >= 0
Default: 1
Example: page=1

從 1 開始的頁碼。省略或傳入 0 會使用第 1 頁。

per_page
integer <uint32> [ 0 .. 20 ]
Default: 20
Example: per_page=10

分頁大小。省略或傳入 0 會使用伺服器預設值 20；大於 20 的值會被拒絕。

status
Array of integers <int32> (SnapshotStatus) [ items <int32 > ]
Items Enum: 0 1 2 3 4 5 6 7

可重複的數值 snapshot status 篩選。省略時使用伺服器預設的 snapshot listing semantics。

Responses

Response Schema: application/json
code
integer <int32> (ErrCode)
Enum: 0 1 6 7 10 17 20 88 89 114 133 164 174 192 194 198 199 206 208 215

與 SDK 相關的應用程式錯誤碼。0 表示成功。

msg
string
object (Pagination)
Array of objects (SDKSnapshotInfo)

Response samples

Content type
application/json
{
  • "code": 0,
  • "msg": "",
  • "pagination": {
    },
  • "snapshots": [
    ]
}

錯誤代碼

公開 SDK API 使用的錯誤碼：

code 名稱 說明
0 Success 請求成功。
1 InternalError 伺服器內部錯誤。
6 ParamIllegal 參數無效、缺少必填欄位、資源 ID 無效或擁有權不符。
7 PermissionDenied 權限不足。
10 MetaKeyExist custom_meta_key 已存在。
17 DiskQuotaExceeded 磁碟配額已超出。
20 IllegalStatus 執行個體目前狀態不允許執行所請求的操作。
88 OutOfNetCountLimit 網路數量配額已超出。
89 EndpointExist Endpoint 已存在。
114 TakingSnapNotAllowed 不允許建立快照。
133 NetNameRepeat 網路名稱已存在。
164 OutOfNetEndpointCountLimit 私有網路 endpoint 配額已超出。
174 ImageAlreadyExists 映像已存在。
192 ImagePendingLimitExceeded 映像 pending 數量已達上限。
194 ConflictPortMapping Bind IP 的 exposePort 被重複設定。
198 UserNodeQtyExceedQuota 使用者執行個體配額已超出。
199 UserSnapQtyExceedQuota 使用者快照配額已超出。
206 InvalidDomainInfo region_name 無法對應到有效的網域。
208 RegionAccessDenied 已驗證的使用者沒有所請求區域的存取權。
215 NoResourceAvailable 沒有可用的所需資源。

LLM

文件即將推出。

Skills

文件即將推出。