# 接口文檔

使用同一個 API 入口，連接你已獲授權的模型。

**OpenAI Chat Completions 相容**

## 快速開始

先在控制台建立普通 API Key，確認模型授權，再將以下設定填入客戶端。

| 項目 | 設定 |
| --- | --- |
| API Base URL | `https://api.tidebell.link/v1` |
| 接口格式 | OpenAI Chat Completions |
| API Key | 自己的 `bf-…` 普通 API Key |
| 模型 | 從下方模型清單選擇已授權且在線的模型 |

```bash
curl https://api.tidebell.link/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen3.5-9B_Uncensored","messages":[{"role":"user","content":"你好"}],"max_tokens":512}'
```

請將 YOUR_API_KEY 換成自己的 Key。不要把 Key 放在網址、公開程式碼或聊天訊息裡。

## 驗證與金鑰

AI API 使用 HTTP Bearer 驗證。模型必須同時在帳號與 API Key 的授權範圍內；帳號停用、Key 到期或撤銷後都無法使用。

```text
Authorization: Bearer YOUR_API_KEY
```

`bf-fp…` 是控制台登入 Key，不能用來呼叫模型。普通 API Key 也不能用來登入控制台。完整 API Key 只在建立時顯示一次；遺失時請撤銷並重新建立。

## 模型清單

`GET /v1/models` 回傳這把 Key 有權使用且已啟用的模型。出現在清單中不代表模型當下在線。

| Model ID（請完整照填） | 說明 |
| --- | --- |
| `Qwen3.5-9B` | 一般版 · Q4_K_M |
| `Qwen3.5-9B_Uncensored` | Uncensored 版 · Q4_K_M |
| `qwen3.8-27b-bf16` | 27B BF16 |
| `qwen3.8-27b-uncensored` | 27B Uncensored |
| `gemma4-12b-uncensored-balanced` | Gemma 4 12B · Balanced · QAT Q4_K_M；來源在線後可生成 |

```bash
curl https://api.tidebell.link/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"
```

模型可用性與上下文長度以實際配置為準；請向服務管理員確認在線狀態。

## 聊天補全

`POST /v1/chat/completions` · JSON 請求

| 欄位 | 用途 |
| --- | --- |
| `model` | 必填，模型 ID |
| `messages` | 必填，對話陣列，文字角色使用 system、user、assistant |
| `max_tokens` | 正整數，回覆上限；另接受 max_completion_tokens 別名 |
| `stream` | 預設 false；true 為 SSE 串流 |
| `temperature` | 隨機程度，0–2；實際效果依模型 |
| `tools / tool_choice` | 工具呼叫設定，是否成功需視模型及模板支援 |

### Python 範例

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.tidebell.link/v1",
    api_key=os.environ["TIDEBELL_API_KEY"],
)
response = client.chat.completions.create(
    model="Qwen3.5-9B_Uncensored",
    messages=[{"role": "user", "content": "你好"}],
    max_tokens=512,
)
print(response.choices[0].message.content)
print(response.usage)
```

一般文字回覆位於 `choices[0].message.content`。usage 可包含 prompt_tokens、completion_tokens、total_tokens；思考模型可能另外回傳推理欄位。

## 串流回覆

設定 `stream: true`。伺服器以 `text/event-stream` 回傳事件，最後用 `data: [DONE]` 結束。

```python
stream = client.chat.completions.create(
    model="Qwen3.5-9B_Uncensored",
    messages=[{"role": "user", "content": "你好"}],
    max_tokens=512,
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        text = chunk.choices[0].delta.content or ""
        print(text, end="", flush=True)
```

允許出現註解心跳、空 choices 或用量事件。串流已開始後遇到錯誤，可能以含 `error` 的 data 事件回傳；不能只憑 HTTP 200 判定生成成功。自行處理 SSE 時也要檢查錯誤事件。

## 用量與限制

透過此服務送出的請求及模型回覆（包含工具呼叫內容）會寫入服務端詳細日誌，供維護、故障排查與用量追蹤。日誌也記錄排隊、執行狀態、錯誤與模型回傳的上下文用量。驗證憑證會遮蔽，圖片本體不保存；本機詳細日誌由服務管理者保管，與控制台中依帳號權限顯示的用量明細分開。

「API Key 管理」可查看自己的每日請求額度、併發及回覆上限；「用量統計」可查看輸入／輸出 tokens。配額由具備相應權限的管理人員設定。

- 每日額度以 UTC 換日（台灣時間上午 8 時）。
- 同一把 Key 的併發跨模型計算，包含排隊與生成；超過上限回覆 429。
- 回覆要求超過 Key 上限時會縮減；未填 max_tokens 也會套用 Key 上限。
- 0 表示該項 Key 配額不限，模型上下文、硬體及服務排隊限制仍適用。
- 輸入與輸出合計仍須符合模型實際可用的上下文容量。

## 錯誤處理

| HTTP | 常見原因與處理 |
| --- | --- |
| 400 / 422 | 欄位或訊息格式不支援；檢查請求內容。 |
| 401 | 未帶 Key、Key 無效、撤銷或到期。 |
| 403 | 帳號或 Key 沒有模型／操作權限。 |
| 404 | 模型 ID、路徑錯誤，或模型已停用。 |
| 429 | 每日額度、Key 併發或等待佇列達上限；依 Retry-After 等待，避免立即重試。 |
| 502 / 503 | 模型離線、來源連線失敗或服務暫時不可用；稍後重試或聯絡管理員。 |

```json
{"error":{"message":"錯誤說明","type":"...","code":"key_concurrency_limit"}}
```

網路層錯誤也可能回傳 HTML，處理失敗時應先檢查狀態碼與 Content-Type。

## 常見問題

### Responses 與 Anthropic 相容介面

三種協定共用相同模型、bf- 金鑰、授權範圍、配額、佇列及用量紀錄。只有協定格式與路徑不同，不需要另開 Colab 或更換模型。

| 協定 | Base URL | POST 端點 |
| --- | --- | --- |
| Chat Completions | `https://api.tidebell.link/v1` | `/v1/chat/completions` |
| Responses | `https://api.tidebell.link/v1` | `/v1/responses` |
| Anthropic Messages | `https://api.tidebell.link/a` | `/a/v1/messages` |

Responses 使用 `Authorization: Bearer bf-...`。Anthropic 可使用 `x-api-key: bf-...` 或 Bearer（不要同時提供兩種），SDK 的 `anthropic-version: 2023-06-01` 可正常使用。請勿將完整 POST 網址當作 SDK Base URL，避免 SDK 重複補上路徑。

```python
from openai import OpenAI
import os
client = OpenAI(base_url="https://api.tidebell.link/v1", api_key=os.environ["TIDEBELL_API_KEY"])
response = client.responses.create(
    model="gemma4-12b-uncensored-balanced",
    input="請用繁體中文介紹你自己。",
    max_output_tokens=128,
    reasoning={"effort": "none"},
    store=False,
)
print(response.output_text)
```

```python
from anthropic import Anthropic
import os
client = Anthropic(base_url="https://api.tidebell.link/a", api_key=os.environ["TIDEBELL_API_KEY"])
message = client.messages.create(
    model="gemma4-12b-uncensored-balanced",
    max_tokens=128,
    messages=[{"role": "user", "content": "請用繁體中文介紹你自己。"}],
)
print(message.content[0].text)
```

支援文字、合法 Base64 圖片（仍取決於模型是否載入視覺）、用戶端 function/tool_use 呼叫與工具結果、`stream: true`。Responses 回傳具型別的 SSE 事件（例如 `response.output_text.delta`、`response.completed`）；Anthropic 回傳 `message_start`、`content_block_delta`、`message_stop` 等事件，不是 Chat Completions 的 `data: [DONE]`。工具參數分片會組合、驗證為完整 JSON 後發出對應工具事件；文字維持增量串流。

相容介面不是 OpenAI 或 Anthropic 官方模型託管服務，不會代為執行工具。模型名稱仍填 Tidebell 的實際 ID，不會把 `claude-*` 或 `gpt-*` 名稱自動映射到其他模型。

目前限制：Responses 無狀態，請傳送完整 `input`；`store:true`、`previous_response_id`、`conversation`、背景工作、內建網搜／檔案工具、自動截斷、額外 include 內容不支援。Anthropic 的簽章 thinking、prompt caching、beta 功能、非空 stop_sequences 及 token-counting 端點不支援。這些請求會明確回傳錯誤，不會假裝成功。普通 Key 的模型授權和輸出上限同樣生效。舊 Chat Completions 完整保留。

### 客戶端要選哪個格式？

選 OpenAI Chat Completions。請勿選 OpenAI Responses 或 Anthropic Messages；目前未提供這兩種接口。

### 可以傳圖片嗎？

這兩個 Qwen3.5-9B 部署目前以文字推論為準，尚未啟用經驗證的圖片能力。不要因模型名稱或客戶端有附件按鈕就視為支援圖片。

### 為什麼清單有模型卻不能生成？

模型來源可能尚未啟動、已停止或正在恢復。模型授權與在線狀態是不同條件。

---

接口文檔 · Tidebell · 最後更新 2026-10-18