---
title: "VL Embedding"
method: POST
path: "/vl-embedding"
---

# VL Embedding

`POST /vl-embedding`

## Request

- Base URL: `https://api.octen.ai`
- URL: `https://api.octen.ai/vl-embedding`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Converts multimodal input (text, images, and videos) into vector representations. Supports a single fused vector across modalities, independent per-element vectors, configurable output dimensions, video frame sampling control, and a custom task instruction.

## Request body

- VLEmbeddingRequest
  - `model` 'octen-vl-embedding' | 'octen-vl-embedding-large', required: The multimodal embedding model used for this request.
  - `input` VLEmbeddingInput, required: The multimodal content to be vectorized. Supports text, images, videos, and combinations. Maximum total elements per request: 20. Maximum images per request: 5. Maximum videos per request: 1.
    - `contents` VLEmbeddingContent[], required: The list of content elements to process.
      - `text` string: Text input. Maximum 10,000 characters per entry.
      - `image` string: Image input. Supports a URL or a Base64 string. Maximum 5MB per image. Supported formats: JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, SGI.
      - `video` string: Video input. URL only. Maximum 50MB per file. Supported formats: MP4, AVI, MOV.
  - `enable_fusion` boolean: Whether to generate a fused embedding. When `true`, all elements in `contents` are fused into a single vector; when `false`, each element produces an independent vector.
  - `dimension` integer: The dimensionality of the output embedding vectors. Defaults to the model's max dimension (octen-vl-embedding: 2048, octen-vl-embedding-large: 4096). Any positive integer ≤ the model's max dimension is allowed.
  - `fps` number: Frames sampled per second of video. For example, `0.5` samples one frame every two seconds. Lower values sample fewer frames and reduce video token consumption. Each video is sampled to at most 64 frames.
  - `instruct` string: Custom task description used to guide the model in understanding the query intent. Its length counts toward `input_tokens` and shares the 10,000-character total limit with `contents`.

## Response `200`

Successful VL embedding response

- VLEmbeddingResponse
  - `code` integer: Business status code. 0 indicates success.
  - `msg` string: A message describing the result.
  - `request_id` string: The unique identifier for this request.
  - `data` VLEmbeddingData: The main VL embedding response payload.
    - `results` VLEmbeddingResult[]: A list of embedding results.
      - `index` integer: The position of the embedding in the input array.
      - `embedding` number[]: The generated embedding vector. Type and encoding may vary based on the input parameters.
      - `type` 'vl' | 'fusion': The result type.
    - `model` string: The embedding model used for this request.
  - `meta` VLEmbeddingMeta: Additional metadata for the VL embedding request.
    - `usage` VLEmbeddingUsage: Usage information for the VL embedding request.
      - `input_tokens` integer: Total number of input tokens processed in this request.
      - `text_tokens` integer: Number of tokens consumed by text inputs.
      - `image_tokens` integer: Total tokens consumed by image and video inputs (videos are sampled into frames before counting).
      - `image_count` integer: Number of images in the request (excluding frames extracted from videos).
      - `duration` integer: Total duration of video inputs in seconds.
    - `warning` string, nullable: Optional warning message, if any.

## Other responses

- `400`: Missing or invalid parameter — Returned when a required parameter is missing or has an invalid value.
- `401`: Invalid API Key — Returned when the API key is missing or invalid.
- `403`: Insufficient balance in account — Returned when the account balance is insufficient to complete the request.
- `413`: Payload too large — Returned when the request payload exceeds the size limit.
- `415`: Unsupported media type — Returned when the input media format is not supported.
- `429`: Exceeding the rate limit — Returned when the request exceeds the configured rate limit.
- `500`: Internal error — Returned when an unexpected server-side error occurs.

---

[API](https://skmtc.dev/octen/apis/octen-api.md) - [All operations](https://skmtc.dev/octen/apis/octen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octen/apis/octen-api/revisions/aaa6caaf46b0?raw)