API 概覽 - OpenModex

基底 URL

環境	URL
正式環境	`https://api.openmodex.com/v1`
沙盒環境	`https://api-sandbox.openmodex.com/v1`

使用沙盒環境進行開發和測試——它的行為與正式環境完全一致，但不會產生費用。所有 API 端點都與 OpenAI 相容。如果您已在使用 OpenAI API，只需更改基底 URL 和 API 金鑰即可切換。

身分驗證

在 Authorization 標頭中包含您的 API 金鑰：

Authorization: Bearer omx_sk_YOUR_API_KEY

端點

方法	端點	說明
`POST`	`/chat/completions`	建立聊天補全
`POST`	`/completions`	建立文字補全（舊版）
`POST`	`/embeddings`	建立嵌入
`GET`	`/models`	列出可用模型
`GET`	`/models/:id`	取得模型資訊
`GET`	`/models/compare`	並排比較模型

請求格式

所有 POST 請求接受 JSON 主體，Content-Type: application/json。

回應格式

所有回應都回傳 JSON。成功回應直接包含資料。錯誤回應遵循以下格式：

{
  "error": {
    "message": "Human-readable error message",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

HTTP 狀態碼

代碼	說明
`200`	成功
`400`	錯誤的請求 — 請檢查您的參數
`401`	未授權 — 無效或缺少 API 金鑰
`403`	禁止 — 權限不足
`404`	未找到 — 無效的端點或模型
`429`	速率受限 — 請放慢速度或升級方案
`500`	伺服器錯誤 — 請使用退避策略重試
`502`	閘道器錯誤 — 上游供應商錯誤
`503`	服務不可用 — 暫時性中斷

OpenModex 回應中繼資料

每個回應都包含一個可選的 openmodex 欄位，帶有路由和效能中繼資料：

{
  "id": "chatcmpl-abc123",
  "choices": [...],
  "usage": {...},
  "openmodex": {
    "request_id": "req_abc123",
    "model_used": "gpt-4o-2024-08-06",
    "provider": "openai",
    "cache_hit": false,
    "routing_strategy": "cost_optimized",
    "fallback_used": false,
    "latency_ms": 1250
  }
}

冪等性

對於 POST 請求，您可以傳遞 Idempotency-Key 標頭以確保相同的請求不會被處理兩次：

curl https://api.openmodex.com/v1/chat/completions \
  -H "Authorization: Bearer omx_sk_..." \
  -H "Idempotency-Key: my-unique-key-123" \
  -H "Content-Type: application/json" \
  -d '...'

冪等金鑰的有效期為 24 小時。

​基底 URL

​身分驗證

​端點

​請求格式

​回應格式

​HTTP 狀態碼

​OpenModex 回應中繼資料

​冪等性