API 概覽

OfoxAI 提供三種協議的 API 接入方式，完全相容各廠商官方 SDK。

協定建議： OpenAI 協定建議使用 Responses API，原生 Prompt Caching 支援更佳；呼叫 Claude 模型建議使用 Anthropic 原生協定，可取得完整功能與原生快取優勢。

Base URL

協議	Base URL	說明
OpenAI 相容	`https://api.ofox.io/v1`	相容 OpenAI SDK，支援所有模型
Anthropic 原生	`https://api.ofox.io/anthropic`	相容 Anthropic SDK，原生 Claude 體驗
Gemini 原生	`https://api.ofox.io/gemini`	相容 Google GenAI SDK

認證

所有協議使用統一的 OfoxAI API Key，但 Header 格式因協議而異：

協議	Header	格式
OpenAI	`Authorization`	`Bearer sk-xxx`
Anthropic	`x-api-key`	`sk-xxx`
Gemini	`x-goog-api-key`	`sk-xxx`

詳見 API Key 取得與使用。

可用端點

OpenAI 相容協議

端點	方法	說明
`/v1/chat/completions`	POST	建立對話補全
`/v1/embeddings`	POST	建立文字向量
`/v1/models`	GET	列出可用模型
`/v1/models/{model_id}`	GET	取得模型詳情
`/v1/images/generations`	POST	圖像生成

Anthropic 原生協議

端點	方法	說明
`/anthropic/v1/messages`	POST	建立 Messages

Gemini 原生協議

端點	方法	說明
`/gemini/v1beta/models/{model}:generateContent`	POST	生成內容
`/gemini/v1beta/models/{model}:streamGenerateContent`	POST	串流生成內容

型別化判斷（Decisions）

對內容做是／否、單選、評分判斷，返回附帶機率的結構化答案。見 Decisions API 文件。

端點	方法	說明
`/v1/decisions`	POST	統一格式，也可用 OpenAI SDK 呼叫
`/openai/v1/decisions`	POST	同上，供 base URL 為 `/openai/v1` 的 OpenAI SDK 使用
`/typesafe/v1/systemone`	POST	TypeSafe 官方格式，相容 TypeSafe SDK

影片生成（OpenRouter 相容）

統一的非同步影片生成 API。見 Video API 文件。

端點	方法	說明
`/v1/videos`	POST	建立影片生成任務
`/v1/videos/{id}`	GET	取得任務狀態與結果
`/v1/videos/{id}`	DELETE	取消任務

OfoxAI OpenAPI（帳戶）

與協議無關的平台介面，使用 OfoxAI API Key 鑑權。

端點	方法	說明
`/v1/user/balance`	GET	餘額查詢，相容 cc-switch

速率限制

OfoxAI 按量付費，所有使用者共享統一的速率策略，無套餐差異：

限制項	額度
RPM（請求/分鐘）	100（團隊級聚合）
TPM（Token/分鐘）	不限

RPM 按團隊聚合計算，多 Key 共享同一配額。如需更高速率配額，請聯繫 hi@ofox.ai 申請調整。

當觸發限流時，API 回傳 429 Too Many Requests，回應 Header 包含：


x-ratelimit-limit-requests: 100
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 1s

錯誤碼

所有協議回傳統一的 HTTP 狀態碼：

狀態碼	說明	常見原因
`200`	成功	—
`400`	請求錯誤	參數格式錯誤、缺少必填欄位
`401`	認證失敗	API Key 無效或過期
`403`	權限不足	帳戶無權存取該模型
`404`	資源不存在	模型 ID 錯誤
`429`	觸發限流	超過速率限制
`500`	伺服器錯誤	內部錯誤，請重試
`502`	上游錯誤	模型供應商服務異常
`503`	服務不可用	服務維護中

錯誤回應格式


{
  "error": {
    "code": "invalid_api_key",
    "message": "提供的 API Key 無效，請檢查後重試。",
    "type": "authentication_error"
  }
}

OfoxAI 擴充參數

OfoxAI 在標準協議基礎上提供擴充參數，用於進階路由和回退控制：


{
  "model": "openai/gpt-6.1-sol",
  "messages": [...],
  "extra_body": {
    "provider": {
      "fallback": ["anthropic/claude-sonnet-5.5", "google/gemini-3.8-flash"]
    }
  }
}

provider 須置於請求主體的 extra_body 中，放在頂層會回傳 400。詳見供應商路由和故障回退。