> ## 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.

# Chat Completions

> OpenAI-compatible chat completions for OCR, VQA, and document inference

Authentication is optional for the VLM Run Gateway (at the moment). See
[Authentication](/gateway/authentication) for tiers and
[Rate Limits](/gateway/rate-limits) for per-tier quotas.

## Models Supported

For available models and aliases, see [Models](/gateway/models).

## Gateway extensions

These fields are accepted at the top level of the request body (or via
`extra_body` in the OpenAI Python SDK):

| Field                | Type      | Default       | Description                                                |
| -------------------- | --------- | ------------- | ---------------------------------------------------------- |
| `method`             | `string`  | model default | Model-specific operation (`ocr`, `detect`, `markdown`, …). |
| `method_params`      | `object`  | `null`        | Keyword arguments for the selected `method`.               |
| `llm`                | `string`  | `null`        | Optional LLM for post-processing structured model output.  |
| `document_dpi`       | `integer` | `150`         | DPI when rasterizing PDF pages.                            |
| `document_max_pages` | `integer` | `500`         | Maximum PDF pages per request.                             |
| `image_resolution`   | `string`  | `null`        | Square resize preset (`224x224` … `768x768`).              |

Each model exposes supported `method` values on
[`GET /v1/openai/models`](/gateway/api-reference/get-models). See
[Methods](/gateway/methods) for a per-model reference with examples.

## Content parts

Messages use the standard OpenAI multimodal shape. See
[Multimodal Inputs](/gateway/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:

| Field   | Description                                          |
| ------- | ---------------------------------------------------- |
| `usage` | Token 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](/gateway/guides/document-ocr#3-streaming-vs-non-streaming) for the full SSE walkthrough.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  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)
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  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.caption/sample.jpg"
              }
            }
          ]
        }
      ]
    }'
  ```
</CodeGroup>

### Document OCR

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  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)
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  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": 150,
      "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"
              }
            }
          ]
        }
      ]
    }'
  ```
</CodeGroup>

### Stream a document page-by-page

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  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="")
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  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",
      "stream": true,
      "method": "ocr",
      "document_dpi": 150,
      "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"
              }
            }
          ]
        }
      ]
    }'
  ```
</CodeGroup>

## Errors and limits

* [Error codes](/gateway/error-codes): capability violations, invalid
  documents, model not found, and sanitized 500 responses.
* [Rate limits](/gateway/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.

## Related

<CardGroup cols={2}>
  <Card title="List models" icon="table-list" href="/gateway/api-reference/get-models">
    Query the live model catalog and capabilities.
  </Card>

  <Card title="Models" icon="server" href="/gateway/models">
    Full catalog with availability and use-case guidance.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/gateway/quickstart">
    First requests for VQA and document OCR.
  </Card>

  <Card title="Flexible Document OCR" icon="file-lines" href="/gateway/guides/document-ocr">
    Request knobs, page blocks, and streaming for PDFs.
  </Card>

  <Card title="Multimodal Inputs" icon="images" href="/gateway/multimodal-inputs">
    Content part types, document limits, and format tradeoffs.
  </Card>
</CardGroup>


## OpenAPI

````yaml gateway/openapi.json POST /v1/openai/chat/completions
openapi: 3.1.0
info:
  title: VLM Run Gateway API
  summary: Unified gateway for real-time vision-language inference.
  description: |
    The **VLM Run Gateway API** is the public entry point to the VLM Run
    inference platform. It fronts vision-language and computer-vision models
    behind a single OpenAI-compatible surface plus first-class real-time
    transports.

    [Terms of service](https://vlm.run/terms) |
    [VLM Run](https://vlm.run) |
    [Send email to support@vlm.run](mailto:support@vlm.run)
  termsOfService: https://vlm.run/terms
  contact:
    name: VLM Run
    url: https://vlm.run/
    email: support@vlm.run
  version: 0.10.0
servers:
  - url: https://gateway.vlm.run
    description: Production
  - url: http://localhost:8001
    description: Local development
security: []
paths:
  /v1/openai/chat/completions:
    post:
      summary: Chat Completions
      operationId: chat_completions_v1_openai_chat_completions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example: {}
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    ChatCompletionRequest:
      properties:
        model:
          type: string
          title: Model
        messages:
          items:
            $ref: '#/components/schemas/ChatMessage'
          type: array
          title: Messages
        temperature:
          type: number
          title: Temperature
          default: 0.7
        max_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Tokens
        top_p:
          type: number
          title: Top P
          default: 1
        frequency_penalty:
          type: number
          title: Frequency Penalty
          default: 0
        presence_penalty:
          type: number
          title: Presence Penalty
          default: 0
        stop:
          anyOf:
            - type: string
            - items:
                type: string
              type: array
            - type: 'null'
          title: Stop
        stream:
          type: boolean
          title: Stream
          default: false
        'n':
          type: integer
          title: 'N'
          default: 1
        llm:
          anyOf:
            - type: string
            - type: 'null'
          title: Llm
        method:
          anyOf:
            - type: string
            - type: 'null'
          title: Method
        method_params:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Method Params
        video_max_frames:
          anyOf:
            - type: integer
            - type: 'null'
          title: Video Max Frames
        video_fps:
          anyOf:
            - type: number
            - type: 'null'
          title: Video Fps
        image_resolution:
          anyOf:
            - type: string
              enum:
                - 224x224
                - 336x336
                - 384x384
                - 448x448
                - 512x512
                - 768x768
            - type: 'null'
          title: Image Resolution
        video_resolution:
          anyOf:
            - type: string
              enum:
                - 256x192
                - 320x240
                - 448x336
                - 512x384
                - 640x480
            - type: 'null'
          title: Video Resolution
        document_dpi:
          anyOf:
            - type: integer
            - type: 'null'
          title: Document Dpi
        document_max_pages:
          anyOf:
            - type: integer
            - type: 'null'
          title: Document Max Pages
      type: object
      required:
        - model
        - messages
      title: ChatCompletionRequest
      description: OpenAI-compatible chat completion request.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ChatMessage:
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
          title: Role
        content:
          anyOf:
            - type: string
            - items:
                $ref: '#/components/schemas/ContentPart'
              type: array
          title: Content
      type: object
      required:
        - role
        - content
      title: ChatMessage
      description: A single message in the conversation.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ContentPart:
      properties:
        type:
          type: string
          enum:
            - text
            - image_url
            - video_url
            - document_url
            - file_url
          title: Type
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
        image_url:
          anyOf:
            - $ref: '#/components/schemas/ImageUrl'
            - type: 'null'
        video_url:
          anyOf:
            - $ref: '#/components/schemas/VideoUrl'
            - type: 'null'
        document_url:
          anyOf:
            - $ref: '#/components/schemas/DocumentUrl'
            - type: 'null'
        file_url:
          anyOf:
            - $ref: '#/components/schemas/FileUrl'
            - type: 'null'
      type: object
      required:
        - type
      title: ContentPart
      description: A single content part in a multi-modal message.
    ImageUrl:
      properties:
        url:
          type: string
          title: Url
        detail:
          type: string
          enum:
            - auto
            - low
            - high
          title: Detail
          default: auto
      type: object
      required:
        - url
      title: ImageUrl
    VideoUrl:
      properties:
        url:
          type: string
          title: Url
      type: object
      required:
        - url
      title: VideoUrl
    DocumentUrl:
      properties:
        url:
          type: string
          title: Url
      type: object
      required:
        - url
      title: DocumentUrl
      description: PDF document referenced by URL or base64 data URI.
    FileUrl:
      properties:
        url:
          type: string
          title: Url
      type: object
      required:
        - url
      title: FileUrl
      description: Alias for :class:`DocumentUrl` — accepted for PDF document inputs.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````