# 提示詞自動優化

此 API 用於使用指定的語言模型（`model`）和原始提示詞（`prompt_id`），自動產生優化後的提示內容。  
系統會依輸入語言（中文或英文）將原始 Prompt 整理為結構化格式（角色、專長與任務、叮嚀與限制），並將結果**儲存為一筆新的 Prompt**；原始 Prompt 不會被修改。

```bash
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/prompts/{prompt_id}/optimize/auto?model={model}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY"
```

#### Request Headers

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

#### Path Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| prompt_id | string (uuid) | 要優化的原始提示詞唯一鍵 | true |

#### Query Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| model | string | 用來優化 Prompt 的模型名稱，可由「取得所有模型」API 查詢；省略則使用系統預設模型 | false |

#### Response Headers

| Key | Value |
| --- | --- |
| Status Code | 200 |

#### Response Body

```json
{
  "id": "6afecc03-ef73-4aa9-8ea6-88098047f3a2",
  "value": "## Role ##\nAn assistant that explains medical concepts such as antibiotics in plain language ...",
  "name": "Derived from Antibiotics Explanation",
  "metadata": {
    "tag": [
      "medication",
      "antibiotics"
    ],
    "derived_from": "dae76e24-ca4b-414f-92be-21abe36a70f7"
  },
  "created_at": "2025-06-09T07:33:47.632198Z"
}
```

**Field Explanation**  
回傳新建立的 Prompt，欄位同「[提示詞物件](https://privstation-docs.apmic.ai/latest/privai-400/提示詞物件.md)」章節內容。新 Prompt 的欄位規則如下：

| Field | Detail |
| --- | --- |
| id | 系統自動產生的新 UUID（與原始 Prompt 不同） |
| value | 模型產生的優化後 Prompt 內容 |
| name | `Derived from ` 加上原始 Prompt 的 `name`，例如 `Derived from Antibiotics Explanation` |
| metadata | 複製原始 Prompt 的 `metadata`，並加入 `derived_from` 欄位 |

在優化提示詞時，系統會自動於新產生的 Prompt 的 `metadata` 中加入一筆 `derived_from` 欄位，記錄來源的 `prompt_id`，方便後續追蹤來源關係與管理版本差異。

#### 可能的錯誤

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| `AUTH_001`、`AUTH_002`、`AUTH_003` | 401 / 403 | 缺少 Authorization header、API Key 無效或已過期，見 「錯誤代碼說明-身份驗證類」 |
| `PROMPT_001` | 404 | 原始 Prompt 不存在，或不屬於目前的 API Key，見 「錯誤代碼說明-提示詞管理類」 |

若指定的 `model` 無法使用或模型服務呼叫失敗，回應格式見「例外狀況處理」章節的「非錯誤代碼格式的回應」。
