> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vlm.run/llms.txt
> Use this file to discover all available pages before exploring further.

# client.gateway

> OpenAI-compatible OCR / VLM model gateway with the VLM Run Node.js SDK

The `client.gateway` object provides access to the [VLM Run Gateway](/gateway/introduction),
an OpenAI-compatible surface for third-party OCR and vision-language models
(e.g. `zai-org/glm-ocr`, `paddleocr/pp-ocrv6`, `qwen/qwen3.5-0.8b`). It
authenticates with the same `VLMRUN_API_KEY` used everywhere else in the SDK.

Under the hood the gateway points the OpenAI SDK at
`https://gateway.vlm.run/v1/openai`, so `client.gateway.completions`,
`client.gateway.embeddings`, and `client.gateway.transcriptions` are the
standard OpenAI resource objects. You get the familiar chat-completions,
embeddings, and audio-transcription interfaces without configuring a base URL
yourself.

<Note>
  The gateway is a raw passthrough to the underlying models. Unlike
  [`client.agent`](/sdk-reference/node/components/agent) (which calls the Orion agent),
  most gateway models, especially OCR models, do **not** accept text-only
  input, so you generally need at least one `image_url`/`document_url` content part.
</Note>

## Installation

The gateway uses the OpenAI SDK, an optional peer dependency:

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
npm install vlmrun openai
```

## Chat Completions

Run an OCR / VLM model over a document or image. Pass PDFs as `document_url`
content parts and images as `image_url`; gateway-specific fields (such as
`method` and `document_dpi`) travel alongside the standard OpenAI fields.

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { VlmRun } from "vlmrun";

const client = new VlmRun({ apiKey: "<VLMRUN_API_KEY>" });

const response = await client.gateway.completions.create({
  model: "paddleocr/pp-ocrv6",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "document_url",
          document_url: {
            url: "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/finance.sec-filings/tsla-8k.pdf",
          },
        },
      ],
    },
  ],
  method: "ocr",
  document_dpi: 96,
});

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

### Visual Q\&A

Models that accept text input (e.g. `qwen/qwen3.5-0.8b`) can take a `text`
content part alongside an image:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
const response = await client.gateway.completions.create({
  model: "qwen/qwen3.5-0.8b",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "What is happening in this image?" },
        { type: "image_url", image_url: { url: "https://example.com/image.jpg" } },
      ],
    },
  ],
});

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

### Streaming

The gateway streams document (PDF) requests one SSE chunk per page:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
const stream = await client.gateway.completions.create({
  model: "zai-org/glm-ocr",
  messages: [
    {
      role: "user",
      content: [
        { type: "document_url", document_url: { url: "https://example.com/doc.pdf" } },
      ],
    },
  ],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

## Embeddings

Embed text, images, or video with a gateway embedding model
(e.g. `qwen/qwen3-vl-embedding-2b`).

<Note>
  Multimodal input nests content parts one level deeper than plain text: `input`
  is a list whose items are either a string or a *list* of content parts.
</Note>

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
const response = await client.gateway.embeddings.create({
  model: "qwen/qwen3-vl-embedding-2b",
  input: [[{ type: "image_url", image_url: { url: "data:image/jpeg;base64,..." } }]],
});

console.log(response.data[0].embedding.length);
```

## Transcriptions

Transcribe audio (or a video's audio track) with a gateway transcription model
(e.g. `nvidia/parakeet-tdt-0.6b-v3`):

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import fs from "fs";

const response = await client.gateway.transcriptions.create({
  model: "nvidia/parakeet-tdt-0.6b-v3",
  file: fs.createReadStream("clip.mp3"),
});

console.log(response.text);
```

## Listing Models

List the models available on the gateway. Each model carries extra metadata
(input/output pricing, modality support, supported methods) beyond the standard
OpenAI fields.

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
const models = await client.gateway.models();
models.forEach((model) => console.log(model.id));
```

## Health Check

Check whether the gateway is reachable and authenticated:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
if (await client.gateway.health()) {
  console.log("Gateway is healthy");
}
```

## Configuration

By default the gateway targets `https://gateway.vlm.run/v1`. Override it with
the `VLMRUN_GATEWAY_URL` environment variable:

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
export VLMRUN_GATEWAY_URL="https://gateway.vlm.run/v1"
```

Gateway calls (especially multi-page PDF OCR) routinely exceed the client's
120s default, so the gateway raises the floor to 600s. An explicit `timeout`
other than the default is used as-is.

## SDK Reference

| Attribute / Method              | Description                                                      |
| ------------------------------- | ---------------------------------------------------------------- |
| `client.gateway.completions`    | OpenAI-compatible chat completions interface                     |
| `client.gateway.embeddings`     | OpenAI-compatible embeddings interface                           |
| `client.gateway.transcriptions` | OpenAI-compatible audio transcriptions interface                 |
| `client.gateway.models()`       | List models available on the gateway                             |
| `client.gateway.health()`       | Resolves to `true` if the gateway is reachable and authenticated |
| `client.gateway.baseUrl`        | Gateway base URL (without trailing slash)                        |

See the [Gateway documentation](/gateway/introduction) for the full model
catalog, [methods](/gateway/methods), and
[multimodal input](/gateway/multimodal-inputs) reference, and the
[Python equivalent](/sdk-reference/components/gateway).