文字
建立聊天補全
為聊天訊息建立補全
請求主體
支援的選填參數、可接受的值和預設值取決於所選模型。在設定取樣、推理或工具選項之前,請先查看其模型詳細資訊。若模型無法支援某項控制參數(例如某些模型上大於 1 的 n),將會被拒絕並傳回 4xx 錯誤。而次要的取樣控制參數(例如 seed 或懲罰參數)則可能會被忽略。
要使用的模型 ID。可用選項請參閱模型。
構成對話的訊息列表。
每個訊息物件包含:
role(string):system,developer,user,assistant,tool,functioncontent(string | array | null):訊息內容
對於包含 tool_calls 的 assistant 訊息,content 可以省略或設為 null。
當 content 為陣列時,TokenLab 為相容模型支援結構化多模態區塊:
- 文字:
{ "type": "text", "text": "..." } - 圖片:
{ "type": "image_url", "image_url": { "url": "https://..." } } - 影片:
{ "type": "video_url", "video_url": { "url": "https://..." } } - 音訊:
{ "type": "input_audio", "input_audio": { "data": "https://... or base64 data URL", "format": "wav" } },或{ "type": "audio_url", "audio_url": { "url": "https://..." } }
對於多模態輸入,請使用可公開存取的 https URL。圖片也可以透過 base64 data URL 傳送。支援的媒體類型取決於所選模型。
取樣溫度。支援程度、允許的值和預設值取決於所選模型;省略此欄位將使用其預設值。
要生成的最大 token 數。傳送 max_tokens 或 max_completion_tokens 其中之一即可,請勿兩者同時傳送:透過其他通訊協定提供服務的模型可能會拒絕同時包含兩者的請求。
在具備思考能力的模型上,思考 token 也會計入此限制。如果限制過小,所有配額可能都會用於思考而導致訊息本文為空,且已使用的 token 仍會計費。請提高限制,或在模型允許的情況下關閉思考功能,例如設定 "reasoning_effort": "none"。在 deepseek-v4.1-flash(別名 deepseek-flash)上,"thinking": {"type": "disabled"} 也可以關閉此功能。
在請求執行之前,TokenLab 會檢查您的餘額是否足以支付此最大值。在餘額偏低時,即使回覆很短,過大的數值也可能會傳回 402。
false若為 true,部分訊息增量將以伺服器發送事件(SSE)的形式傳送。請參閱串流。
對於長輸出(數千個 token 或更多),請設定 stream: true,以免用戶端和 Proxy 在等待完整回應時逾時。
串流選項。設定 include_usage: true 以在 data: [DONE] 之前額外接收一個包含 token 使用量的區塊。若未設定,串流中將不包含使用量資訊。
核取樣參數。建議調整此參數或 temperature 其中之一,而非兩者同時調整。
介於 -2.0 到 2.0 之間的數值。正值會對重複出現的 token 進行懲罰。
介於 -2.0 到 2.0 之間的數值。正值會對已在文字中出現過的 token 進行懲罰。
停止序列或序列列表。支援程度和序列數量上限取決於所選模型。
模型可呼叫的工具列表(函式呼叫)。每個工具皆為 { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } }。請參閱結構化輸出與工具呼叫。
控制模型如何使用工具。選項包括:auto、none、required,或使用 { "type": "function", "function": { "name": "..." } } 強制使用特定工具。
在所選模型支援的情況下,允許在單次助理回合中進行多次工具呼叫。
補全內容的上限,包含思考 token。為較新 OpenAI 模型家族所使用,作為 max_tokens 的替代方案。兩者僅能傳送其中一個。
支援該功能的模型的推理工作量。可接受的值取決於所選模型。
對於 Claude 模型,此值用於設定模型的思考模式:在具備調適型思考的模型上代表工作量等級,或在支援思考預算的模型上代表預算。在允許的模型上,none 會關閉思考功能。若設定了模型不支援的值,將會被拒絕並傳回 400,代碼為 invalid_value,錯誤訊息中會列出支援的值。在開啟思考功能時,Claude 會拒絕不為 1 的 temperature、top_k、不在 0.95–1 範圍內的 top_p 以及預填的助理訊息。強制指定 tool_choice 適用於調適型思考,但不適用於思考預算。
Claude 模型的選項。
prompt_caching(boolean):設為true可快取提示詞的開頭部分。TokenLab 會將系統提示詞結尾和最新使用者訊息標記為快取點。後續以相同內容開頭的請求將從快取中讀取。請使用此選項或您自己的cache_control標記,勿兩者同時使用。prompt_caching_ttl(string):5m(預設)或1h。當處理請求的服務無法保留快取一小時時,TokenLab 可以改用 5 分鐘快取,而非拒絕該請求。
extra.prompt_caching 與 extra.prompt_caching_ttl 亦被接受為相同選項。價格以及如何查看快取 token,請參閱提示詞快取。
支援該功能的模型的取樣隨機種子。不保證能產生完全相同的輸出。
要生成的補全數量。支援的模型接受 1-128。許多模型僅支援 1。
是否傳回對數機率。
要傳回的前幾高對數機率數量(0-20)。需要設定 logprobs: true。
支援該功能的模型的 Top-K 取樣。
回應格式。使用 {"type": "text"}(預設)、{"type": "json_object"} 啟用 JSON 模式,或使用 {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}} 指定 JSON Schema。支援程度取決於所選模型。請參閱結構化輸出與工具呼叫。
修改指定 token 出現的機率。將 token ID(以字串形式)對應到 -100 至 100 的偏差值。支援程度取決於所選模型。
TokenLab 以標準服務層級提供 Chat 請求服務並計費。接受 auto 與 default。其他值(例如 flex 或 priority)會從請求中移除,且請求將按標準價格計費。
代表您的終端使用者的唯一識別碼,用於濫用行為監控。
回應
補全的唯一識別碼。
一律為 chat.completion。
建立補全時的 Unix 時間戳記。
用於補全的模型。
補全選項列表。
每個選項包含:
index(integer):選項索引message(object):生成的訊息finish_reason(string):模型停止的原因,例如stop、length、tool_calls或content_filter
當模型進行思考時,message 還可以包含:
reasoning_content(string):思考文字。部分模型僅傳回摘要或不傳回文字。reasoning_details(array):包含簽章的思考區塊。若要在具備思考的情況下繼續對話(例如在工具呼叫之後),請在助理訊息中將其原樣傳回。
在串流中,相同欄位將以 delta.reasoning_content 與 delta.reasoning_details 形式傳送。
Token 使用量統計資訊。
prompt_tokens(integer):提示詞中的 token 數completion_tokens(integer):補全中的 token 數,包含思考 tokentotal_tokens(integer):使用的總 token 數prompt_tokens_details.cached_tokens(integer):從快取讀取的提示詞 token 數cache_creation_input_tokens(integer):寫入快取的提示詞 token 數。僅在數值大於 0 時出現completion_tokens_details.reasoning_tokens(integer):思考 token 數(當模型有回報時)
在串流中,僅當 stream_options.include_usage 為 true 時才會傳送使用量資訊。
請求
curl -X POST "https://api.tokenlab.sh/v1/chat/completions" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-terra",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
],
"max_tokens": 1000
}'多模態範例
{
"model": "gemini-2.5-pro",
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "Describe this video briefly." },
{ "type": "video_url", "video_url": { "url": "https://example.com/demo.mp4" } }
]
}
],
"max_tokens": 64
}回應
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1706000000,
"model": "gpt-5.6-terra",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 20,
"completion_tokens": 9,
"total_tokens": 29
}
}串流
當設定 stream: true 時,回應為 text/event-stream。每個事件皆為帶有 chat.completion.chunk 物件的 data: {...},其 choices[].delta 攜帶新增文字、工具呼叫引數或思考文字。串流以 data: [DONE] 結束。以 : 開頭的行是保持連線註解:請忽略它們。未以 [DONE] 或未包含 finish_reason 結束的串流是不完整的。請參閱串流。
錯誤
錯誤使用 OpenAI 風格的 error 物件。常見情況:400 表示無效欄位或模型不接受的值,401 表示金鑰無效,402 表示餘額不足,413 表示輸入超出大小限制,429 表示達到速率限制。請參閱處理 API 錯誤。
授權
BearerAuth API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
選填鍵值,用於防止相同請求執行第二次。請為每個請求發送一個新的唯一值(例如 UUID),並在逾時重試時保留該值。使用相同鍵值的重試不會再次執行:它會回傳 409 狀態碼與 idempotency_replay_unavailable,若請求主體已變更,通常會回傳 idempotency_conflict。例外情況:若非串流(non-stream)結果在客戶端斷線後完成,則 24 小時內使用相同鍵值與主體的重試會回傳該結果(上限 1 MB),並帶有 Idempotent-Replayed: true 標頭,且不會進行第二次扣款。超過 255 個字元的鍵值將被忽略,該請求將不具備冪等性保護。請參閱 安全地使用冪等鍵進行重試。
1 <= length <= 255請求主體
application/json
回應
application/json
application/json
application/json
application/json
application/json
application/json
application/json