Gate AI TypeScript SDK

A lightweight, type-safe client for calling Gate AI model and media APIs from TypeScript and JavaScript. The SDK stays close to the HTTP API: it handles authentication, typed request and response envelopes, streaming, multipart uploads, retries, and error decoding while your application owns orchestration and conversation state.

Documentation: https://gate.ai/docs

Languages: English | 简体中文

When to Use This SDK

Use the client when your application needs direct access to:

• Chat Completions and Responses APIs
• Anthropic Messages, Gemini, and Vertex-compatible APIs
• Embeddings and image generation or editing
• Speech-to-text and text-to-speech, including streaming
• Asynchronous video generation and result download
• Generation usage and credit balance queries

This is an API client, not an agent framework. Agent loops, tool dispatch, memory, and application state remain in your code.

Requirements

• Node.js 18 or newer, or a modern browser with Fetch, FormData, Blob, and Web Streams
• A Gate AI base URL
• A Gate AI API key for authenticated operations

The package is ESM-only and has no runtime dependencies.

Installation

npm add gate-ai

The package can also be installed with pnpm add gate-ai, yarn add gate-ai, or bun add gate-ai.

Quickstart

Set the base URL to the Gate AI root URL. Do not append an API suffix such as /openai/v1. Custom reverse-proxy path prefixes are preserved, so a base URL such as https://proxy.example.com/gateai routes requests under /gateai.

import { DEFAULT_BASE_URL, GateAI } from "gate-ai";

const client = new GateAI(process.env.GATEAI_BASE_URL ?? DEFAULT_BASE_URL, {
  apiKey: process.env.GATEAI_API_KEY,
});

const response = await client.chat.send({
  model: "openai/gpt-5.2",
  messages: [
    { role: "user", content: "Explain embeddings in one sentence." },
  ],
});

console.log(response.data.choices?.[0]?.message?.content);

In Node.js, the client reads GATEAI_API_KEY automatically when neither apiKey nor securitySource is supplied.

Streaming

Streaming operations return an async iterable of parsed Server-Sent Events.

const stream = await client.chat.stream({
  model: "openai/gpt-5.2",
  messages: [{ role: "user", content: "Write a short haiku." }],
});

for await (const event of stream) {
  console.log(event.data.choices?.[0]?.delta);
}

Each event includes parsed data, the original raw JSON, and any SSE id, type, or retry metadata. Call await stream.close() when abandoning a stream before it is exhausted. A stream can be consumed only once.

API Reference

The client exposes resources grouped by API domain:

| Resource | Main operations | | --- | --- | | chat | Chat completions and streaming | | responses | Responses API calls and streaming | | embeddings | Vector embeddings | | anthropic.messages | Anthropic-compatible messages | | gemini, vertex | Gemini-compatible content generation | | images | Image generation and editing | | stt, tts | Speech transcription and synthesis | | videoGeneration | Submit, inspect, and download video jobs | | generations | Query persisted generation usage | | credits | Query the current credit balance |

See the TypeScript API Reference for method signatures, endpoints, response types, raw-call variants, and request options.

The model-list operation is intentionally not exposed by this SDK.

Client Configuration

const client = new GateAI(DEFAULT_BASE_URL, {
  apiKey: process.env.GATEAI_API_KEY,
  securitySource: async (signal) => loadRotatingAPIKey(signal),
  headers: { "X-Gate-Request-Source": "my-service" },
  userAgent: "my-service/1.0.0",
  retry: {
    maxRetries: 2,
    initialBackoffMs: 250,
    maxBackoffMs: 5_000,
  },
});

DEFAULT_BASE_URL is the production API root, https://api.gate.ai. Pass a different absolute HTTP or HTTPS URL to use a proxy, test environment, or other deployment.

securitySource is evaluated before every authenticated request and takes precedence over apiKey. A custom fetch implementation can also be supplied for testing or non-standard runtimes.

Responses and Errors

JSON operations return SDKResponse<T>, which contains:

• data: the decoded response body
• raw: the original response text
• status and headers: HTTP response metadata
• response: the native Fetch Response

Binary operations return BinaryResponse, exposing the response stream, content type, headers, and an arrayBuffer() convenience method. Text-to-speech responses also expose generationId when the server returns X-Gate-Generation-Id.

Non-success responses throw APIError. It exposes the HTTP status, provider error type, code and message, request ID, trace ID, raw body, and native Response. Missing credentials fail before a request is sent with MissingAPIKeyError.

GET requests retry transient network failures and HTTP 408, 429, 500, 502, 503, and 504 responses. POST requests do not retry by default because they may be billed. Set maxRetries or provide an idempotencyKey only when replay is safe. Multipart uploads are never retried. Retry-After and retry-after-ms are respected; when both are present, retry-after-ms takes precedence.

Examples

• Chat completion
• Credit balance

Development

npm ci
npm run typecheck
npm test
npm pack --dry-run

The canonical HTTP contract is maintained in the Gate AI documentation.