创建云主机

POST/v2/instances

按规格与镜像创建实例，支持注入初始化脚本。

创建为异步操作，立即返回 202 与实例 ID，实例进入 starting。可通过 /v2/instances/{id} 轮询状态，或订阅 instance.ready Webhook 事件。

Bearer Token instances:write api.demo.acme-cloud.dev

请求参数

共 1 项

Idempotency-Key 可选请求头

string

幂等键

请求体

application/json

name 必填

string

实例名称，2–48 字符

region 必填

string · 默认 ap-east-1

地域

可选值ap-east-1ap-southeast-1

spec 必填

object

规格配置

cpu 必填

integer · 默认 2

vCPU 核数

可选值124816

memory_gb 必填

integer · 默认 4

内存（GB）

disk_gb 必填

integer · 默认 80

系统盘容量（GB）

image 必填

string · 默认 ubuntu-26.04-lts

镜像 ID 或别名

可选值ubuntu-26.04-ltsdebian-13rocky-10

ssh_key_ids 可选

array<string>

绑定的 SSH 密钥 ID 列表

labels 可选

object

标签键值对，用于批量运维筛选

user_data 可选

string

Cloud-init 初始化脚本，Base64 编码后不超过 16KB

响应

4 种状态

202 Accepted —— 已受理，实例创建中

响应示例

{
  "id": "ins_9c30de",
  "name": "api-01",
  "status": "starting",
  "region": "ap-east-1",
  "estimated_ready_in": 38
}

代码示例

cURL

curl -i -X POST 'https://api.demo.acme-cloud.dev/v2/instances' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: e88a-4d10-9f3c' \
  -d '{
  "name": "api-01",
  "region": "ap-east-1",
  "spec": {
    "cpu": 4,
    "memory_gb": 8,
    "disk_gb": 80
  },
  "image": "ubuntu-26.04-lts",
  "ssh_key_ids": [
    "key_1a2b"
  ],
  "labels": {
    "env": "prod",
    "role": "api"
  }
}'

注意事项

创建请求务必携带 Idempotency-Key，避免超时重试造成多台实例。