Embeddings

from openai import OpenAI

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

response = client.embeddings.create(
    model="qwen/qwen3-vl-embedding-2b",
    input="Extract a vector representation for this text.",
)

print(len(response.data[0].embedding))

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.embeddings.create({
  model: "qwen/qwen3-vl-embedding-2b",
  input: "Extract a vector representation for this text.",
});

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

vlmrun gw embed -t "Extract a vector representation for this text." \
  -m qwen/qwen3-vl-embedding-2b

curl https://gateway.vlm.run/v1/openai/embeddings \
  -X POST \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-vl-embedding-2b",
    "input": "Extract a vector representation for this text."
  }'

{
  "id": "embd-d4d2e8733ab043c891ad12f1546e2ef",
  "object": "list",
  "created": 1791250885,
  "model": "qwen/qwen3-vl-embedding-2b:text",
  "served_model_id": "qwen/qwen3-vl-embedding-2b",
  "backend": "vllm",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.009216280654072762, -0.03020104207098484, 0.023253384977579117, /* ... 2048 values in total */]
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9,
    "cost": 0.0
  }
}

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "input"],
      "msg": "Field required",
      "input": {
        "model": "qwen/qwen3-vl-embedding-2b"
      }
    }
  ]
}

POST

openai

embeddings

from openai import OpenAI

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

response = client.embeddings.create(
    model="qwen/qwen3-vl-embedding-2b",
    input="Extract a vector representation for this text.",
)

print(len(response.data[0].embedding))

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.embeddings.create({
  model: "qwen/qwen3-vl-embedding-2b",
  input: "Extract a vector representation for this text.",
});

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

vlmrun gw embed -t "Extract a vector representation for this text." \
  -m qwen/qwen3-vl-embedding-2b

curl https://gateway.vlm.run/v1/openai/embeddings \
  -X POST \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-vl-embedding-2b",
    "input": "Extract a vector representation for this text."
  }'

{
  "id": "embd-d4d2e8733ab043c891ad12f1546e2ef",
  "object": "list",
  "created": 1791250885,
  "model": "qwen/qwen3-vl-embedding-2b:text",
  "served_model_id": "qwen/qwen3-vl-embedding-2b",
  "backend": "vllm",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.009216280654072762, -0.03020104207098484, 0.023253384977579117, /* ... 2048 values in total */]
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9,
    "cost": 0.0
  }
}

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "input"],
      "msg": "Field required",
      "input": {
        "model": "qwen/qwen3-vl-embedding-2b"
      }
    }
  ]
}

Omit the Authorization header for anonymous access. Per-tier quotas are on Rate Limits. This route shares those quotas with chat completions. Model ids are on Models.

Request parameters

Field	Type	Default	Description
`model`	`string`	required	Embedding model id, e.g. `qwen/qwen3-vl-embedding-2b` or `google/embeddinggemma-2`.
`input`	`string`, array of strings, or array of content parts	required	Text, or `text` / `image_url` / `video_url` / `audio_url` / `document_url` content parts. See below.
`encoding_format`	`string`	`float`	`float` or `base64`.
`dimensions`	`integer`	model default	Truncate the output vector to fewer dimensions, if the model supports it.
`prompt_name`	`string`	model default	Task prefix for text, on models trained with one. See Task prefixes and dimensions.
`document_pages`	array	all	Pages of a `document_url` part to read: indices, or `[start, stop]` ranges.
`document_max_pages`	`integer`	model cap	Pages one document may add to an input.
`truncate_prompt_tokens`	`integer`	`null`	Truncate long inputs to this many tokens instead of erroring.
`user`	`string`	`null`	Opaque end-user identifier, accepted for OpenAI SDK compatibility.

Each model lists the extra fields it reads in supported_parameters on GET /v1/openai/models.

Text input

from openai import OpenAI

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

response = client.embeddings.create(
    model="qwen/qwen3-vl-embedding-2b",
    input="Extract a vector representation for this text.",
)

print(len(response.data[0].embedding))

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.embeddings.create({
  model: "qwen/qwen3-vl-embedding-2b",
  input: "Extract a vector representation for this text.",
});

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

vlmrun gw embed -t "Extract a vector representation for this text." \
  -m qwen/qwen3-vl-embedding-2b

curl https://gateway.vlm.run/v1/openai/embeddings \
  -X POST \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-vl-embedding-2b",
    "input": "Extract a vector representation for this text."
  }'

{
  "id": "embd-d4d2e8733ab043c891ad12f1546e2ef",
  "object": "list",
  "created": 1791250885,
  "model": "qwen/qwen3-vl-embedding-2b:text",
  "served_model_id": "qwen/qwen3-vl-embedding-2b",
  "backend": "vllm",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.009216280654072762, -0.03020104207098484, 0.023253384977579117, /* ... 2048 values in total */]
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9,
    "cost": 0.0
  }
}

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "input"],
      "msg": "Field required",
      "input": {
        "model": "qwen/qwen3-vl-embedding-2b"
      }
    }
  ]
}

Multimodal input

Vision-language models such as qwen/qwen3-vl-embedding-2b accept image_url and video_url content parts in input. video_url embeds sampled frames. Image and video vectors share the text vector space. google/embeddinggemma-2 also accepts audio_url, input_audio, and document_url parts. A PDF’s pages pool into one vector. All parts in one input share one 8,192-token window. Check capabilities.supported_input_types on GET /v1/openai/models before using a modality. Not every embedding model accepts images or video.

from openai import OpenAI

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

response = client.embeddings.create(
    model="qwen/qwen3-vl-embedding-2b",
    input=[
        {
            "type": "image_url",
            "image_url": {
                "url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.caption/car.jpg"
            },
        }
    ],
)

print(len(response.data[0].embedding))

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.embeddings.create({
  model: "qwen/qwen3-vl-embedding-2b",
  input: [
    {
      type: "image_url",
      image_url: {
        url: "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.caption/car.jpg",
      },
    },
  ],
});

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

vlmrun gw embed car.jpg -m qwen/qwen3-vl-embedding-2b

curl https://gateway.vlm.run/v1/openai/embeddings \
  -X POST \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-vl-embedding-2b",
    "input": [
      {
        "type": "image_url",
        "image_url": {
          "url": "https://storage.googleapis.com/vlm-data-public-prod/hub/examples/image.caption/car.jpg"
        }
      }
    ]
  }'

Task prefixes and dimensions

google/embeddinggemma-2 is trained with a short prefix on text inputs. Set it with prompt_name. The default is Classification. A wrong prefix still returns a vector, at lower precision. An unknown name is a 400.

`prompt_name`	Task	Pair with
`SearchQuery`	Web and document search	`Document`
`QuestionAnswering`	Question answering	`Document`
`FactChecking`	Fact checking	`Document`
`CodeRetrieval`	Code search	`Document`
`Classification`	Text classification	itself
`Clustering`	Clustering	itself
`SentenceSimilarity`	Semantic similarity	itself

dimensions takes 768, 512, 256, or 128. The shorter vector is re-normalized. Queries and documents must share one value.

from openai import OpenAI

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

response = client.embeddings.create(
    model="google/embeddinggemma-2",
    input="What causes the northern lights?",
    dimensions=256,
    extra_body={"prompt_name": "SearchQuery"},
)

print(len(response.data[0].embedding))

curl https://gateway.vlm.run/v1/openai/embeddings \
  -X POST \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/embeddinggemma-2",
    "input": "What causes the northern lights?",
    "dimensions": 256,
    "prompt_name": "SearchQuery"
  }'

200

{
  "object": "list",
  "model": "google/embeddinggemma-2:text",
  "served_model_id": "google/embeddinggemma-2",
  "backend": "sentence-transformers",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.01708984375, -0.003997802734375, 0.056640625, /* ... 256 values in total */]
    }
  ],
  "usage": {
    "prompt_tokens": 13,
    "total_tokens": 13,
    "cost": 0.0
  }
}

Models

Available embedding models.

Supported Inputs

Content part types shared across chat and embeddings.

Authorizations

Authorization

string

header

required

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

Body

application/json

OpenAI-compatible embeddings request.

The input field is intentionally polymorphic to match both OpenAI's API (string / list-of-strings / list-of-token-ids) and vLLM's multimodal extension (list of content parts). The router normalises everything to a list of items before handing it to the backend, so individual backends only see one shape.

model

string

required

input

required

encoding_format

enum<string>

default:float

Available options:

float,

base64

dimensions

integer | null

user

string | null

prompt_name

string | null

document_pages

any[] | null

document_max_pages

integer | null

truncate_prompt_tokens

integer | null

Response

Successful Response

OpenAI-compatible embeddings response with audit extras (served_model_id and backend).

model

string

required

data

EmbeddingData · object[]

required

Hide child attributes

data.index

integer

required

data.embedding

required

data.object

string

default:embedding

Allowed value: "embedding"

string

object

string

default:list

Allowed value: "list"

created

integer

served_model_id

string | null

backend

string | null

usage

EmbeddingUsage · object

Hide child attributes

usage.prompt_tokens

integer

default:0

usage.total_tokens

integer

default:0

usage.cost

number | null

OpenAI Compatible API

TypeSafe Compatible API

Request parameters

Text input

Multimodal input

Task prefixes and dimensions

Models

Supported Inputs

Authorizations

Body

Response

​Request parameters

​Text input

​Multimodal input

​Task prefixes and dimensions

​Related

Models

Supported Inputs

Authorizations

Body

Response

Request parameters

Text input

Multimodal input

Task prefixes and dimensions

Related