第一個 API 請求

本頁把「發出一個請求」拆成最小步驟，並解釋每個部分的用途。如果你只是想盡快跑通，可以先看快速開始。

請求組成

一個最小的 Chat Completions 請求包含四件事：

部分	內容	範例
方法與網址	`POST` ＋ Base URL ＋ `/chat/completions`	`POST https://api.guagua5487.xyz/v1/chat/completions`
驗證標頭	你的 API Key	`Authorization: Bearer YOUR_API_KEY`
內容型別標頭	固定為 JSON	`Content-Type: application/json`
請求主體	模型與對話內容	`{"model": "...", "messages": [...]}`

POSThttps://api.guagua5487.xyz/v1/chat/completions

完整範例

cURLPythonNode.js瀏覽器 fetch

bash

curl https://api.guagua5487.xyz/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      { "role": "system", "content": "你是一位樂於助人的助理，請用繁體中文回答。" },
      { "role": "user", "content": "請用三點說明為什麼要用 API。" }
    ]
  }'

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.guagua5487.xyz/v1",
)

resp = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {"role": "system", "content": "你是一位樂於助人的助理，請用繁體中文回答。"},
        {"role": "user", "content": "請用三點說明為什麼要用 API。"},
    ],
)

print(resp.choices[0].message.content)

javascript

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.GUAGUA_API_KEY,
  baseURL: 'https://api.guagua5487.xyz/v1'
})

const resp = await client.chat.completions.create({
  model: 'MODEL_ID',
  messages: [
    { role: 'system', content: '你是一位樂於助人的助理，請用繁體中文回答。' },
    { role: 'user', content: '請用三點說明為什麼要用 API。' }
  ]
})

console.log(resp.choices[0].message.content)

javascript

const res = await fetch('https://api.guagua5487.xyz/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    model: 'MODEL_ID',
    messages: [{ role: 'user', content: '請用三點說明為什麼要用 API。' }]
  })
})

const data = await res.json()
console.log(data.choices[0].message.content)

不要在瀏覽器前端放 API Key

上面的 fetch 範例只用於說明 HTTP 結構。把 API Key 放進前端程式碼會讓任何人都能取用你的額度；正式環境請由自家後端代為呼叫（見下方「安全做法」）。

回應長什麼樣

以下為 OpenAI 相容格式的示意結構（實際欄位與內容以服務端回傳為準）：

json

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1735689600,
  "model": "MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "第一點……第二點……第三點……"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

待補充

usage 的實際欄位與計算方式（是否包含快取 Token 等）尚待官方確認。範例中的 id、created、Token 數量皆為示意值。

回應欄位說明

欄位	型別	說明
`id`	string	本次回應的識別碼，回報問題時可提供
`object`	string	物件型別，通常為 `chat.completion`
`created`	integer	產生時間（Unix 秒）
`model`	string	實際用於產生回應的模型
`choices`	array	回應候選清單，通常取第一筆
`choices[].message.role`	string	通常為 `assistant`
`choices[].message.content`	string	模型回覆的文字內容
`choices[].finish_reason`	string	結束原因，例如 `stop`、`length`
`usage`	object	Token 用量統計（欄位待確認）

完整參數與回應說明見 Chat Completions。

讀取結果的建議做法

一定要檢查狀態碼，非 2xx 時讀取錯誤內容，不要直接解析 choices。
choices 可能是空陣列（例如內容被安全策略攔截），請先判斷長度。
content 可能為空字串或 null，前端請提供預設顯示。
長回應可能被截斷，檢查 finish_reason 是否為 length，必要時調整 max_tokens。

python

resp = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "你好"}],
)

if resp.choices:
    print(resp.choices[0].message.content or "")

安全做法

做法	說明
由後端呼叫	前端只與自家後端溝通，金鑰留在伺服器
使用環境變數	不要把金鑰寫進程式碼或提交到 Git
一環境一金鑰	開發／測試／正式分開，洩漏時可單獨停用
定期輪替	依你的資安政策更換金鑰
記錄請求 ID	回報問題時附上 `id` 與時間，便於追查

下一步

Chat Completions — 完整參數與回應
串流輸出 — 讓回覆逐字顯示
模型選擇 — model 該怎麼填
OpenAI SDK — 用 SDK 取代手寫 HTTP

第一個 API 請求 ​

請求組成 ​

完整範例 ​

回應長什麼樣 ​

回應欄位說明 ​

讀取結果的建議做法 ​

安全做法 ​

下一步 ​