Embeddings

Turn text into vectors for retrieval, and rerank a candidate set against a query.

Retrieval takes two models. An embedding model turns text into a vector, so a query and a document can be compared by distance; a reranker takes the handful of candidates that search returned and scores each one against the query directly, which is slower per document and far more accurate. A typical pipeline embeds the corpus once, retrieves 50 candidates by vector distance, then reranks them down to the 5 that go into the prompt.

Both kinds of model appear in the model catalogue and both can be fine-tuned. Filter with modality=embedding for the bi-encoders and modality=rerank for the cross-encoders. Fine-tuning either one takes a retrieval file of query and passage pairs rather than the conversations a chat model is trained on, and it is usually the cheapest large accuracy win available on a retrieval system: the base models are small, and a few thousand labelled pairs from your own corpus move recall substantially.

Embedding and reranking calls are metered on the tokens they read, because they return a vector or a score rather than tokens.

Create embeddings

POST/v1/embeddingsscope: infer

Embeds one or more inputs and returns a vector for each. Inputs are embedded in the order given and the response preserves that order, so results can be zipped back onto the source rows.

Body parameters

modelstringrequired

An embedding model ID, or a nucleus:// path to a fine-tuned checkpoint.

inputstring | string[]required

The text to embed. Pass an array to embed a batch in one call, up to 256 inputs.

dimensionsinteger

Truncate each vector to this many dimensions. Only accepted for models trained with Matryoshka representation; the model's full width is the default.

encoding_formatstring

float (default) returns an array of numbers. base64 returns a packed little-endian float32 buffer, which is roughly three times smaller over the wire.

An input longer than the model's context_length is rejected rather than silently truncated, so a document that will not fit is a 400 you can act on instead of a vector that quietly represents the first half.

curl https://api.nucleus-ai.io/v1/embeddings \
  -H "Authorization: Bearer $NUCLEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-Embedding-8B",
    "input": ["What is the refund window?", "Refunds are accepted within 30 days."]
  }'

200 OK

{
  "object": "list",
  "model": "Qwen/Qwen3-Embedding-8B",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0213, -0.0447, 0.0091, "…4093 more"]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [0.0198, -0.0392, 0.0164, "…4093 more"]
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "total_tokens": 19
  }
}

Rerank documents

POST/v1/rerankscope: infer

Scores each document against the query with a cross-encoder and returns them ordered by relevance. Unlike an embedding comparison, the query and the document are read together, so the model can weigh how they relate rather than how close two independent vectors happen to land.

Body parameters

modelstringrequired

A reranking model ID, or a nucleus:// path to a fine-tuned checkpoint.

querystringrequired

The query to score each document against.

documentsstring[]required

The candidate documents, up to 256 per call.

top_ninteger

Return only the highest-scoring top_n results. All documents are scored either way, so this trims the response rather than the work.

return_documentsboolean

Include each document's text in the response. false by default, since the caller already holds the text it sent and index is enough to match results back.

Scores are comparable within one response and not across responses: they rank this candidate set against this query. Use the ordering, or a threshold you have calibrated on your own evaluation set, rather than a fixed cut-off borrowed from another model.

curl https://api.nucleus-ai.io/v1/rerank \
  -H "Authorization: Bearer $NUCLEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-reranker-v2-m3",
    "query": "What is the refund window?",
    "documents": [
      "Refunds are accepted within 30 days of delivery.",
      "Our warehouse ships on weekdays before 4pm.",
      "Store credit never expires."
    ],
    "top_n": 2
  }'

200 OK

{
  "object": "list",
  "model": "BAAI/bge-reranker-v2-m3",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.9814
    },
    {
      "index": 2,
      "relevance_score": 0.2077
    }
  ],
  "usage": {
    "prompt_tokens": 46,
    "total_tokens": 46
  }
}

Embeddings

Create embeddings

Rerank documents

On this page