DocsAPI ReferenceSDKsCookbookChangelog

For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://modelgates.ai/docs/_mcp/server.

Quickstart: Build a Chat App

Goal: Learn the fundamentals of ModelGates by building a TypeScript chat app that sends messages and streams responses through ModelGates.

Outcome: A working multi-turn conversation loop that can talk to any of the 600+ models available on the platform by changing a single string.

Want to get started faster? Copy this prompt into your coding agent.

Prerequisites

1. Create a project and install the SDK

Set up a new Node.js project and add the ModelGates client SDK. The SDK is ESM-only, so set the package type to module. Install tsx so you can run the TypeScript examples directly.

bash
mkdir modelgates-chat && cd modelgates-chatnpm init -ynpm pkg set type=modulenpm install @modelgates/sdknpm install --save-dev tsx

2. Send your first message

Create chat.ts with a client instance and a single chat completion request. The apiKey reads from the environment so you never hard-code credentials.

typescript
import { ModelGates } from '@modelgates/sdk'; const client = new ModelGates({  apiKey: process.env.MODELGATES_API_KEY,}); const completion = await client.chat.send({  chatRequest: {    model: 'google/gemini-3.1-flash-lite',    messages: [      { role: 'user', content: 'Say hello in one sentence.' },    ],  },}); console.log(completion.choices[0]?.message.content);console.log({  promptTokens: completion.usage?.promptTokens,  completionTokens: completion.usage?.completionTokens,});

Run it with your API key:

bash
MODELGATES_API_KEY=sk-mg-v1-... npx tsx chat.ts

You should see a single text response printed to the console. The SDK returns token usage in camelCase fields such as promptTokens and completionTokens. The completion.choices array follows the same shape as the Chat Completions response.

3. Stream the response

Streaming returns text as it is generated instead of waiting for the full response. Pass stream: true and iterate over the returned async iterable. Each chunk contains a delta with the new text fragment.

typescript
import { ModelGates } from '@modelgates/sdk'; const client = new ModelGates({  apiKey: process.env.MODELGATES_API_KEY,}); const stream = await client.chat.send({  chatRequest: {    model: 'google/gemini-3.1-flash-lite',    messages: [      { role: 'user', content: 'Explain how routers work in three sentences.' },    ],    stream: true,  },}); for await (const chunk of stream) {  const delta = chunk.choices[0]?.delta?.content;  if (delta) process.stdout.write(delta);}console.log();

Text now prints incrementally. See the Streaming reference for the full SSE event format.

4. Add multi-turn conversation

Multi-turn works by sending the full message history with each request. The model uses all previous messages as context. Append each user input and assistant response to a messages array before the next call.

typescript
import { ModelGates } from '@modelgates/sdk';import * as readline from 'node:readline'; const client = new ModelGates({  apiKey: process.env.MODELGATES_API_KEY,}); const messages: { role: 'user' | 'assistant'; content: string }[] = []; const rl = readline.createInterface({  input: process.stdin,  output: process.stdout,}); function ask(): void {  rl.question('You: ', async (input) => {    if (input.toLowerCase() === 'exit') {      rl.close();      return;    }     messages.push({ role: 'user', content: input });     const stream = await client.chat.send({      chatRequest: {        model: 'google/gemini-3.1-flash-lite',        messages,        stream: true,      },    });     let response = '';    process.stdout.write('Assistant: ');    for await (const chunk of stream) {      const delta = chunk.choices[0]?.delta?.content;      if (delta) {        process.stdout.write(delta);        response += delta;      }    }    console.log();     messages.push({ role: 'assistant', content: response });    ask();  });} ask();

Run the file and type messages. The model remembers prior turns because the full messages array is sent with each request. Type exit to quit.

5. Swap models

ModelGates gives you access to hundreds of models through one API. Change the model string to switch providers — no other code changes needed.

typescript
// Use OpenAI's latest chat modelmodel: 'openai/gpt-chat-latest', // Use Anthropic Claude Sonnet latestmodel: '~anthropic/claude-sonnet-latest', // Use a free modelmodel: 'modelgates/free',

Browse all available models at modelgates.ai/models or query the Models API programmatically.

Check your work

  • npx tsx chat.ts prints a streamed response to the console
  • A multi-turn conversation maintains context across turns (ask a follow-up that references a previous answer)
  • Changing the model string switches to a different provider with no other code changes
  • The non-streaming response includes a usage object with promptTokens and completionTokens

Next steps

  • Connect a coding agent to ModelGates
  • Explore the Agent SDK for built-in multi-turn loops and tool execution