Skip to main content
POST
/
v1
/
openai
/
chat
/
completions
Chat Completions
import requests

url = "https://gateway.vlm.run/v1/openai/chat/completions"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}
Authentication is optional for the VLM Run Gateway (at the moment). See Authentication for tiers and Rate Limits for per-tier quotas.

​
Models Supported

For available models and aliases, see Models.

​
Gateway extensions

These fields are accepted at the top level of the request body (or via extra_body in the OpenAI Python SDK):
FieldTypeDefaultDescription
methodstringmodel defaultModel-specific operation (ocr, detect, markdown, …).
method_paramsobjectnullKeyword arguments for the selected method.
llmstringnullOptional LLM for post-processing structured model output.
document_dpiinteger150DPI when rasterizing PDF pages.
document_max_pagesinteger500Maximum PDF pages per request.
image_resolutionstringnullSquare resize preset (224x224 … 768x768).
Each model exposes supported method values on GET /v1/openai/models. See Methods for a per-model reference with examples.

​
Content parts

Messages use the standard OpenAI multimodal shape. See Multimodal Inputs for the full content part reference (text, image_url, document_url) and document-specific limits.

​
Response extensions

Non-streaming responses follow the OpenAI chat completion shape with one VLM Run Gateway extension:
FieldDescription
usageToken counts; may include usage.cost for metering.

​
Streaming

Set stream: true on document PDF requests (document_url). The VLM Run Gateway emits one SSE chunk per page block, in ascending page order, followed by a final chunk with aggregated usage. Image-only and text-only requests do not support streaming on the Gateway today. See Flexible Document OCR for the full SSE walkthrough. 
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.caption/sample.jpg"
                    },
                },
            ],
        }
    ],
)

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

​
Document OCR

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/document.markdown/goog-10-k-2024.pdf"
                    },
                }
            ],
        }
    ],
    extra_body={
        "method": "ocr",
        "document_dpi": 150,
    },
)

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

​
Stream a document page-by-page

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="paddleocr/pp-ocrv6",
    stream=True,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document_url",
                    "document_url": {
                        "url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/document.markdown/goog-10-k-2024.pdf",
                    },
                }
            ],
        }
    ],
    extra_body={
        "method": "ocr",
        "document_dpi": 150,
    },
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="")

​
Errors and limits

  • Error codes: capability violations, invalid documents, model not found, and sanitized 500 responses.
  • Rate limits: 60 requests/min and 1000 requests/hr per IP (anonymous) or per user (authenticated).
Every response includes an x-request-id header. You may send your own id on the request; otherwise the VLM Run Gateway mints one. Sanitized 500 responses also include the id as error.request_id in the JSON body.

List models

Query the live model catalog and capabilities.

Models

Full catalog with availability and use-case guidance.

Quickstart

First requests for VQA and document OCR.

Flexible Document OCR

Request knobs, page blocks, and streaming for PDFs.

Multimodal Inputs

Content part types, document limits, and format tradeoffs.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

OpenAI-compatible chat completion request.

​
model
string
required
​
messages
ChatMessage · object[]
required
​
temperature
number
default:0.7
​
max_tokens
integer | null
​
top_p
number
default:1
​
frequency_penalty
number
default:0
​
presence_penalty
number
default:0
​
stop
​
stream
boolean
default:false
​
n
integer
default:1
​
llm
string | null
​
method
string | null
​
method_params
Method Params · object | null
​
video_max_frames
integer | null
​
video_fps
number | null
​
image_resolution
enum<string> | null
Available options:
224x224,
336x336,
384x384,
448x448,
512x512,
768x768
​
video_resolution
enum<string> | null
Available options:
256x192,
320x240,
448x336,
512x384,
640x480
​
document_dpi
integer | null
​
document_max_pages
integer | null

Response

Successful Response