接口文檔

快速開始

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

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 到期或撤銷後都無法使用。

Authorization: Bearer YOUR_API_KEY

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

模型清單

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

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

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

聊天補全

POST /v1/chat/completions · JSON 請求

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] 結束。

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 配額不限，模型上下文、硬體及服務排隊限制仍適用。
• 輸入與輸出合計仍須符合模型實際可用的上下文容量。

錯誤處理

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

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

常見問題

Responses 與 Anthropic 相容介面

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

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

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)

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