---
title: "Create Embeddings"
method: POST
path: "/v1/embeddings"
tags: ["openai-compat"]
---

# Create Embeddings

`POST /v1/embeddings`

Create embeddings using OpenAI-compatible API.

This endpoint is compatible with OpenAI's /v1/embeddings API, allowing
drop-in replacement for any OpenAI SDK or client. Route-generated errors
are emitted as top-level OpenAI ``{"error": {...}}`` envelopes, matching
``/v1/completions``. The one exception is 422 request-body validation,
which still returns FastAPI's ``HTTPValidationError`` ``{"detail": [...]}``
shape (out of scope for this route's error handling; known residual).

Args:
    request: OpenAI-format embedding request.
    http_request: FastAPI request (for app state).
    x_machine_profile: Machine profile header for routing validation.

Returns:
    OpenAI-format embedding response with embeddings and usage info.

## Headers

- `X-SIE-MACHINE-PROFILE` string, nullable

## Request body

- OpenAIEmbeddingRequest — OpenAI-compatible embedding request. See: https://platform.openai.com/docs/api-reference/embeddings
  - `model` string, required — Model ID to use for embedding
  - `input` union, required — Input text(s) or token array(s) to embed.
    - string
    - string[]
    - integer[]
    - array[]
      - integer[]
  - `encoding_format` 'float' | 'base64', nullable — Format for embeddings: 'float' or 'base64'
  - `dimensions` integer, nullable — Requested embedding width. SIE always returns the model's native dense width, so this is accepted only when it equals that width; any other value is rejected with 400 `unsupported_field` rather than ignored.
  - `user` string, nullable — User ID for tracking (ignored by SIE)

## Response `200`

Embeddings generated successfully

- OpenAIEmbeddingResponse — OpenAI-compatible embedding response.
  - `object` 'list'
  - `data` OpenAIEmbeddingData[], required — Embedding results
    - `object` 'embedding'
    - `embedding` union, required — Embedding vector (floats or base64)
      - number[]
      - string
    - `index` integer, required — Index in the input array
  - `model` string, required — Model used
  - `usage` OpenAIUsage, required — Token usage information.
    - `prompt_tokens` integer, required — Number of tokens in the input
    - `total_tokens` integer, required — Total tokens (same as prompt_tokens for embeddings)

## Other responses

- `400` — Invalid request
- `404` — Model not found
- `422` — Validation Error
- `502` — Terminal model-load failure (MODEL_LOAD_FAILED). Carried in the top-level OpenAI ``error`` envelope, whose object adds the model-load extras ``error_class``, ``permanent``, and ``attempts`` to ``{message, type, param, code}``. No ``Retry-After`` header — clients MUST NOT auto-retry.
- `503` — Service unavailable (retryable). A cold model starts a background load and returns ``MODEL_LOADING`` with a ``Retry-After`` header immediately instead of blocking the request — clients should retry after the indicated delay. Also returned while unloading, on a full queue, and under transient resource exhaustion. The body is the top-level OpenAI ``error`` envelope.

## Changes

> 43 revisions in range; 1 could not be searched.

- **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/embeddings/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)