開發者指南

這是統一 AI API 閘道的呼叫說明。App 只要打下面幾個網址即可，不需要知道背後是哪家供應商，也不用帶任何供應商金鑰。

1. 基本資訊

Base URL…

認證方式Authorization: Bearer <你的 GATEWAY_API_KEY>

備用認證x-api-key: <你的 GATEWAY_API_KEY>

金鑰來源向閘道管理員索取；本頁不會顯示任何金鑰。

管理後台設定的「全域提示詞」會自動加在每個請求的最前面。你的 App 不需要處理，也無法關閉它。

本頁所有範例中的 YOUR_GATEWAY_DOMAIN 會自動換成目前網站網址。呼叫時請把「公開模型A」換成 /v1/models 回傳的名稱。

2. 列出可用模型

回傳的是管理員封裝過的「公開名稱」，不是底層供應商的真實模型名稱。

Shell

curl YOUR_GATEWAY_DOMAIN/v1/models \\
  -H "Authorization: Bearer YOUR_GATEWAY_KEY"

回應範例：

{"object":"list","data":[
  {"id":"公開模型A","object":"model","created":0,"owned_by":"gateway"},
  {"id":"公開模型B","object":"model","created":0,"owned_by":"gateway"}
]}

3. OpenAI 格式（推薦）

端點：POST /v1/chat/completions，請求與回應都是 OpenAI Chat Completions 格式。

cURL

curl YOUR_GATEWAY_DOMAIN/v1/chat/completions \\
  -H "Authorization: Bearer YOUR_GATEWAY_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"model":"公開模型A","messages":[{"role":"user","content":"你好"}]}'

Python（openai SDK）

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GATEWAY_KEY",       # 閘道金鑰，不是供應商金鑰
    base_url="YOUR_GATEWAY_DOMAIN/v1" # 注意：結尾不要再加 /chat/completions
)

resp = client.chat.completions.create(
    model="公開模型A",                 # 用 /v1/models 回傳的名稱
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

Node.js（openai SDK）

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GATEWAY_KEY",
  baseURL: "YOUR_GATEWAY_DOMAIN/v1",
});

const resp = await client.chat.completions.create({
  model: "公開模型A",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);

4. Anthropic 格式

端點：POST /v1/messages，請求與回應都是 Anthropic Messages 格式。

cURL

curl YOUR_GATEWAY_DOMAIN/v1/messages \\
  -H "x-api-key: YOUR_GATEWAY_KEY" \\
  -H "anthropic-version: 2023-06-01" \\
  -H "Content-Type: application/json" \\
  -d '{"model":"公開模型A","max_tokens":1024,"messages":[{"role":"user","content":"你好"}]}'

Python（anthropic SDK）

from anthropic import Anthropic

client = Anthropic(
    api_key="YOUR_GATEWAY_KEY",
    base_url="YOUR_GATEWAY_DOMAIN/v1",
)

msg = client.messages.create(
    model="公開模型A",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(msg.content[0].text)

Node.js（anthropic SDK）

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "YOUR_GATEWAY_KEY",
  baseURL: "YOUR_GATEWAY_DOMAIN/v1",
});

const msg = await client.messages.create({
  model: "公開模型A",
  max_tokens: 1024,
  messages: [{ role: "user", content: "你好" }],
});
console.log(msg.content[0].text);

5. 串流（Streaming）

兩種格式都支援串流：在請求 body 加 "stream": true，就會收到對應協議的 SSE 串流。串流裡出現的 model 欄位也一律是公開名稱。

OpenAI 格式 cURL

curl -N YOUR_GATEWAY_DOMAIN/v1/chat/completions \\
  -H "Authorization: Bearer YOUR_GATEWAY_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"model":"公開模型A","stream":true,"messages":[{"role":"user","content":"你好"}]}'

OpenAI 串流以 data: {...} 分行輸出，最後一行是 data: [DONE]。

Anthropic 格式 cURL

curl -N YOUR_GATEWAY_DOMAIN/v1/messages \\
  -H "x-api-key: YOUR_GATEWAY_KEY" \\
  -H "anthropic-version: 2023-06-01" \\
  -H "Content-Type: application/json" \\
  -d '{"model":"公開模型A","max_tokens":1024,"stream":true,"messages":[{"role":"user","content":"你好"}]}'

Anthropic 串流為 message_start、content_block_delta…等 SSE 事件。

6. 錯誤格式

閘道會把上游錯誤轉成統一格式，且不會包含任何 API key。

OpenAIHTTP 4xx / 5xx

{"error":{"message":"模型未被啟用：公開模型A","type":"invalid_request_error","code":"model_not_allowed"}}

AnthropicHTTP 4xx / 5xx

{"type":"error","error":{"type":"invalid_request_error","message":"模型未被啟用：公開模型A"}}

常見狀態：401 金鑰錯誤或沒帶、403 嚴格模式下模型未啟用、404 模型或路由不存在、429 上游限流、502 上游連線失敗。