---
title: "Chat Completions"
method: POST
path: "/v1/openai/chat/completions"
tags: ["chat"]
---

# Chat Completions

`POST /v1/openai/chat/completions`

## Request

- Base URL: `https://api.vlm.run` (the document declares no server; this is the origin it was published from)
- URL: `https://api.vlm.run/v1/openai/chat/completions`
- Auth: HTTP bearer

Handle chat completion requests.

Supports both authenticated and public (unauthenticated) requests.
Guest users are limited to the playground UI path at $0.50/day per IP and
browser fingerprint. Authenticated free users are not subject to a daily
chat cap after they sign in.

## Headers

- `user-agent` string, nullable

## Request body

- AgentChatCompletionsRequest: Request payload for the OpenAI chat completions API for VLM Run agents.
  - `id` string: ID of the completion
  - `model` union: VLM Run Agent model to use for completion. When omitted, the skill's vlmrun.yaml model is used; otherwise the agent default.
    - 'vlmrun-orion-1' | 'vlmrun-orion-1:auto' | 'vlmrun-orion-1:fast' | 'vlmrun-orion-1:pro' | 'vlmrun-orion-2' | 'vlmrun-orion-2:auto'
    - string
  - `messages` Message[], required: Messages to complete
    - `role` 'user' | 'assistant' | 'system' | 'developer' | 'tool'
    - `content` union
      - string
      - MessageContent[]
        - `type` 'text' | 'image_url' | 'video_url' | 'audio_url' | 'file_url' | 'input_file', required
        - `text` string, nullable
        - `image_url` union
          - MessageContentImageUrl
            - `url` string, required
            - `detail` 'auto' | 'low' | 'high'
          - string
        - `video_url` MessageContentVideoUrl
          - `url` string, required
        - `audio_url` MessageContentAudioUrl
          - `url` string, required
        - `file_url` MessageContentFileUrl
          - `url` string, required
        - `file_id` string, nullable
    - `name` string, nullable
    - `tool_call_id` string, nullable
    - `tool_calls` ChatCompletionMessageFunctionToolCallParam[], nullable
      - `id` string, required
      - `function` Function, required: The function that the model called.
        - `arguments` string, required
        - `name` string, required
      - `type` 'function', required
  - `max_tokens` integer: Maximum number of tokens to generate
  - `n` integer, nullable: Number of completions to generate
  - `temperature` number: Temperature of the sampling distribution
  - `top_p` number: Cumulative probability of parameter highest probability vocabulary tokens to keep for nucleus sampling
  - `top_k` integer, nullable: Number of highest probability vocabulary tokens to keep for top-k-filtering
  - `logprobs` integer, nullable: Include the log probabilities on the logprobs most likely tokens, as well the chosen tokens
  - `stream` boolean: Whether to stream the response or not
  - `tools` object[], nullable: OpenAI-compatible client tool definitions. By default (``tool_execution=client``) the endpoint returns model ``tool_calls`` for the client to execute (OpenRouter / OpenAI / pydantic-ai protocol). Set ``tool_execution=hybrid`` to also enable server-side tools such as ``execute_code``.
  - `tool_choice` union: OpenAI-compatible tool_choice (``none`` / ``auto`` / ``required`` / specific function). Only used when ``tools`` is set.
    - string
    - object
  - `tool_execution` 'client' | 'hybrid', nullable: How tools are executed when ``tools`` is set. ``client`` (default): passthrough — all tool_calls returned to the caller. ``hybrid``: server tools (see ``server_tools``) run in-process; only client tool_calls are returned with ``finish_reason=tool_calls``.
  - `server_tools` string[], nullable: Server-owned tool names to inject and execute when ``tool_execution=hybrid``. Defaults to ``["execute_code"]``. Unknown names are rejected.
  - `expose_server_tool_calls` boolean: When True on the native (no client ``tools``) path, stream OpenAI-compatible ``delta.tool_calls`` for server-side tool invocations. Default False keeps the opaque server harness loop (text / preview / think markers only). External agent harnesses that need visible tool_calls should prefer ``tool_execution=hybrid`` instead.
  - `preview` union: Preview card selection for the agent. Accepts: ``True`` to enable all known card types, a ``list[str]`` of card discriminator names (e.g. ``["preview.image", "preview.grid"]``) for a focused set, or ``False``/``None`` to disable structured preview output. When enabled, the agent streams ``<preview data='{...json...}'/>`` lines through ``vlmrun.log.print(...)`` for the chosen card types.
    - boolean
    - string[]
  - `response_format` union: Format of the response
    - JSONSchemaResponseFormat: Response format for JSON schema mode as per Fireworks AI specification.
      - `type` 'json_schema'
      - `schema` object, required: JSON schema definition
    - JSONModeResponseFormat: Response format for JSON object mode as per Fireworks AI specification.
      - `type` 'json_object'
    - JSONSchemaResponseFormatStrict: Response format for JSON schema mode as per Fireworks AI specification.
      - `type` 'json_schema'
      - `json_schema` object, required: JSON schema definition
      - `name` string, required: The name of the JSON schema
      - `strict` boolean: Whether to use strict mode for the JSON schema
  - `service_tier` 'auto' | 'default' | 'standard' | 'flex' | 'priority', nullable: Delivery tier for the request. 'standard'/'default' uses baseline rates, 'flex' applies a 50% discount with higher latency, and 'priority' applies a 1.8x premium for highest reliability. When omitted (or 'auto'), the server default ('standard') applies — opt into 'flex'/'priority' explicitly.
  - `session_id` string: Session UUID for persisting the chat history
  - `session_token` string, nullable: Client-minted session token for IDOR protection (base64url, >=256-bit)
  - `metadata` object, nullable: Additional metadata for the request (e.g., dataset_name, experiment_id, etc.)
  - `skills` AgentSkill[], nullable: List of agent skills to enable for this request.
    - `type` string: The type of the skill. Use 'skill_reference' for DB-stored skills referenced by id/name. Use 'inline' to provide the skill as a base64-encoded zip bundle.
    - `skill_id` string, nullable: The unique identifier of the skill — a UUID or a name string (e.g., 'pillow', 'batch-processing').
    - `skill_name` string, nullable: Human-readable skill name for lookup (e.g., 'invoice-extraction'). Alternative to skill_id. Deprecated in favour of skill_id.
    - `skill_version` union: The version of the skill — an integer (e.g. 2) or 'latest'.
      - integer
      - string
    - `version` union: DEPRECATED: Use 'skill_version' instead. The version of the skill.
      - integer
      - string
    - `name` string, nullable: Human-readable name for the inline skill (used for discovery and logging).
    - `description` string, nullable: Short description of what the inline skill does.
    - `source` InlineSkillSource: Source payload for an inline skill bundle. Follows the OpenAI inline skill format:: { "type": "base64", "media_type": "application/zip", "data": "<base64-encoded-zip>" }
      - `type` 'base64': Encoding type for the inline skill data. Currently only 'base64' is supported.
      - `media_type` string: MIME type of the skill bundle. Must be 'application/zip'.
      - `data` string, required: Base64-encoded zip bundle containing the skill files.
    - `bundle` string, nullable: DEPRECATED: Use 'source.data' instead. Base64-encoded zip bundle containing the skill files (inline skills only).

## Response `201`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/vlm/apis/vlm-run-unified-server.md) · [All operations](https://skmtc.dev/vlm/apis/vlm-run-unified-server/llms.txt) · [OpenAPI document](https://skmtc.dev/vlm/apis/vlm-run-unified-server/revisions/4a68ab36546b?raw)