Base URL

所有瓜瓜AI API 請求都指向同一個 Base URL：

https://api.guagua5487.xyz/v1

Base URL 一覽

項目	值
協定	https（僅支援 HTTPS）
主機	api.guagua5487.xyz
路徑前綴	/v1
完整 Base URL	https://api.guagua5487.xyz/v1
文檔站（本網站）	https://docs.api.guagua5487.xyz

完整網址怎麼組

Base URL                        端點路徑
https://api.guagua5487.xyz/v1 + /chat/completions
= https://api.guagua5487.xyz/v1/chat/completions

在 SDK 中，Base URL 與端點路徑是分開設定的：SDK 會自動接上 /chat/completions，因此 base_url 只需要填到 /v1。

Python — 正確

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

Node.js — 正確

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

Python — 錯誤

# 多寫了端點路徑，SDK 會再補一次，變成 /v1/chat/completions/chat/completions
base_url="https://api.guagua5487.xyz/v1/chat/completions"

Node.js — 錯誤

// 少了 /v1，請求會打到不存在的路徑
baseURL: 'https://api.guagua5487.xyz'

常見端點

以下為 OpenAI 相容介面的慣例路徑。瓜瓜AI 目前實際開放的端點清單待官方確認，使用前請以服務端回應為準。

方法	路徑	完整網址	說明	狀態
POST	/chat/completions	https://api.guagua5487.xyz/v1/chat/completions	建立對話補全	主要端點，見 Chat Completions
GET	/models	https://api.guagua5487.xyz/v1/models	列出可用模型	待補充
POST	/embeddings	https://api.guagua5487.xyz/v1/embeddings	文字向量	待補充
POST	/images/generations	https://api.guagua5487.xyz/v1/images/generations	圖片生成	待補充
POST	/audio/transcriptions	https://api.guagua5487.xyz/v1/audio/transcriptions	語音轉文字	待補充

待補充

上表中標示「待補充」的端點不代表已支援或未支援，僅表示本文件尚未取得官方確認。請勿在正式環境依賴未確認的端點。

常見寫法錯誤

錯誤寫法	問題	正確寫法
https://api.guagua5487.xyz	缺少 /v1	https://api.guagua5487.xyz/v1
https://api.guagua5487.xyz/v1/	結尾多餘斜線，可能組出 //chat/completions	去掉結尾斜線
https://api.guagua5487.xyz/v1/v1	版本前綴重複	只保留一個 /v1
http://api.guagua5487.xyz/v1	使用非加密協定	改用 https://
api.guagua5487.xyz/v1	缺少協定，多數客戶端會直接失敗	補上 https://

驗證連線是否正常

最單純的驗證方式是對主要端點發一個最小請求，並觀察 HTTP 狀態碼：

cURL

curl -i https://api.guagua5487.xyz/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GUAGUA_API_KEY" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{ "role": "user", "content": "ping" }]
  }'

只檢查狀態碼

curl -o /dev/null -s -w "%{http_code}\n" \
  https://api.guagua5487.xyz/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GUAGUA_API_KEY" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"ping"}]}'

狀態碼判讀：

狀態碼	意義	下一步
200	連線與驗證皆正常	可以開始接入
400	連線正常，但請求內容有誤	400 Bad Request
401	連線正常，但金鑰有問題	401 Unauthorized
403	金鑰有效但無使用權限	403 Forbidden
429	請求過於頻繁	429 Too Many Requests
5xx	上游服務異常	5xx 上游錯誤

若連狀態碼都拿不到（連線逾時、DNS 失敗、TLS 錯誤），通常是網路、防火牆、Proxy 或 DNS 問題，而非金鑰問題。

需要自訂主機嗎？

若你的環境必須經過自架 Proxy 或閘道，請確認：

1. Proxy 有正確轉發 Authorization 標頭。
2. Proxy 未改寫路徑（/v1 需保留）。
3. Proxy 未對 SSE 回應做緩衝（否則串流會延遲；見 串流輸出）。

待補充

瓜瓜AI 是否提供多區域端點、備援網域或專用閘道，尚待官方確認。