---
title: "Create embeddings"
method: POST
path: "/api/v1/embeddings"
tags: ["AI"]
---

# Create embeddings

`POST /api/v1/embeddings`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/v1/embeddings`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Returns one embedding vector per input string. The request and success bodies follow the OpenAI embeddings API shape; error bodies use the standard B4M error envelope. `model` is any embedding model this deployment supports (OpenAI, Voyage AI, Amazon Bedrock, or a self-hosted Ollama model); `input` is a string or up to 2048 strings, at most 300000 tokens in total and each within the model context window. The input count is further capped so inputs x output width stays within 196608 values (128 inputs at 1536 dimensions) - page larger jobs across requests. Pre-tokenized input (arrays of token ids) is not accepted; clients that send it by default, such as LangChain's Python `OpenAIEmbeddings`, must be set to send strings (`check_embedding_ctx_length=False`). `dimensions` shortens the vector on models that support it (OpenAI `text-embedding-3-*`, and Voyage models with several published widths). Billed in credits per input token from the per-model embedding rate, reserved before the provider call and refunded if it fails. Authenticate with an API key (`b4m_live_`) carrying `ai:generate`, or a JWT.

## Request body

- CreateEmbeddingsRequest
  - `model` union, required
    - 'text-embedding-3-small' | 'text-embedding-3-large' | 'text-embedding-ada-002'
    - 'voyage-3-large' | 'voyage-3' | 'voyage-3-lite' | 'voyage-code-3' | 'voyage-finance-3' | 'voyage-law-3'
    - 'amazon.titan-embed-text-v2:0'
    - 'qwen3-embedding:0.6b' | 'qwen3-embedding:4b' | 'qwen3-embedding:8b' | 'nomic-embed-text' | 'mxbai-embed-large' | 'bge-m3' | 'snowflake-arctic-embed'
  - `input` union, required
    - string
    - string[]
  - `dimensions` integer
  - `encoding_format` 'float' | 'base64'

## Response `200`

One embedding per input, in input order.

- CreateEmbeddingsResponse200
  - `object` 'list', required
  - `data` object[], required
    - `object` 'embedding', required
    - `index` integer, required
    - `embedding` union, required
      - number[]
      - string
  - `model` string, required
  - `usage` object, required
    - `prompt_tokens` integer, required
    - `total_tokens` integer, required

## Other responses

- `400`: The billing user or organization could not be resolved, or the API key bills an organization its owner is no longer a member of.
- `401`: Missing/invalid credentials, or the embedding provider refused the configured key (`errorCode: "provider_rejected"`).
- `403`: The API key does not hold any of the required scopes.
- `405`: The path does not serve this HTTP method.
- `422`: Request body failed validation, an input exceeds the model context window, the request exceeds the token or response-size ceiling, the model has no published credit rate, the model cannot produce the requested `dimensions`, or the caller cannot afford the request - the last is tagged `errorCode: "insufficient_credits"`.
- `429`: Per-key rate limit exceeded.
- `502`: The embedding provider failed; reserved credits are refunded.
- `503`: This deployment has no credential for the requested model's provider (`errorCode: "provider_not_configured"`).

---

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