OpenAI 相容性

瓜瓜AI 採用 OpenAI 相容的介面設計，目的是讓你沿用既有的 SDK、框架與客戶端，只更換連線資訊即可接入。

只需要改三件事

設定	原本（OpenAI）	改成（瓜瓜AI）
Base URL	`https://api.openai.com/v1`	`https://api.guagua5487.xyz/v1`
API Key	你的 OpenAI 金鑰	你的瓜瓜AI API Key
模型代號	`gpt-*` 等	瓜瓜AI 提供的模型代號，見支援模型

程式邏輯、SDK 方法名稱與回應解析方式通常不需要改動。

PythonNode.js

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": "user", "content": "你好"}],
)
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: 'user', content: '你好' }]
})
console.log(resp.choices[0].message.content)

相容範圍

層面	狀態	說明
端點路徑風格	相容	`/v1/chat/completions` 形式
驗證標頭	相容	`Authorization: Bearer <API_KEY>`
請求／回應格式	相容	JSON，`choices[].message.content` 結構
串流（SSE）	相容	`stream: true`，見串流輸出
OpenAI SDK 直連	相容	設定 `base_url` 即可，見 OpenAI SDK
對話補全以外端點	待補充	Embeddings、Images、Audio 等是否開放未確認
進階參數	待補充	`tools`、`response_format`、`logprobs` 等支援範圍未確認
錯誤物件結構	待補充	是否與 OpenAI 完全一致未確認
用量與計費 API	待補充	是否提供未確認

待補充

「相容」代表介面形式一致，不代表所有參數與行為都與 OpenAI 完全相同。上述標示「待補充」的項目，請以服務端實際回應為準；若你的程式依賴特定進階功能，請先小規模驗證再上線。

可以沿用的工具

類型	範例	設定方式
官方 SDK	OpenAI Python / Node SDK	設定 `base_url` 與 `api_key`，見 OpenAI SDK
桌面客戶端	Cherry Studio 等	新增 OpenAI 類型供應商，見 Cherry Studio
通用客戶端	任何支援自訂 OpenAI Base URL 的工具	見通用 OpenAI 相容客戶端
開發框架	支援自訂 OpenAI endpoint 的框架	填入 Base URL 與模型代號

待補充

實際「已驗證可用」的客戶端與框架清單尚待官方測試後補充。上表僅說明設定方式，不代表相容性已逐一驗證。

遷移步驟

備份現有設定：記下目前使用的模型與參數。
更換 Base URL：改為 https://api.guagua5487.xyz/v1（注意 /v1 不可省）。
更換金鑰：改用瓜瓜AI API Key，並存放於環境變數。
替換模型代號：把 gpt-* 等代號換成瓜瓜AI 的模型代號。
跑一次煙霧測試：非串流與串流各測一次。
檢查進階功能：若有使用 tools、response_format、logprobs 等，逐一驗證。
調整錯誤處理：確認你的程式能正確處理 400 / 401 / 403 / 429 / 5xx。

常見落差

症狀	可能原因	處理
SDK 回 404	`base_url` 少了 `/v1` 或多了端點路徑	見 Base URL
回 400 且提及未知參數	該參數未被支援	移除或改用支援的參數，見 400
串流沒有逐字出現	中介層緩衝了 SSE	見串流輸出
找不到模型	代號不屬於瓜瓜AI	見模型選擇
回 429	觸發速率限制	見 429

OpenAI 相容性 ​

只需要改三件事 ​

相容範圍 ​

可以沿用的工具 ​

遷移步驟 ​

常見落差 ​