--- title: "Encode" method: POST path: "/v1/encode/{model}" tags: ["encode"] --- # Encode `POST /v1/encode/{model}` Generate embeddings for input items. Supports both msgpack and JSON request bodies (Content-Type header). Returns msgpack by default, JSON if Accept header requests it. Args: model: Model name to use for encoding. http_request: FastAPI request object (for body and app state). accept: Accept header for response content negotiation. x_machine_profile: Machine profile header for routing validation. Returns: EncodeResponse with embeddings for each input item. Format depends on Accept header: msgpack (default) or JSON. Raises: HTTPException: 400 for invalid input or profile mismatch, 404 if model not found, 503 if not loaded. ## Path parameters - `model` string, required ## Headers - `accept` string, nullable - `X-SIE-MACHINE-PROFILE` string, nullable ## Request body - EncodeRequestModel — Request body for encode endpoint. - `items` ItemModel[], required — Items to encode - `id` string, nullable — Optional identifier for this item. Returned in response. - `text` string, nullable — Text content to encode - `images` ImageInputModel[], nullable — Images for multimodal models - `data` string, byte, required — Image data. Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Image format hint: 'jpeg', 'png', etc. - `audio` AudioInputModel — Audio input for audio models. - `data` string, byte, required — Audio data. Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Audio format: 'wav', 'mp3', etc. - `sample_rate` integer, nullable — Sample rate in Hz. Must be positive. - `video` VideoInputModel — Video input for video models. - `data` string, byte, required — Video data. Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Video format: 'mp4', 'webm', etc. - `document` DocumentInputModel — Document input for composite-document extractors (PDF, DOCX, HTML, ...). - `data` string, byte, required — Document bytes (raw file content). Base64-encoded on the JSON path; native binary on the msgpack path. - `format` string, nullable — Document format hint: 'pdf', 'docx', 'html', etc. - `metadata` object, nullable — Arbitrary metadata. Returned in response. - `params` EncodeParamsModel — Parameters for encode requests. - `output_types` string[], nullable — Output types to return - `instruction` string, nullable — Task instruction for instruction-tuned models - `output_dtype` 'float32' | 'float16' | 'int8' | 'binary', nullable — Output dtype - `options` object, nullable — Runtime options ## Response `200` Embeddings generated successfully - EncodeResponseModel — Response from encode endpoint. - `model` string, required — Model used for encoding - `items` EncodeResultModel[], required — Encoding results for each input item - `id` string, nullable — Item ID (if provided in request) - `dense` DenseVectorModel — Dense embedding vector. - `dims` integer, required — Vector dimensionality - `dtype` 'float32' | 'float16' | 'int8' | 'uint8' | 'binary', required — Data type - `values` number[], required — Vector values - `sparse` SparseVectorModel — Sparse embedding vector. - `dims` integer, nullable — Vocabulary size - `dtype` 'float32' | 'float16', required — Data type - `indices` integer[], required — Non-zero indices - `values` number[], required — Non-zero values - `multivector` MultiVectorModel — Multi-vector (token-level) embedding. - `token_dims` integer, required — Dimension per token - `num_tokens` integer, required — Number of tokens - `dtype` 'float32' | 'float16' | 'int8' | 'uint8' | 'binary', required — Data type - `values` array[], required — Token embeddings (num_tokens x token_dims) - number[] - `timing` TimingInfoModel — Request timing breakdown. - `total_ms` number, required — Total request time in milliseconds - `queue_ms` number, required — Time waiting in queue - `tokenization_ms` number, required — Tokenization time - `inference_ms` number, required — Model inference time - `postprocessing_ms` number, nullable — Postprocessing time - `usage` UsageModel — Authoritative worker-emitted usage. Post-tokenization counts, never a character estimate. A reported 0 is a measurement (a video-only encode reads no text); an absent block means the counts were unavailable on this path. - `input_tokens` integer, required — Post-truncation input tokens processed - `images` integer, nullable — Images processed across the request's items ## Other responses - `400` — Invalid request - `404` — Model not found - `422` — Validation Error - `502` — Terminal model-load failure (MODEL_LOAD_FAILED). Carried in the ``detail`` envelope: ``{code, message, error_class, permanent, attempts}``. No ``Retry-After`` header — clients MUST NOT auto-retry. - `503` — Model not loaded or service unavailable ## Changes - **2026-08-27** `26ac644915a4` — 4 breaking, 9 info - the `items/items/document/anyOf[subschema #1: DocumentInputModel]/data` request property contentEncoding changed from `` to `base64` (media type: application/json) - the `items/items/document/anyOf[subschema #1: DocumentInputModel]/data` request property contentEncoding changed from `` to `base64` (media type: application/msgpack) - the `items/items/images/anyOf[subschema #1]/items/data` request property contentEncoding changed from `` to `base64` (media type: application/json) - the `items/items/images/anyOf[subschema #1]/items/data` request property contentEncoding changed from `` to `base64` (media type: application/msgpack) - …9 more - **2026-07-22** `872f29afcb07` — 4 breaking, 12 info - removed `#/components/schemas/EncodeParamsModel` from the `params` request property `anyOf` list (media type: application/json) - removed `#/components/schemas/EncodeParamsModel` from the `params` request property `anyOf` list (media type: application/msgpack) - the `items/items/` request property type/format changed from ``/`` to `object`/`` (media type: application/json) - the `items/items/` request property type/format changed from ``/`` to `object`/`` (media type: application/msgpack) - …12 more - **2026-04-29** `7a3933f67211` — 1 info - added the non-success response with the status `502` - **2026-04-29** `62c36304882b` — 1 info - removed the non-success response with the status `502` [Change history](https://skmtc.dev/superlinked/apis/sie-server/changes/v1/encode/:model/post.md) --- [API](https://skmtc.dev/superlinked/apis/sie-server.md) · [All operations](https://skmtc.dev/superlinked/apis/sie-server/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/superlinked/sie-server/revisions/26ac644915a4/schema)