AI Gateway v1.0 · API Docs

AI Gateway API

一個統一入口，串接多家大型語言模型供應商。 換供應商只要改 provider 跟 model，你的程式碼完全不用改。

Base URL

https://ai2.0800945.com

三步開始

  1. 在 後台 API Keys 產生一把 sk_xxx
  2. 用 Authorization: Bearer sk_xxx 打 下面任一端點
  3. 回 JSON + token 用量 + latency

認證方式

所有 /api/* 端點（除了 /api/health）都需要 API Key。兩種 header 都吃：

# 推薦
curl https://ai2.0800945.com/api/providers \
  -H "Authorization: Bearer sk_你的KEY"

# 備援
curl https://ai2.0800945.com/api/providers \
  -H "X-Api-Key: sk_你的KEY"

Key 在後台 /admin/api-keys 產生，明文只顯示一次，DB 只存 SHA-256 hash。

錯誤碼

所有錯誤回傳 {ok: false, error: "code", message: "..."}：

HTTPerror code說明
400bad_requestBody 缺少必要欄位
401unauthorized缺少或無效的 API Key
404not_found端點 / provider 不存在
500internal_errorGateway 內部錯誤
502upstream_error上游 provider 回錯（附 upstream_http 跟 upstream_data）

所有端點

目前已串接 1 個供應商，共 5 個端點（從 DB 即時拉出，後台新增會自動同步）：

MethodPath供應商認證說明
GET /v1/models nvidia 需要 列出 NVIDIA 平台上所有可用的模型 id（含已釋出但未必 open weights 的預覽版）
POST /v1/chat/completions nvidia 需要 OpenAI 相容的 Chat Completions，可對話、串流、function calling，NVIDIA 把它當 NIM 對外介面
POST /v1/completions nvidia 需要 傳統 legacy completions（純文字接龍），新模型大多已轉 chat/completions
POST /v1/embeddings nvidia 需要 把文字轉成向量（依模型不同維度，常見 1024/2048/4096），可用於 RAG 檢索
GET /v1/health nvidia 公開 NVIDIA 內部健康檢查端點（部分模型有此路徑）

端點細節

POST /v1/chat/completions 🔒 需要 API Key

統一 Chat 入口。OpenAI 相容 body 格式，接受任意已啟用的 provider + model。支援 vision：messages 中某則 content 可改用 array 格式（text + image_url），需用 vision 模型。

Request

curl https://ai2.0800945.com/api/chat \
  -H "Authorization: Bearer sk_你的KEY" \
  -H "Content-Type: application/json" \
  -d '
  {
    "provider": "nvidia",
    "model": "meta/llama-3.1-70b-instruct",
    "messages": [
      {"role": "user", "content": "1+1=?"}
    ]
  }
'

Body 參數

欄位類型說明
provider* string Provider code（例：nvidia）
model* string Model id（從 /api/providers 拿；vision 用 meta/llama-3.2-11b-vision-instruct）
messages* array [{role, content}]，content 可以是 str 或 array（vision 多模組件）
temperatureopt number 0 ~ 2，預設 0.7
top_popt number 0 ~ 1，預設 1.0
max_tokensopt integer 回覆最大 token 數，預設 1024
stopopt string|array 停止字串

Body 範例（純文字）

{
  "provider": "nvidia",
  "model": "meta/llama-3.1-70b-instruct",
  "messages": [
    {"role": "system", "content": "你是一個繁體中文助理"},
    {"role": "user", "content": "幫我寫一首關於台北夜景的短詩"}
  ],
  "temperature": 0.7,
  "max_tokens": 512
}

Body 範例（Vision：圖文混合，限 vision 模型）

{
  "provider": "nvidia",
  "model": "meta/llama-3.2-11b-vision-instruct",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "用繁體中文描述這張圖，最多 50 字"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
      ]
    }
  ],
  "max_tokens": 256
}

image_url.url 支援兩種：
• 公開 URL："https://example.com/photo.jpg"
• Base64 內嵌："data:image/png;base64,iVBORw0KG..."（適合小圖，不佔上傳流量）

Response 200

{
  "ok": true,
  "data": {
    "provider": "nvidia",
    "model": "meta/llama-3.1-70b-instruct",
    "reply": "霓虹燈下淡水河...",
    "finish_reason": "stop",
    "usage": { "prompt_tokens": 59, "completion_tokens": 128, "total_tokens": 187 },
    "latency_ms": 1923,
    "raw": { ... 原始上游回應 ... }
  }
}
GET /v1/health 🌐 公開

健康檢查 + 目前所有 provider 狀態。公開端點，不需 API key。

Request

curl https://ai2.0800945.com/api/health

Response 200

{
  "ok": true,
  "service": "AI Gateway",
  "version": "1.0.0",
  "time": "2026-08-05 14:30:00",
  "providers": [
    { "code": "nvidia", "display_name": "NVIDIA NIM", "is_active": true }
  ]
}

已串接的供應商

NVIDIA NIM (integrate.api.nvidia.com) nvidia

https://integrate.api.nvidia.com
自動 seed；正式環境請至後台更新 API key
8 個模型
meta/llama-3.1-70b-instruct meta/llama-3.1-8b-instruct meta/llama-3.3-70b-instruct mistralai/mistral-large-2-instruct qwen/qwen2.5-72b-instruct google/gemma-2-27b-it nvidia/nv-embed-v1 meta/llama-3.2-11b-vision-instruct

線上測試

即時打 /api/chat

貼上你的 API Key，選 provider + model，送出後看回應。 Key 只存在你的瀏覽器（localStorage），不會送到任何第三方。

＋ 加 image_url（vision 模型才有用）
尚未送出