用戶端 SDK

    Gate AI 用戶端 SDK 提供輕量、型別安全的方式來存取 Gate AI 的模型、媒體、生成用量和餘額 API。SDK 的設計與 HTTP API 保持緊密對應：負責處理身分驗證、請求與回應型別、串流傳輸、multipart 上傳、重試和錯誤解析，同時由應用程式自行控制編排與狀態。

    可用 SDK

    語言套件環境需求安裝指令
    TypeScriptgate-ai-sdkNode.js 18+ 或現代瀏覽器npm add gate-ai-sdk
    Gogithub.com/gate/gate-ai-go-sdkGo 1.20+go get github.com/gate/gate-ai-go-sdk

    兩個 SDK 目前版本均為 0.1.0。TypeScript 套件僅支援 ESM。兩個 SDK 都沒有第三方執行階段依賴。

    何時使用用戶端 SDK

    當應用程式需要直接存取以下能力時，可以使用這些 SDK：

    • Chat Completions 和 Responses API
    • Anthropic Messages、Gemini 和 Vertex 相容 API
    • Embeddings
    • 圖像生成、編輯和結果查詢
    • 語音轉文字和文字轉語音
    • 非同步視訊生成與結果下載
    • 生成用量和餘額查詢
    • 串流 Server-Sent Events

    這些 SDK 是 API 用戶端，並非 Agent 框架。Agent 迴圈、工具分派、記憶、對話狀態和其他編排邏輯仍由應用程式負責。

    環境變數

    變數用途
    GATEAI_BASE_URLGate AI 根服務位址，不包含 /openai/v1 或其他 API 後綴
    GATEAI_API_KEY需要身分驗證的操作所使用的 API Key

    如果未明確提供 API Key 或安全憑證來源，兩個 SDK 都會自動讀取 GATEAI_API_KEY。

    TypeScript 快速開始

    安裝

    bash
    1npm add gate-ai-sdk

    也可以使用 pnpm、yarn 或 bun 安裝該套件。

    對話補全

    javascript
    1import { GateAI } from "gate-ai-sdk";23const client = new GateAI(process.env.GATEAI_BASE_URL!, {4  apiKey: process.env.GATEAI_API_KEY,5});67const response = await client.chat.send({8  model: "openai/gpt-5.2",9  messages: [10    { role: "user", content: "Explain embeddings in one sentence." },11  ],12});1314console.log(response.data.choices?.[0]?.message?.content);

    串流傳輸

    javascript
    1const stream = await client.chat.stream({2  model: "openai/gpt-5.2",3  messages: [{ role: "user", content: "Write a short haiku." }],4});56for await (const event of stream) {7  console.log(event.data.choices?.[0]?.delta);8}

    每個事件都包含解析後的 data、原始 raw JSON，以及選用的 SSE id、type 和 retry 中繼資料。如果在串流傳輸結束前停止讀取，請呼叫 await stream.close()。每個串流只能取用一次。

    用戶端設定

    javascript
    1const client = new GateAI(serverURL, {2  apiKey: process.env.GATEAI_API_KEY,3  securitySource: async (signal) => loadRotatingAPIKey(signal),4  headers: { "X-Gate-Request-Source": "my-service" },5  userAgent: "my-service/1.0.0",6  retry: {7    maxRetries: 2,8    initialBackoffMs: 250,9    maxBackoffMs: 5_000,10  },11});

    每次發起需要身分驗證的請求前都會執行 securitySource，且其優先順序高於 apiKey。測試或非標準執行環境也可以提供自訂 fetch 實作。

    Go 快速開始

    安裝

    bash
    1go get github.com/gate/gate-ai-go-sdk

    對話補全

    go
    1package main23import (4	"context"5	"fmt"6	"log"7	"os"89	gateai "github.com/gate/gate-ai-go-sdk"10	"github.com/gate/gate-ai-go-sdk/models/components"11)1213func main() {14	client, err := gateai.New(15		os.Getenv("GATEAI_BASE_URL"),16		gateai.WithAPIKey(os.Getenv("GATEAI_API_KEY")),17	)18	if err != nil {19		log.Fatal(err)20	}2122	response, err := client.Chat.Send(context.Background(), components.ChatRequest{23		Model: "openai/gpt-5.2",24		Messages: []components.ChatMessage{25			{Role: "user", Content: "Explain embeddings in one sentence."},26		},27	})28	if err != nil {29		log.Fatal(err)30	}3132	fmt.Println(response.Data.Choices[0].Message.Content)33}

    串流傳輸

    go
    1events, err := client.Chat.Stream(ctx, components.ChatRequest{2	Model: "openai/gpt-5.2",3	Messages: []components.ChatMessage{4		{Role: "user", Content: "Write a short haiku."},5	},6})7if err != nil {8	log.Fatal(err)9}10defer events.Close()1112for events.Next() {13	chunk := events.Value()14	fmt.Println(string(chunk.Choices[0].Delta))15}16if err := events.Err(); err != nil {17	log.Fatal(err)18}

    Value() 傳回解碼後的事件，Event() 傳回其 SSE 中繼資料。請一律關閉串流；取消 context 會關閉底層 HTTP 請求。

    用戶端設定

    go
    1client, err := gateai.New(2	serverURL,3	gateai.WithAPIKey(apiKey),4	gateai.WithDefaultHeader("X-Gate-Request-Source", "my-service"),5	gateai.WithUserAgent("my-service/1.0.0"),6	gateai.WithRetryConfig(gateai.RetryConfig{7		MaxRetries:     2,8		InitialBackoff: 250 * time.Millisecond,9		MaxBackoff:     5 * time.Second,10	}),11)

    使用 WithSecuritySource 提供輪替憑證，使用 WithHTTPClient 提供自訂 HTTP 傳輸或測試用戶端。

    API 資源

    能力TypeScriptGo端點
    對話補全chat.send, chat.streamChat.Send, Chat.StreamPOST /openai/v1/chat/completions
    Responses APIresponses.send, responses.streamResponses.Send, Responses.StreamPOST /openai/v1/responses
    Embeddingsembeddings.generateEmbeddings.GeneratePOST /openai/v1/embeddings
    Anthropic Messagesanthropic.messages.send, streamAnthropic.Messages.Send, StreamPOST /anthropic/v1/messages
    Geminigemini.generateContent, streamGenerateContentGemini.GenerateContent, StreamGenerateContentGemini 原生路徑
    Vertexvertex.generateContent, streamGenerateContentVertex.GenerateContent, StreamGenerateContentVertex 發布商路徑
    圖像生成images.generateImages.GeneratePOST /openai/v1/images/generations
    圖像編輯images.editImages.EditPOST /openai/v1/images/edits
    圖像查詢images.getImages.GetGET /api/v1/images/{image_id}
    語音轉文字stt.createTranscription, streamTranscriptionSTT.CreateTranscription, StreamTranscriptionPOST /openai/v1/audio/transcriptions
    文字轉語音tts.createSpeech, streamSpeechTTS.CreateSpeech, StreamSpeechPOST /openai/v1/audio/speech
    視訊生成videoGeneration.generateVideoGeneration.GeneratePOST /api/v1/videos
    視訊狀態videoGeneration.getGenerationVideoGeneration.GetGenerationGET /api/v1/videos/{job_id}
    視訊內容videoGeneration.getVideoContentVideoGeneration.GetVideoContentGET /api/v1/videos/{job_id}/content
    生成用量generations.getGenerations.GetGET /api/v1/generation
    餘額credits.getBalanceCredits.GetBalanceGET /api/v1/credits/balance

    兩個 SDK 都刻意不提供模型列表操作。

    回應處理

    TypeScript

    JSON 方法傳回 SDKResponse<T>，其中包含：

    • data ：解碼後的回應本文
    • raw ：原始回應文字
    • status 和 headers ：HTTP 中繼資料
    • response ：原生 Fetch Response

    二進位方法傳回 BinaryResponse，其中提供回應串流、內容類型、標頭、原生回應和 arrayBuffer()。當伺服器傳回 X-Gate-Generation-Id 時，文字轉語音回應會提供 generationId。

    Go

    JSON 方法傳回 *gateai.Response[T]，其中包含：

    • Data ：解碼後的回應本文
    • Raw ：原始回應位元組
    • StatusCode 和 Header ：HTTP 中繼資料
    • HTTPResponse ：原始 *http.Response

    二進位方法傳回 *gateai.BinaryResponse。呼叫端擁有 Body 並且必須將其關閉。當伺服器傳回對應資訊時，文字轉語音回應會提供 GenerationID。

    錯誤與重試

    TypeScript HTTP 請求失敗時會拋出 APIError；缺少憑證時會拋出 MissingAPIKeyError。Go HTTP 請求失敗時會傳回 *gateai.APIError；缺少憑證時傳回 gateai.ErrMissingAPIKey。

    API 錯誤會保留 HTTP 狀態、提供商錯誤類型、錯誤碼和訊息、請求 ID、追蹤 ID、原始回應本文以及原始 HTTP 回應。

    GET 操作會在發生暫時性網路故障，或收到 HTTP 408、429、500、502、503 和 504 回應時重試。POST 操作預設不會重試，因為它們可能產生費用。僅在可以安全重播請求時啟用 POST 重試，並建議搭配冪等鍵。Multipart 上傳永不重試。SDK 會遵循 Retry-After 和 retry-after-ms。

    向前相容的原始呼叫

    TypeScript 中面向提供商的資源提供 sendRaw、streamRaw、generateRaw 和 generateContentRaw 等原始呼叫變體，Go 中則提供相應的 PascalCase 方法。當提供商新增欄位而 SDK 型別尚未更新時，可以使用原始呼叫。

    當所需欄位已包含在 SDK 型別中時，優先使用型別化方法。

    詳細文件