# 新增提示詞

此 API 用於建立一個新的 Prompt，作為語言模型推論時的前置模板。  
建立後的 Prompt 可在 Chat Completions 中以 `prompt_id` 引用。Prompt 隸屬於建立它的 API Key，其他 API Key 無法查詢或使用（詳見「Tenant Scope 與資料隔離」章節）。

```bash
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/prompts' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "tag": [
        "medication",
        "antibiotics"
      ]
    },
    "name": "Antibiotics Explanation",
    "value": "Antibiotics are a type of medication used to treat bacterial infections. They work by either killing the bacteria or preventing them from reproducing, allowing the body'\''s immune system to fight off the infection. Antibiotics are usually taken orally in the form of pills, capsules, or liquid solutions, or sometimes administered intravenously. They are not effective against viral infections, and using them inappropriately can lead to antibiotic resistance.\nExplain the above in one sentence:"
  }'
```

#### Request Headers

| Key | Value |
| --- | --- |
| Request Method | POST |
| accept | application/json |
| Authorization | `Bearer $PRIVAI_API_KEY` |
| Content-Type | application/json |

#### Request Payload

```json
{
  "metadata": {
    "tag": [
      "medication",
      "antibiotics"
    ]
  },
  "name": "Antibiotics Explanation",
  "value": "Antibiotics are a type of medication used to treat bacterial infections. They work by either killing the bacteria or preventing them from reproducing, allowing the body's immune system to fight off the infection. Antibiotics are usually taken orally in the form of pills, capsules, or liquid solutions, or sometimes administered intravenously. They are not effective against viral infections, and using them inappropriately can lead to antibiotic resistance.\nExplain the above in one sentence:"
}
```

**Field Explanation**

| Field | Type | Detail | Required |
| --- | --- | --- | --- |
| id | string (uuid) | 自訂此 Prompt 的 UUID；省略則由系統自動產生。若指定的 `id` 已被使用，回傳 `PROMPT_002`（409） | false |
| metadata | object | 使用者自訂的描述資訊 | false |
| name | string | Prompt 名稱；省略時由系統自動命名 | false |
| value | string | Prompt 內容 | true |

#### Response Headers

| Key | Value |
| --- | --- |
| Status Code | 201 |

#### Response Body

```json
{
  "id": "dae76e24-ca4b-414f-92be-21abe36a70f7",
  "value": "Antibiotics are a type of medication used to treat bacterial infections. They work by either killing the bacteria or preventing them from reproducing, allowing the body's immune system to fight off the infection. Antibiotics are usually taken orally in the form of pills, capsules, or liquid solutions, or sometimes administered intravenously. They are not effective against viral infections, and using them inappropriately can lead to antibiotic resistance.\nExplain the above in one sentence:",
  "name": "Antibiotics Explanation",
  "metadata": {
    "tag": [
      "medication",
      "antibiotics"
    ]
  },
  "created_at": "2025-01-01T00:15:00.000Z"
}
```

**Field Explanation**  
回傳「[提示詞物件](https://privstation-docs.apmic.ai/latest/privai-400/提示詞物件.md)」章節內容。

#### 可能的錯誤

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| `AUTH_001`、`AUTH_002`、`AUTH_003` | 401 / 403 | 缺少 Authorization header、API Key 無效或已過期，見 「錯誤代碼說明-身份驗證類」 |
| `PROMPT_002` | 409 | 指定的 `id` 已存在，見 「錯誤代碼說明-提示詞管理類」 |

缺少必填欄位 `value`，或 `id` 不是合法的 UUID 時，會回傳 422 參數驗證錯誤（格式見「例外狀況處理」章節）。
