Embeddings

POST /api/v1/llm/v1/embeddings

768-dimensional float embeddings. Supports Idempotency-Key.

Scope: llm:access or llm:embeddings

Request

Field	Type	Notes
model	string	nebula-embed (default).
input	string or array	Up to 256 strings.
task_type	string	SEMANTIC_SIMILARITY (default), RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, CODE_RETRIEVAL_QUERY, CLASSIFICATION or CLUSTERING.
encoding_format	string	float only; anything else is 400. The OpenAI Python SDK sends base64 unless you pass encoding_format="float".
dimensions	integer	768 only.

PythonCopy

result = client.embeddings.create(
    model="nebula-embed",
    input="Session cookie set without the Secure flag",
    encoding_format="float",  # required: the SDK defaults to base64, which is refused
    extra_body={"task_type": "RETRIEVAL_DOCUMENT"},
)
vector = result.data[0].embedding  # 768 floats

Size limits

Caution

Each input can be at most 1,000 UTF-8 bytes, and the whole request at most 1,056 bytes, including a short task instruction BreachLine adds to each input. In practice that is one short passage per request. Split longer text into chunks and send them in separate requests.

A request over a limit gets 400 with a message that names the limit.

Response

ResponseCopy

{
  "object": "list",
  "data": [{"object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, "..."]}],
  "model": "nebula-embed",
  "usage": {"prompt_tokens": 11, "total_tokens": 11}
}

Vectors come back in input order. Token counts are estimated at about 4 characters per token, and embeddings are charged on that estimate at the Nebula input rate.

Choosing a task type

• Index documents with RETRIEVAL_DOCUMENT and embed search queries with RETRIEVAL_QUERY. Using the matching pair gives better retrieval than SEMANTIC_SIMILARITY for both.
• Use CODE_RETRIEVAL_QUERY for natural-language queries over code.
• Compare vectors with cosine similarity.