Chat Completions API — TokSpan 文件

端點

http
POST https://api.tokspan.com/v1/chat/completions

快速範例

相同 API，所有模型通用。選擇您的語言：

from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.tokspan.com/v1")
response = client.chat.completions.create(model="gpt-4o", messages=[{"role":"user","content":"Hello"}])
print(response.choices[0].message.content)

javascript
import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.TOKSPAN_API_KEY, baseURL: 'https://api.tokspan.com/v1' });
const response = await client.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Hello' }] });
console.log(response.choices[0].message.content);

shell
curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

請求主體

參數	類型	必要	說明
model	string	是	模型 ID（例如 `gpt-4o`、`claude-opus-4-8`）。請參閱模型了解完整目錄。
messages	array	是	訊息物件陣列，包含 `role`（`system` / `user` / `assistant` / `tool`）和 `content`。
temperature	number	否	取樣溫度（0–2）。數值越高越隨機。預設值因模型而異。
max_tokens	integer	否	要生成的最大 Token 數。若省略，模型根據剩餘上下文決定。
stream	boolean	否	啟用 SSE 串流。預設值：`false`。請參閱下方串流。
top_p	number	否	核取樣 — 溫度的替代方案（0–1）。
stop	string / array	否	一個或多個序列，模型在遇到時停止生成。
frequency_penalty	number	否	減少 Token 重複（-2.0 到 2.0）。
presence_penalty	number	否	增加新主題的可能性（-2.0 到 2.0）。
seed	integer	否	用於可重現輸出的確定性取樣種子。
response_format	object	否	強制 JSON 輸出：`{"type": "json_object"}` 或 `{"type": "json_schema", "json_schema": {...}}`。
tools	array	否	用於函式呼叫的工具/函式定義。請參閱下方工具呼叫。
tool_choice	string / object	否	控制工具選擇：`"auto"`、`"none"`、`"required"`，或指定工具物件。
n	integer	否	要生成的補全數量。預設值：`1`。
user	string	否	用於濫用監控的最終使用者識別碼。

請求與回應範例

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What is the capital of France?" }
  ],
  "temperature": 0.7,
  "max_tokens": 256
}

json — Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The capital of France is Paris."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}

回應欄位

欄位	類型	說明
id	string	唯一請求識別碼 — 聯絡支援時使用
object	string	始終為 `"chat.completion"`
created	integer	回應生成時的 Unix 時間戳記（秒）
model	string	實際處理請求的模型（當自動容錯移轉或路由啟用時很有用）
choices	array	補全選項陣列。每個選項包含 `index`、`message`（`role` + `content`）和 `finish_reason`（`stop` / `length` / `tool_calls` / `content_filter`）
usage	object	Token 計數：`prompt_tokens`、`completion_tokens`、`total_tokens`。請參閱下方Token 用量。

了解 Token 用量

usage 物件回報用於計費的 Token 消耗：

prompt_tokens — 輸入訊息中的 Token（包含系統提示、歷史記錄及任何附加媒體轉換為 Token 等值）
completion_tokens — 模型在回應中生成的 Token
total_tokens — 提示 Token + 補全 Token 的總和 = 您的計費基礎

對於多模態輸入（圖片、音訊），供應商會將媒體轉換為 Token 等值。GPT-4o 對低解析度圖片約計 85 個 Token，高解析度約 170+。您的儀表板會顯示最終 Token 計數和每個請求的成本。

串流（SSE）

設定 stream: true 即可在模型生成時即時接收 Token。TokSpan 使用標準的伺服器傳送事件（SSE） — 完全相容 OpenAI 串流格式。

範例

from openai import OpenAI

client = OpenAI(api_key="sk-your-key", base_url="https://api.tokspan.com/v1")

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

shell
curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Tell me a story."}],
    "stream": true
  }'

SSE 區塊格式

每個區塊是一個以 data: 為前綴的 JSON 物件。串流以 data: [DONE] 結束：

SSE stream
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":" world"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

每個區塊包含 delta 物件（而非 message）。content 欄位在最後一個區塊可能為空或不存在。最後一個區塊會設定 finish_reason 且 delta 為空。

串流中的工具呼叫

當模型在串流期間呼叫函式時，工具呼叫區塊會以 tool_calls 形式在 delta 中到達 — 函式名稱和參數會逐步串流傳送。累積給定 tool_call_id 的所有區塊以組裝完整的函式呼叫，然後發回 role: "tool" 訊息。

重新連線：SSE 串流可能因網路問題中斷。在生產環境中，請在重新連線時實作帶抖動的指數退避。再次發送相同請求 — 串流將從頭開始（SSE 串流無法從中間點恢復）。

工具 / 函式呼叫

TokSpan 支援在所有相容模型上進行 OpenAI 相容的函式呼叫。在請求中定義您的工具，模型會以結構化 JSON 函式呼叫回應，由您的程式碼執行。

定義工具

傳遞包含函式定義的 tools 陣列。每個函式需要 name、description 和 JSON Schema parameters：

json
"tools": [{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get current weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}]

含工具呼叫的模型回應

當模型決定呼叫函式時，回應會包含 tool_calls 而非文字內容：

json
{
  "role": "assistant",
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "get_weather",
      "arguments": "{\"city\": \"Paris\"}"
    }
  }]
}

完整工具呼叫流程

發送請求，附帶 tools 定義
接收 tool_calls — 提取函式名稱和參數
執行函式（在您的程式碼中呼叫天氣 API、查詢資料庫等）
傳回結果，作為 role: "tool" 訊息，引用 tool_call_id
模型回應，以自然語言答覆並整合工具結果

支援的模型

工具呼叫支援以下模型：GPT-4o、GPT-4.1、Claude Opus 4.8、Claude Sonnet 4.6、Gemini 2.5 Pro、Gemini 2.5 Flash、DeepSeek V3、Mistral Large 3、Llama 4、Qwen3 等。請查看模型頁面了解各模型能力詳情。

專業提示：為獲得最佳工具呼叫可靠性，請使用已知擅長結構化輸出的模型：GPT-4o 和 Claude Opus 4.8 持續排名最高。使用 tool_choice: "required" 強制模型始終呼叫工具（適用於應將文字回應視為例外情況的代理管線）。

視覺 / 圖片輸入

對於 GPT-4o 和 Claude 4 Vision 等多模態模型，可在 content 陣列中以 URL 或 base64 編碼資料形式包含圖片：

json
{
  "model": "gpt-4o",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "What's in this image?" },
      { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
    ]
  }]
}

支援的圖片格式：PNG、JPEG、WebP、GIF（非動畫）。圖片大小上限因模型而異 — 通常每張圖片 20MB。Claude 模型也支援 PDF 文件作為視覺輸入。

JSON 模式 / 結構化輸出

透過設定 response_format 強制模型返回有效 JSON：

JSON 模式：{"type": "json_object"} — 模型返回有效 JSON。您必須在系統提示中包含「JSON」一詞。
結構化輸出：{"type": "json_schema", "json_schema": {...}} — 模型返回符合您確切 Schema 的 JSON。GPT-4o 及更新版本模型支援。

串流 + JSON：設定 response_format 進行串流時，模型會串流 JSON Token。所有區塊組裝完成後，完整回應為有效 JSON — 請在串流完成後進行驗證。