模型與文字介面

模型目錄與文字對話都使用同一把平台 API Key。共用約定（基礎位址、驗證、限流、重試）請見驗證與基礎規範。

查詢模型清單

GET/v1/models

請求範例

這一步不需要請求內容，直接在請求標頭帶上 API Key 即可。傳回的 data[].id 就是後續所有呼叫要用的模型 ID。

請求

curl "https://locopalai.com/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

回應參數

參數	類型	說明
`object`	string	固定為 `list`
`success`	boolean	查詢成功時為 `true`
`data`	array	目前 Key 可呼叫的模型清單
`data[].id`	string	模型 ID，提交請求時請原樣填寫
`data[].object`	string	固定為 `model`
`data[].created`	integer	目錄記錄時間（Unix 秒）
`data[].owned_by`	string	模型提供者識別，僅供參考
`data[].supported_endpoint_types`	string[]	該模型可用的介面類型

object 與 success 是頂層欄位，不在 data[] 內。object 固定為 list， success 成功時為 true。判斷請求是否成功請以 HTTP 狀態碼為準，success 僅供輔助。

回應內容

{
  "data": [
    {
      "id": "doubao-seedance-2.0",
      "object": "model",
      "created": 1626777600,
      "owned_by": "doubaovideo",
      "supported_endpoint_types": ["openai"]
    },
    {
      "id": "claude-sonnet-4-5-20250929",
      "object": "model",
      "created": 1626777600,
      "owned_by": "claude",
      "supported_endpoint_types": ["anthropic", "openai"]
    }
  ],
  "object": "list",
  "success": true
}

傳回 "data": [] 表示目前 Key 所屬的呼叫分組沒有可用模型，請先確認分組設定或聯絡平台支援，不要改用頁面顯示名稱重試。模型目錄會隨授權與平台可用性變動，建議在服務啟動、使用者選擇模型或收到「模型無法使用」時重新整理一次。

錯誤回應

HTTP	回應	說明
`401`	`{"error":{"code":"","message":"Invalid token (request id: ...)","type":"new_api_error"}}`	API Key 缺少、錯誤或已失效
`500`	`{"error":{"message":"...","type":"new_api_error"}}`	目錄查詢失敗，保留請求識別碼後重試

文字對話

POST/v1/chat/completions

請求內容 · application/json

參數	類型	必填	說明
`model`	string	是	從 `/v1/models` 傳回的文字模型 ID
`messages`	array	是	依時間順序排列的訊息
`messages[].role`	string	是	`system`、`user` 或 `assistant`
`messages[].content`	string	是	目前訊息內容
`stream`	boolean	否	為 `true` 時使用 SSE 串流傳回，讀到 `[DONE]` 即結束
`temperature`	number	否	是否支援以目前模型的實際能力為準
`max_tokens`	integer	否	是否支援以目前模型的實際能力為準

請求範例

model 必須填寫 /v1/models 傳回的 id，不要使用頁面上的顯示名稱。 stream 設為 true 時會依 SSE 逐段傳回，讀到 [DONE] 即結束。

右側提供三種語言的等效寫法，切換標籤即可對照。

curl -X POST "https://locopalai.com/v1/chat/completions" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的文本模型 ID",
  "messages": [{ "role": "user", "content": "只回复两个字：你好" }],
  "stream": false
}
JSON

回應參數

參數	類型	說明
`id`	string	本次回應識別碼，用於排查與對帳
`object`	string	非串流時為 `chat.completion`
`created`	integer	回應時間（Unix 秒）
`model`	string	本次請求使用的模型 ID
`choices`	array	結果清單
`choices[].index`	integer	結果序號
`choices[].message.role`	string	固定為 `assistant`
`choices[].message.content`	string	生成的文字
`choices[].finish_reason`	string	結束原因，`length` 表示因長度限制而被截斷
`usage.prompt_tokens`	integer	輸入用量
`usage.completion_tokens`	integer	輸出用量
`usage.total_tokens`	integer	總用量
`choices[].message.refusal`	string / null	模型拒絕內容時的說明，一般回答通常為 `null`
`choices[].message.annotations`	array	模型的附加標註，可能為空

usage 還會包含本次計費的詳細用量欄位（快取命中、輸入/輸出拆分等），以實際傳回為準。部分通道還會傳回 latency_checkpoint、routing、system_fingerprint 等擴充欄位，用戶端應忽略不認識的欄位，不要依固定欄位全集解析。

回應內容

{
  "id": "msg_011CevNtsfivFKb6YP3WcL7A",
  "model": "claude-haiku-4-5-20251001",
  "object": "chat.completion",
  "created": 1789071575,
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20587,
    "completion_tokens": 6,
    "total_tokens": 20593
  }
}

串流回應（請求內容加上 "stream": true，回應為 text/event-stream）：

data: {"choices":[{"delta":{"content":"这是"}}]}
data: {"choices":[{"delta":{"content":"模型输出"}}]}
data: [DONE]

用戶端必須持續讀取直到 [DONE]；串流回應不要被中間層快取或拼接成重複內容。最後一個資料區塊可能只包含 usage，此時 choices 可能為空。

部分推理模型會將輸出額度優先保留給隱藏推理。實測請求 gpt-5-nano 且 max_tokens 過小時，HTTP 傳回 200，但 message.content 為空、finish_reason 為 length，usage.completion_tokens_details.reasoning_tokens 等於輸出上限。遇到這種情況應提高額度或改用非推理文字模型，不能把空字串當成模型故障或介面失敗。

伺服器端範例

const response = await fetch('https://locopalai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LOCOPAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '从 /v1/models 选择的模型 ID',
    messages: [{ role: 'user', content: '写一条产品简介。' }],
  }),
})

if (!response.ok) throw new Error(await response.text())
const data = await response.json()

不要將 API Key 放進瀏覽器程式碼；前端請求應先送到你的業務後端，再由後端轉發。

錯誤回應

{
  "error": {
    "code": "model_not_found",
    "message": "No available channel for model xxx under group xxx (distributor) (request id: ...)",
    "type": "new_api_error"
  }
}

HTTP	回應 / 原因	處理
`400`	`{"error":{"code":"","message":"Model name not specified, model name cannot be empty (request id: ...)","type":"new_api_error"}}`	請求內容缺少 `model`
`401`	`Invalid token`	API Key 缺少、錯誤或已失效
`503`	`{"error":{"code":"model_not_found","message":"No available channel for model ..."}}`	目前分組沒有該模型可用的通道，請改選同類模型或聯絡平台支援
`429`	請求頻率受限	退避後重試

完整說明請見錯誤碼與排查。

模型與文字介面

模型與文字介面

查詢模型清單

驗證方式

請求參數

請求範例

回應參數

回應內容

錯誤回應

文字對話

驗證方式

請求內容 · application/json

請求範例

回應參數

回應內容

推理模型可能傳回空內容

伺服器端範例

錯誤回應

本頁目錄