# Create calculation specification

Create a calculation specification.

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

## Preparation before calling

Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: ID of the workspace where the calculation specification is to be created, passed via the `X-Workspace-ID` Header.

First [Query the calculation specification management permission](get-compute-resource-spec-management-permission.md). A specification can only be created if the result is `true`. Specifications will affect the compute instances that can be created, please confirm the capacity and resource type before submitting.

## Request example

```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
  }'
```

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Spec ID. |
| `kind` | string | Yes | Computing resource type, can only be `task` or `query`. |
| `family` | string | Yes | Spec family identifier. |
| `family_name` | string | Yes | Specification family name. |
| `family_name_en` | string | Yes | English name of the specification family; cannot be empty. |
| `cpu_milli` | integer | Yes | CPU capacity, in millicore, must be greater than `0`. |
| `memory_mib` | integer | Yes | Memory capacity, in MiB, must be greater than `0`. |
| `gpu_count` | integer | No | Number of GPUs. |
| `gpu_memory_mib` | integer | No | GPU memory defined by a single card or specification, in MiB. |
| `gpu_cores` | integer | No | Number of GPU cores. |
| `credit_per_hour` | number | No | Credit usage per hour. |
| `description` | string | No | Specification. |
| `node_placement` | object | No | Node scheduling configuration. |
| `enabled` | boolean | No | Whether to allow the use of this specification; when omitted, it is `false`. |

## Successful response

Returns `200` on success. `data` returns the specification object after creation; save `data.id` for subsequent updates or to switch the enabled state.

```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
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.id` | string | Specification ID after creation. |
| `data.kind` | string | Resource type. |
| `data.family` | string | Specification family identifier. |
| `data.family_name` | string | Specification family name. |
| `data.family_name_en` | string | English name of the specification family. |
| `data.cpu_milli` | integer | CPU capacity in millicore. |
| `data.memory_mib` | integer | Memory capacity in MiB. |
| `data.gpu_count` | integer | Number of GPUs. |
| `data.gpu_memory_mib` | integer | GPU memory, unit is MiB. |
| `data.gpu_cores` | integer | Number of GPU cores. |
| `data.credit_per_hour` | number | Credit usage per hour. |
| `data.description` | string | Specification. |
| `data.description_en` | string | English specifications; system specifications can be returned. |
| `data.node_placement` | object | Node scheduling configuration. |
| `data.enabled` | boolean | Enabled status after creation. |
| `data.is_system` | boolean | Whether it is a built-in specification of the system. |
| `data.created_by` | string | Creator ID. |
| `data.updated_by` | string | The last updater ID. |
| `data.created_at` | string | Creation time. |
| `data.updated_at` | string | Last updated time. |

## Error response

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

### Common HTTP errors

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

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `INVALID_PARAMS`
  - The request body could not be parsed or `family_name_en` was not provided.
  - Check JSON format and provide non-empty `family_name_en`.
* - `401`
  - —
  - Missing, invalid or expired access credentials.
  - Check API Key.
* - `403`
  - `COMPUTE_RESOURCE_SPEC_FORBIDDEN`
  - The current identity does not have specification management rights.
  - Try again using an identity with appropriate permissions.
* - `409`
  - —
  - The spec ID or name conflicts with an existing spec.
  - Replace the conflicting logo, or check the existing specifications first.
* - `500`
  - `CREATE_SPEC_FAILED`
  - The server failed to create the specification.
  - Retain the error message and try again later; if failure persists, contact support.
```

## Follow-up operations

[List calculation specifications](list-compute-resource-specs.md) After confirming that the specifications are visible, then [Create a calculation instance](../compute-resources/create-compute-resource.md).