API 參考

go-llm-router 匯出的介面、設定型別、回應結構與輔助函式。

`core.Agent`

type Agent interface {
    Name() string
    Send(
        ctx context.Context,
        messages []Message,
        toolDefs []Tool,
        reasoning Reasoning,
        mode Mode,
    ) (*Output, int, error)
}

方法	說明
`Name`	回傳目前的模型名稱
`Send`	送出訊息與可選工具，回傳 `*Output`、HTTP status code 與 error

`core.StreamAgent`

type StreamAgent interface {
    SendStream(
        ctx context.Context,
        messages []Message,
        toolDefs []Tool,
        reasoning Reasoning,
        mode Mode,
    ) (<-chan StreamEvent, error)
}

由 core/claude 與 core/copilot 實作，以型別斷言取用。

type StreamEvent struct {
    Type           StreamEventType
    TextDelta      string
    ReasoningDelta string
    ToolCall       *ToolCallDelta
    Usage          *Usage
    FinishReason   string
    Err            error
}

`StreamEventType`	有效欄位
`StreamEventText`	`TextDelta`
`StreamEventReasoning`	`ReasoningDelta`
`StreamEventToolCall`	`ToolCall`（`Index`、`ID`、`Name`、`Arguments`）
`StreamEventUsage`	`Usage`
`StreamEventDone`	`FinishReason`
`StreamEventError`	`Err`

`router.New`

func New(config Config) (core.Agent, error)

解析 config.Name，選出對應工廠並回傳統一的 Agent。未知的 provider 鍵值回傳錯誤。

`router.Config`

欄位	用途
`Name`	`<provider>@<model>` 路由鍵
`APIKey`	API key 供應商
`Token`	OAuth token（`CopilotToken` / `CodexToken` / `*GrokToken`）
`BaseURL`	僅 `compat`
`AccountID` / `GatewayID`	僅 `cloudflare`

供應商鍵值

鍵值	憑證／特殊欄位	套件
`claude`	`APIKey`	`core/claude`
`openai`	`APIKey`	`core/openai`
`gemini`	`APIKey`	`core/gemini`
`grok`	`APIKey`	`core/grok`
`deepseek`	`APIKey`	`core/deepseek`
`nvidia`	`APIKey`	`core/nvidia`
`openrouter`	`APIKey`	`core/openRouter`
`cloudflare`	`APIKey`、`AccountID`、`GatewayID`	`core/cloudflare`
`compat`	`APIKey`、`BaseURL`	`core/compat`
`copilot`	`Token`	`core/copilot`
`codex`	`Token`	`core/openaiCodex`
`grok-oauth`	`Token`	`core/grokOauth`

`core.Config`

欄位	用途
`Model`	去除 provider 前綴後的模型名稱
`APIKey`	供應商 API key
`Token`	供應商專屬的 OAuth token 物件
`BaseURL`	自訂 endpoint base URL
`AccountID` / `GatewayID`	Cloudflare 專用欄位
`Thinking` / `Efforts` / `Endpoints`	由模型清單帶入的能力提示

推理

type Reasoning int

const (
    ReasoningNone Reasoning = iota
    ReasoningLow
    ReasoningMedium
    ReasoningHigh
    ReasoningXHigh
    ReasoningMax
)

const ReasoningDefault = ReasoningMedium

函式／型別	說明
`Reasoning.String()`	回傳字面值；超出範圍回傳 `invalid`
`ParseReasoning(s)`	解析字面值與別名 `minimal`／`extra`／`ultra`，回傳 `(Reasoning, bool)`
`ClampReasoning(r, lo, hi, provider, model)`	夾到區間並在被夾時記錄 debug 日誌
`ReasoningAgent`	供應商公開 `ReasoningLimits() (min, max Reasoning)` 的介面
`OpenAIEffortRange(model)`	回傳 OpenAI 系列模型的推理上下限

執行模式

type Mode int

const (
    ModeDefault Mode = iota
    ModeFast
)

函式	說明
`Mode.String()`	回傳 `default` 或 `fast`
`ParseMode(s)`	解析 `default` 與 `fast`，回傳 `(Mode, bool)`
`SupportFast(provider, model)`	該組合是否有加速層；適配器據此決定是否加上原生欄位
`WarnFastDowngrade(provider, model, tier)`	回報層級非 fast／priority 時記錄警告；空字串視為未回報，不警告

能力輔助函式

函式	說明
`SupportTemperature(provider, model)`	該模型是否接受 temperature
`ResponsesAPI(provider, model)`	是否走 OpenAI Responses API 路徑
`IsTextModel(id)`	是否為純文字模型
`NewHTTPClient()`	建立逾時十分鐘的共用 HTTP client

訊息與工具型別

型別	主要欄位
`Message`	`Role`、`Content`、`ReasoningContent`、`ToolCalls`、`ToolCallID`
`ContentPart`	多模態片段：`text` 或 `image_url`
`ImageURL`	`URL`、可選 `Detail`
`Tool`	OpenAI 風格的 function calling 外層
`ToolFunction`	`Name`、`Description`、JSON Schema `Parameters`
`ToolCall`	模型回傳的呼叫，含 `ID`、`Type`、function payload 與 Gemini 的 `ThoughtSignature`

type Message struct {
    Role             string
    Content          any
    ReasoningContent string
    ToolCalls        []ToolCall
    ToolCallID       string
}

type Tool struct {
    Type     string
    Function ToolFunction
}

type ToolFunction struct {
    Name        string
    Description string
    Parameters  json.RawMessage
}

回應型別

型別	說明
`Output`	正規化回應，含 `Choices`、`Usage`、`ServiceTier` 與可選 `Error`
`OutputChoices`	含 `Message`、串流 `Delta` 與 `FinishReason`
`Usage`	正規化計數：`Input`、`Output`、`CacheCreate`、`CacheRead`

Output.ServiceTier 帶回供應商回報的服務層級（例如 default、priority），是判斷加速層是否生效的唯一可信來源。

Usage.UnmarshalJSON 吸收各家 token 欄位命名：

input_tokens / output_tokens
prompt_tokens / completion_tokens
cache_creation_input_tokens
cache_read_input_tokens 與 prompt_tokens_details.cached_tokens

正規化後：

欄位	意義
`Input`	非快取的 input token
`Output`	產生的 output token
`CacheCreate`	寫入 prompt cache 的 token
`CacheRead`	由 cache 讀取的 input token

模型清單

func Models(ctx context.Context, config core.Config, filter core.ModelFilter) ([]string, error)
func ModelInfos(ctx context.Context, config core.Config, filter core.ModelFilter) ([]core.ModelInfo, error)

Models 存在於 claude、openai、gemini、grok、grokOauth、deepseek、nvidia、openRouter、cloudflare、copilot、openaiCodex。ModelInfos 由 copilot 與 gemini 提供。

型別	欄位
`ModelFilter`	`TextOnly` —— 以 `IsTextModel` 濾除非文字模型
`ModelInfo`	`ID`、`Thinking`、`Efforts`、`Endpoints`

OAuth token 型別

型別	說明
`CopilotToken`	access token、token type、scope 與到期時間
`CodexToken`	access／refresh／ID token、account ID 與到期時間；提供 `Expired()`
`GrokToken`	access／refresh token 與到期時間；提供 `Expired()`

套件	用途
`core/oauth/copilot`	GitHub device flow、keychain 載入與清除、session 刷新
`core/oauth/codex`	Codex OAuth 登入、載入、刷新
`core/oauth/grok`	Grok OAuth 登入、載入、刷新

Codex 影像生成

core/openaiCodex 的 Agent 額外提供：

func (a *Agent) GenerateImage(
    ctx context.Context,
    prompt string,
    opts ImageOptions,
) (base64Image string, revisedPrompt string, err error)

`ImageOptions` 欄位	用途
`Size`	輸出尺寸，例如 `1024x1024`
`Quality`	輸出品質，例如 `high`
`RefImageB64`	可選的 base64 參考影像
`RefMime`	參考影像的 MIME type

套件結構

套件	說明
`core`	共用型別、Agent 合約、推理與加速層政策
`core/router`	以字串鍵值建立 Agent 的工廠
`core/claude` … `core/compat`	各供應商實作
`core/oauth/*`	OAuth 登入、載入、刷新與清除流程
`cmd/test`	OpenAI 相容的本機測試伺服器