API 文件 — HiveCore

快速開始

三步驟開始使用 HiveCore API：

2. 在儀表板產生 API Key

3. 發送你的第一個請求：

curl -X POST https://gemma4-api.workers.dev/v1/chat/completions \
  -H "Authorization: Bearer sk-gemma4-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemma4","messages":[{"role":"user","content":"Hi"}]}'
    

認證方式

所有 API 請求需要在 Header 中帶上 API Key：

Authorization: Bearer sk-gemma4-xxxxxxxxxxxx

API Key 可以在儀表板產生。每個 Key 只會顯示一次，請妥善保存。

Chat Completions

POST /v1/chat/completions

與 OpenAI API 完全相容。如果你的程式碼已經在用 OpenAI，只需改 base_url 和 api_key。

Request Body

參數	類型	必填	說明
`model`	string	否	模型名稱，預設 "gemma4"
`messages`	array	是	對話訊息陣列
`temperature`	number	否	溫度 0-2，預設 0.7
`max_tokens`	integer	否	最大回應 token 數
`stream`	boolean	否	是否串流回應，預設 false

messages 格式

欄位	類型	說明
`role`	string	"system"、"user" 或 "assistant"
`content`	string	訊息內容

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gemma4",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Hello! ..." },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 45,
    "total_tokens": 57
  }
}
    

列出模型

GET /v1/models

回傳所有可用的模型列表。

串流回應

設定 stream: true 即可啟用 Server-Sent Events 串流。回應格式與 OpenAI 一致：

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"!"},"finish_reason":"stop"}]}

data: [DONE]

註冊

POST /auth/register

參數	類型	說明
`email`	string	Email 地址
`password`	string	密碼（至少 8 字元）
`name`	string	名稱

POST /auth/login

回傳 JWT Token，有效期 7 天。

API Keys

POST /auth/api-keys

產生新的 API Key。需要 JWT 認證。Key 只會在回應中顯示一次。

GET /auth/api-keys

列出你的所有 API Keys（只顯示前綴，不顯示完整 Key）。

DELETE /auth/api-keys/:id

刪除指定的 API Key。

用量查詢

GET /usage/me

查詢你的用量統計（今日/本月/總計/剩餘配額）。需要 JWT 認證。

錯誤碼

HTTP 狀態碼	說明
`400`	請求格式錯誤
`401`	未認證（API Key 無效或未提供）
`402`	配額用盡，請升級方案
`403`	權限不足或網域被封鎖
`404`	端點或模型不存在
`429`	請求過於頻繁（超過限流）
`503`	沒有可用的運算節點

限制

限制	免費	基本	專業
Tokens/月	10,000	100,000	1,000,000
API Keys	1	5	20
限流	10/min	60/min	300/min
運算節點	1	5	無限