快速開始

本頁帶你完成最小可行的接入流程。全程只需要三樣東西：API Key、Base URL、一個模型代號。

前置需求

項目	說明
瓜瓜AI 帳號	用於兌換與管理 API Key（見兌換與取得 API Key）
API Key	你的存取憑證，格式為字串；請勿外流
可發送 HTTPS 請求的環境	curl、Python、Node.js、或任何 OpenAI 相容客戶端
模型代號	呼叫時 model 欄位要填的值，見 支援模型

API Key 從網頁主控台取得

登入瓜瓜AI 控制台後，點擊左側導覽列的**「API 密钥」，再點擊右上角的「创建密钥」**即可建立金鑰；完整圖文步驟請見兌換與取得 API Key。

取得金鑰後，請以環境變數保存，不要寫進原始碼。

步驟一：取得並保存 API Key

取得金鑰後，建議立刻存進環境變數：

macOS / Linux

export GUAGUA_API_KEY="YOUR_API_KEY"

Windows PowerShell

$env:GUAGUA_API_KEY = "YOUR_API_KEY"

.env 檔案

# .env（請加入 .gitignore，不要提交到版本控制）
GUAGUA_API_KEY=YOUR_API_KEY

步驟二：確認 Base URL

瓜瓜AI 的 API Base URL 固定為：

https://api.guagua5487.xyz/v1

呼叫時是 Base URL ＋ 端點路徑：

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

注意 /v1

/v1 屬於 Base URL 的一部分，請勿省略，也不要重複堆疊成 /v1/v1/...。常見寫法錯誤整理於 Base URL。

步驟三：發出第一個請求

cURL

curl 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": "請用一句話說明什麼是 API。" }
    ]
  }'

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",           # 或 os.environ["GUAGUA_API_KEY"]
    base_url="https://api.guagua5487.xyz/v1",
)

resp = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "請用一句話說明什麼是 API。"}],
)

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: 'user', content: '請用一句話說明什麼是 API。' }]
})

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

若請求成功，你會收到一段 JSON，其中模型回覆位於 choices[0].message.content。完整欄位說明見 Chat Completions，逐步拆解見 第一個 API 請求。

步驟四：選擇你的接入方式

你的情境	建議做法
已有 OpenAI SDK 專案	只改 base_url 與 api_key，見 OpenAI SDK
想用現成桌面／網頁客戶端	見 Cherry Studio 或 通用相容客戶端
需要即時逐字輸出	設定 stream: true，見 串流輸出
想自建 HTTP 請求	直接依 Chat Completions 組裝 JSON

完成檢查清單

• [ ] API Key 已存放於環境變數，未寫入原始碼
• [ ] Base URL 為 https://api.guagua5487.xyz/v1，且未重複 /v1
• [ ] 請求帶有 Authorization: Bearer <API_KEY> 標頭
• [ ] Content-Type 為 application/json
• [ ] model 使用實際存在的模型代號（見 支援模型）
• [ ] messages 為陣列，每筆都有 role 與 content

遇到錯誤？

狀態碼	可能原因	前往
400	請求格式錯誤、缺少必填欄位	400 Bad Request
401	金鑰缺失、格式錯誤或無效	401 Unauthorized
403	金鑰有效但無權限	403 Forbidden
429	請求過於頻繁	429 Too Many Requests
5xx	上游服務異常	5xx 上游錯誤