API_DOCS.md

API Documentation

The Unified Embedding API provides an OpenAI-compatible interface for dense embeddings, sparse embeddings, and document reranking.

Base URL

http://localhost:7860/api/v1

For Hugging Face Spaces:

https://YOUR_SPACE.hf.space/api/v1

---

Authentication

Authentication is not required by default.

When using the official OpenAI SDK, an API key is still required by the client but its value is ignored.

client = OpenAI(
    base_url="https://YOUR_SPACE.hf.space/api/v1",
    api_key="not-required"
)

---

Endpoints

Method	Endpoint	Description
POST	/embeddings	Generate dense embeddings
POST	/embed_sparse	Generate sparse embeddings
POST	/rerank	Rank documents based on a query
GET	/models	List available models
GET	/health	Health check

---

Dense Embeddings

Generate dense vector embeddings.

Request

POST

/api/v1/embeddings

Body

{
  "input": [
    "Machine learning",
    "Artificial Intelligence"
  ],
  "model": "qwen3-0.6b"
}

Field	Type	Required	Description
input	string	string[]	Yes
model	string	Yes	Configured embedding model
encoding_format	string	No	Currently returns float embeddings

---

Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.124,
        -0.554,
        0.873
      ]
    }
  ],
  "model": "qwen3-0.6b",
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  }
}

---

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR_SPACE.hf.space/api/v1",
    api_key="not-required"
)

response = client.embeddings.create(
    input="Large Language Models",
    model="qwen3-0.6b"
)

embedding = response.data[0].embedding

---

cURL

curl -X POST \
http://localhost:7860/api/v1/embeddings \
-H "Content-Type: application/json" \
-d '{
    "input":"Large Language Models",
    "model":"qwen3-0.6b"
}'

---

Sparse Embeddings

Generate sparse embeddings (SPLADE).

Request

POST /api/v1/embed_sparse

Body

{
  "input": [
    "Hybrid Search"
  ],
  "model": "splade"
}

---

Response

{
  "object":"list",
  "data":[
    {
      "index":0,
      "indices":[
        24,
        91,
        118
      ],
      "values":[
        0.87,
        0.41,
        0.29
      ]
    }
  ]
}

---

Document Reranking

Ranks retrieved documents according to their relevance to a query.

Request

POST /api/v1/rerank

Body

{
  "query":"What is LangGraph?",
  "documents":[
    "LangGraph is an orchestration framework.",
    "React is a frontend library.",
    "FastAPI is a Python framework."
  ],
  "model":"bge-reranker-base",
  "top_k":2
}

Field	Type	Required
query	string	Yes
documents	string[]	Yes
model	string	Yes
top_k	integer	No

---

Response

{
  "results":[
    {
      "index":0,
      "score":0.992,
      "text":"LangGraph is an orchestration framework."
    },
    {
      "index":2,
      "score":0.843,
      "text":"FastAPI is a Python framework."
    }
  ]
}

---

Available Models

Returns every configured model.

Request

GET /api/v1/models

Response

{
  "models":[
    {
      "id":"qwen3-0.6b",
      "type":"embeddings"
    },
    {
      "id":"splade",
      "type":"sparse-embeddings"
    },
    {
      "id":"bge-reranker-base",
      "type":"rerank"
    }
  ]
}

---

Health Check

Check server status.

Request

GET /health

Response

{
  "status":"healthy"
}

---

Error Responses

The API follows standard HTTP status codes.

Status	Description
200	Success
400	Invalid request
404	Resource not found
422	Validation error
500	Internal server error

Example:

{
  "detail":"Model 'unknown-model' is not configured."
}

---

Model Configuration

Available models are defined in:

config/models.yaml

Example:

models:

  qwen3:
    name: Qwen/Qwen3-Embedding-0.6B
    type: embeddings

  splade:
    name: prithivida/Splade_PP_en_v1
    type: sparse-embeddings

  reranker:
    name: BAAI/bge-reranker-base
    type: rerank

Adding a new model only requires updating this configuration file. No application code changes are needed.

---

OpenAI Compatibility

The /embeddings endpoint implements the OpenAI Embeddings API specification.

Migrating from OpenAI usually requires changing only the client configuration.

client = OpenAI(
    base_url="https://YOUR_SPACE.hf.space/api/v1",
    api_key="not-required"
)

Your existing embedding requests can remain unchanged.