# 创建计算规格

创建一个计算规格。

```text
POST https://moi.matrixorigin.cn/newmoi/compute-resource-specs
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：要创建计算规格的工作区 ID，通过 `X-Workspace-ID` Header 传递。

先[查询计算规格管理权限](get-compute-resource-spec-management-permission.md)。只有结果为 `true` 时才能创建规格。规格会影响可创建的计算实例，请在提交前确认容量和资源类型。

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 规格 ID。 |
| `kind` | string | 是 | 计算资源类型，只能为 `task` 或 `query`。 |
| `family` | string | 是 | 规格族标识。 |
| `family_name` | string | 是 | 规格族名称。 |
| `family_name_en` | string | 是 | 规格族英文名称；不能为空。 |
| `cpu_milli` | integer | 是 | CPU 容量，单位为毫核，必须大于 `0`。 |
| `memory_mib` | integer | 是 | 内存容量，单位为 MiB，必须大于 `0`。 |
| `gpu_count` | integer | 否 | GPU 数量。 |
| `gpu_memory_mib` | integer | 否 | 单卡或规格定义的 GPU 显存，单位为 MiB。 |
| `gpu_cores` | integer | 否 | GPU 核数。 |
| `credit_per_hour` | number | 否 | 每小时 Credit 用量。 |
| `description` | string | 否 | 规格说明。 |
| `node_placement` | object | 否 | 节点调度配置。 |
| `enabled` | boolean | 否 | 是否允许使用该规格；省略时为 `false`。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/compute-resource-specs" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "task-standard-small",
    "kind": "task",
    "family": "standard",
    "family_name": "标准",
    "family_name_en": "Standard",
    "cpu_milli": 2000,
    "memory_mib": 4096,
    "gpu_count": 0,
    "gpu_memory_mib": 0,
    "gpu_cores": 0,
    "credit_per_hour": 1,
    "enabled": true
  }'
```

## 成功响应

成功时返回 `200`。`data` 返回创建后的规格对象；保存 `data.id` 用于后续更新或切换启用状态。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "task-standard-small",
    "kind": "task",
    "family": "standard",
    "family_name": "标准",
    "family_name_en": "Standard",
    "cpu_milli": 2000,
    "memory_mib": 4096,
    "gpu_count": 0,
    "gpu_memory_mib": 0,
    "gpu_cores": 0,
    "credit_per_hour": 1,
    "description": "用于常规任务",
    "node_placement": {},
    "enabled": true
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.id` | string | 创建后的规格 ID。 |
| `data.kind` | string | 资源类型。 |
| `data.family` | string | 规格族标识。 |
| `data.family_name` | string | 规格族名称。 |
| `data.family_name_en` | string | 规格族英文名称。 |
| `data.cpu_milli` | integer | CPU 容量，单位为毫核。 |
| `data.memory_mib` | integer | 内存容量，单位为 MiB。 |
| `data.gpu_count` | integer | GPU 数量。 |
| `data.gpu_memory_mib` | integer | GPU 显存，单位为 MiB。 |
| `data.gpu_cores` | integer | GPU 核数。 |
| `data.credit_per_hour` | number | 每小时 Credit 用量。 |
| `data.description` | string | 规格说明。 |
| `data.description_en` | string | 英文规格说明；系统规格可返回。 |
| `data.node_placement` | object | 节点调度配置。 |
| `data.enabled` | boolean | 创建后的启用状态。 |
| `data.is_system` | boolean | 是否为系统内置规格。 |
| `data.created_by` | string | 创建者标识。 |
| `data.updated_by` | string | 最后更新者标识。 |
| `data.created_at` | string | 创建时间。 |
| `data.updated_at` | string | 最后更新时间。 |

## 错误响应

```json
{
  "code": "INVALID_PARAMS",
  "msg": "family_name_en is required",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `INVALID_PARAMS`
  - 请求体无法解析，或未提供 `family_name_en`。
  - 检查 JSON 格式，并提供非空的 `family_name_en`。
* - `401`
  - —
  - 缺少、无效或已失效的访问凭据。
  - 检查 API Key。
* - `403`
  - `COMPUTE_RESOURCE_SPEC_FORBIDDEN`
  - 当前身份没有规格管理权限。
  - 使用具有相应权限的身份重试。
* - `409`
  - —
  - 规格 ID 或名称与现有规格冲突。
  - 更换冲突标识，或先检查已有规格。
* - `500`
  - `CREATE_SPEC_FAILED`
  - 服务端未能创建规格。
  - 保留错误信息并稍后重试；持续失败时联系支持人员。
```

## 后续操作

[列出计算规格](list-compute-resource-specs.md)确认规格可见后，再[创建计算实例](../compute-resources/create-compute-resource.md)。