Chat Completions

建立對話補全（chat completion）。這是瓜瓜AI 的主要 API，採 OpenAI 相容的請求與回應格式。

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

請求標頭

標頭	必填	值	說明
Authorization	是	Bearer YOUR_API_KEY	你的 API Key
Content-Type	是	application/json	請求主體為 JSON
Accept	否	text/event-stream	使用串流時可一併指定

請求主體參數

參數	型別	必填	說明	支援狀態
model	string	是	要使用的模型代號	見 支援模型
messages	array	是	對話訊息陣列，見下節	支援
stream	boolean	否	true 時以 SSE 逐段回傳，見 串流輸出	支援
temperature	number	否	取樣隨機性，通常 0～2	待補充
top_p	number	否	核取樣參數，通常 0～1	待補充
max_tokens	integer	否	限制回覆長度	待補充
stop	string | array	否	遇到指定字串時停止生成	待補充
presence_penalty	number	否	主題新鮮度懲罰	待補充
frequency_penalty	number	否	重複詞懲罰	待補充
n	integer	否	產生幾個候選回覆	待補充
seed	integer	否	盡量讓輸出可重現	待補充
response_format	object	否	指定輸出格式（如 JSON）	待補充
tools / tool_choice	array / object	否	函式呼叫（Function Calling）	待補充
user	string	否	終端使用者標識，用於濫用追蹤	待補充

待補充

上表以 OpenAI 相容介面的常見參數列出。瓜瓜AI 實際支援的參數子集、預設值與上下限尚未確認；標示「待補充」者請先以服務端回應驗證，不要直接假設可用。若傳入不支援的參數，服務端可能忽略或回傳 400 Bad Request。

messages 結構

messages 是一個陣列，依對話順序排列，每筆至少包含 role 與 content。

角色	用途	說明
system	系統指示	設定助理的行為、語氣與限制；通常放在第一筆
user	使用者輸入	你的問題或指令
assistant	助理回覆	多輪對話時，放入先前的回覆以維持上下文
tool	工具結果	搭配函式呼叫使用（支援狀態待補充）

{
  "model": "MODEL_ID",
  "messages": [
    { "role": "system", "content": "你是一位技術文件助理，請用繁體中文回答。" },
    { "role": "user", "content": "什麼是串流輸出？" },
    { "role": "assistant", "content": "串流輸出是指伺服器逐段回傳結果……" },
    { "role": "user", "content": "那要怎麼啟用？" }
  ]
}

上下文是「無狀態」的

API 不會替你記住上一輪對話。多輪對話必須由你在每次請求中重新帶上先前的訊息。訊息越長，消耗的 Token 越多，也越容易超過長度上限（實際上限待補充）。

回應格式

非串流請求會回傳單一 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
  }
}

欄位	型別	說明
id	string	回應識別碼
object	string	物件型別
created	integer	建立時間（Unix 秒）
model	string	實際使用的模型
choices[]	array	回應候選清單
choices[].message.content	string	回覆內容
choices[].finish_reason	string	結束原因（如 stop、length；實際值待補充）
usage	object	Token 用量（欄位待補充）

使用範例

cURL

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": "什麼是串流輸出？" }
    ]
  }'

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": "什麼是串流輸出？"},
    ],
)

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

Node.js

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: '什麼是串流輸出？' }
  ]
})

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

串流版本

只要加上 "stream": true，回應就會改為 SSE 事件流，適合逐字顯示。完整說明與解析範例見 串流輸出。

錯誤處理

建議在程式碼中明確區分狀態碼，而非只依賴例外訊息：

import openai

try:
    resp = client.chat.completions.create(
        model="MODEL_ID",
        messages=[{"role": "user", "content": "你好"}],
    )
    print(resp.choices[0].message.content)
except openai.APIStatusError as e:
    print("status:", e.status_code)
    print("body:", e.response.text)

狀態碼	意義	文件
400	請求格式或參數錯誤	400 Bad Request
401	未通過驗證	401 Unauthorized
403	無存取權限	403 Forbidden
429	超過速率限制	429 Too Many Requests
5xx	上游服務異常	5xx 上游錯誤

待補充

瓜瓜AI 的錯誤回應主體結構（是否與 OpenAI 的 error.type / error.code 完全一致）、以及是否有自訂錯誤碼，尚待官方確認。

相關頁面

• 串流輸出
• 模型選擇
• OpenAI 相容性
• 支援模型