メインコンテンツまでスキップ
Glows.ai
API docs by Redocly

GLOWS SDK HTTP API ドキュメント (v1)

GLOWS SDK v1 は /sdk/v1 配下で、インスタンスのライフサイクル、イメージ送信、リソース仕様、ネットワーク、スナップショット API を提供します。

認証には Authorization: Bearer <token> ヘッダー内の SDK トークンを使用します。サーバーは Authorization クエリパラメーターも受け付け、JWT 検証の前にそれをヘッダーへコピーします。

アプリケーションエラーは 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

冪等な business lookup に使用する、グローバルに一意なカスタム 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

インスタンス entry command。

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 または省略時は 1 単位がデフォルトです。 GPU と CPU の両方のインスタンス作成に適用されます。 base_resource.resource_id または base_resource.unit_spec があり、 base_resource.unit_qty が 0 より大きい場合、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 が 0 より大きい場合はトップレベル unit_qty を上書きします。 0 または省略時はトップレベル値を保持します。unit_qty だけを持つ base_resource object では base-resource creation を有効にするには不十分です。resource_id または unit_spec を含めてください。

object (CreateInstanceExtraResource)

Extra resource description。Extra resources には resource ID や GPU fields はありません。

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

listNetworks が返す private network ID。現在のサーバーは 1 つのネットワークをサポートします。

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 parameter の不足は 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 リンクを 1 つ送信し、SDK から見えるイメージを一覧します。

コンテナイメージリンクを 1 つ送信

認証済み 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 を渡します。 NAT4 作成は SDK HTTP API では公開されていません。

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 ネットワークを一覧

ユーザー所有のネットワークを一覧します。mesh ネットワークを一覧するには network_type を省略するか 0 を渡します。ユーザーが購入した public IP ネットワークを一覧するには 6 (NAT4) を渡します。

この 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 ネットワークへ追加

1 つ以上の既存のユーザー所有インスタンスを、ユーザー所有の 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 を使用して、実行中のインスタンスのスナップショットを 1 つ以上作成します。

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 エンドポイントは既に存在します。
114 TakingSnapNotAllowed スナップショットの作成は許可されていません。
133 NetNameRepeat ネットワーク名は既に存在します。
164 OutOfNetEndpointCountLimit プライベートネットワークのエンドポイントクォータを超過しました。
174 ImageAlreadyExists イメージは既に存在します。
192 ImagePendingLimitExceeded イメージの保留数が上限を超過しました。
194 ConflictPortMapping 指定された Bind IP の exposePort は既に使用されています。
198 UserNodeQtyExceedQuota ユーザーのインスタンスクォータを超過しました。
199 UserSnapQtyExceedQuota ユーザーのスナップショットクォータを超過しました。
206 InvalidDomainInfo region_name を有効なドメインにマッピングできません。
208 RegionAccessDenied 認証されたユーザーは要求されたリージョンへのアクセス権を持っていません。
215 NoResourceAvailable 必要なリソースが利用できません。

LLM

ドキュメントは近日公開予定です。

Skills

ドキュメントは近日公開予定です。