# 模型

讓 Mini App 使用 Cowork 裡已設定好的 AI 模型。API 金鑰留在 Cowork 內，永遠不會到達頁面。每次呼叫只有一個請求和一個回覆：沒有工具，也沒有對話紀錄。

## MAESTROSDK.llm.providers() <Badge type="warning" text="尚未發布" />

列出可以使用（已登入或已有金鑰）的模型來源，以及它們的模型和思考強度。

### 參數

無。

### 回傳值

`Promise<Provider[]>`。沒有設定任何來源、頁面沒有 Cowork 分頁身分，或呼叫失敗時，回傳空清單。

| 欄位 | 類型 | 說明 |
|---|---|---|
| `id` | `string` | 來源 id，作為 `provider` 傳給 `complete` |
| `label` | `string` | 顯示名稱 |
| `models[].id` | `string` | 模型 id，作為 `model` 傳入 |
| `models[].label` | `string` | 顯示名稱 |
| `models[].defaultEffort` | `string` | Cowork 預設使用的思考強度 |
| `models[].efforts[]` | `{ id, label }[]` | 這個模型接受的思考強度；把其中一個 `id` 作為 `effort` 傳入 |

### 示例

```js
const providers = await MAESTROSDK.llm.providers();
const first = providers[0]?.models[0];
```

## MAESTROSDK.llm.complete(request) <Badge type="warning" text="尚未發布" />

把一段提示詞送給一個模型，並回傳它的文字回覆。

### 參數

| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| `request.provider` | `string` | 是 | `providers()` 裡的一個來源 `id` |
| `request.model` | `string` | 是 | 該來源的一個模型 `id` |
| `request.effort` | `string` | 是 | 該模型的一個思考強度 `id` |
| `request.prompt` | `string` | 是 | 提示詞，最多 32,000 個字元 |

一次呼叫最多等待模型 120 秒。

### 回傳值

`Promise<{ ok: true, text: string } | { ok: false, error: string }>`

### 錯誤

| `error` | 意思 |
|---|---|
| `provider, model, effort and prompt are required` | 有欄位缺少或為空 |
| `prompt_too_long` | 提示詞超過 32,000 個字元 |
| `empty_prompt` | 提示詞只有空白 |
| `unknown_model` | 這個組合不在 `providers()` 裡 |
| `empty_reply` | 模型沒有回傳文字 |
| `no_instance` | 頁面沒有 Cowork 分頁身分 |
| `host_unavailable` | Cowork 無法接下這次呼叫 |
| 其他任何文字 | 模型自己的錯誤訊息，或 `model_failed` |

### 示例

```js
const [provider] = await MAESTROSDK.llm.providers();
const model = provider.models[0];
const reply = await MAESTROSDK.llm.complete({
  provider: provider.id,
  model: model.id,
  effort: model.defaultEffort,
  prompt: 'Summarise this note in one sentence: ...'
});
if (reply.ok) show(reply.text); else showError(reply.error);
```

## 相關

- [AI 對話：模型與思考強度](https://docs.micromeet.ai/zh-tw/chat/models.md): 在哪裡設定模型
- [概覽](https://docs.micromeet.ai/zh-tw/miniapp-sdk/overview.md): Mini App SDK 的所有模組