客户端 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 类型中时，优先使用类型化方法。

    详细文档