Quickstart

Point base_url at https://gateway.vlm.run/v1/openai in any OpenAI SDK and you can start making requests. This page covers setup and the two most common request shapes: visual Q&A and document OCR. See Introduction for the rationale behind the VLM Run Gateway.

Prerequisites

pip install openai

npm install openai

export VLMRUN_API_KEY="your-api-key"

Base URL: https://gateway.vlm.run/v1/openai. Use Authorization: Bearer <VLMRUN_API_KEY>, or omit the header for anonymous access. See Authentication and Rate Limits.

Visual Q&A

Send a question with an optional image. See Models for available models.

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.vlm.run/v1/openai",
    api_key="<VLMRUN_API_KEY>",
)

response = client.chat.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://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.generation/sf-golden-gate.jpg",
                    },
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

curl https://gateway.vlm.run/v1/openai/chat/completions \
  -X POST \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.generation/sf-golden-gate.jpg"
            }
          }
        ]
      }
    ]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.vlm.run/v1/openai",
  apiKey: process.env.VLMRUN_API_KEY,
});

const response = await client.chat.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://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.generation/sf-golden-gate.jpg",
          },
        },
      ],
    },
  ],
});

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

Video Q&A

Send a question with a hosted video URL. Tune frame sampling with video_fps and video_max_frames. See Video Inputs for all knobs.

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.vlm.run/v1/openai",
    api_key="<VLMRUN_API_KEY>",
)

response = client.chat.completions.create(
    model="qwen/qwen3.5-0.8b",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Summarize what happens in this video."},
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/video.transcription/bakery.mp4",
                    },
                },
            ],
        }
    ],
    extra_body={"video_fps": 1.0, "video_max_frames": 8},
)

print(response.choices[0].message.content)

curl https://gateway.vlm.run/v1/openai/chat/completions \
  -X POST \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3.5-0.8b",
    "video_fps": 1.0,
    "video_max_frames": 8,
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Summarize what happens in this video." },
          {
            "type": "video_url",
            "video_url": {
              "url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/video.transcription/bakery.mp4"
            }
          }
        ]
      }
    ]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.vlm.run/v1/openai",
  apiKey: process.env.VLMRUN_API_KEY,
});

const response = await client.chat.completions.create({
  model: "qwen/qwen3.5-0.8b",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Summarize what happens in this video." },
        {
          type: "video_url",
          video_url: {
            url: "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/video.transcription/bakery.mp4",
          },
        },
      ],
    },
  ],
  video_fps: 1.0,
  video_max_frames: 8,
});

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

Document and Image OCR

Pass a PDF as a document_url content part and select a per-page method. See Models and Flexible Document OCR for the full pipeline.

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.vlm.run/v1/openai",
    api_key="<VLMRUN_API_KEY>",
)

response = client.chat.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"
                    },
                }
            ],
        }
    ],
    extra_body={
        "method": "ocr",
        "document_dpi": 72,
    },
)

print(response.choices[0].message.content)

curl https://gateway.vlm.run/v1/openai/chat/completions \
  -X POST \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "paddleocr/pp-ocrv6",
    "method": "ocr",
    "document_dpi": 72,
    "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"
            }
          }
        ]
      }
    ]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.vlm.run/v1/openai",
  apiKey: process.env.VLMRUN_API_KEY,
});

const response = await client.chat.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: 72,
});

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

Next steps

Flexible Document OCR

Request knobs, page blocks, and streaming for PDFs.

Models

Catalog, capabilities, and model selection.

Authentication

Anonymous vs API key access and rate limits.

Chat Completions API

Full request parameters and response schema.

Overview

Guides

API Reference

Misc

Prerequisites

Visual Q&A

Video Q&A

Document and Image OCR

Next steps

Flexible Document OCR

Models

Authentication

Chat Completions API

​Prerequisites

​Visual Q&A

​Video Q&A

​Document and Image OCR

​Next steps

Flexible Document OCR

Models

Authentication

Chat Completions API

Prerequisites

Visual Q&A

Video Q&A

Document and Image OCR

Next steps