Name: BGE-M3 API: Multilingual Embeddings for Hybrid Search
Brand: magicapi
SKU: api-magicapi-multilingual-embedding-hybrid-retrieval-ifaas-uk-bge-m3
Availability: InStock
Author: API Market

Shashank Agarwal

# 🔢 Multilingual Text Embedding API (BAAI BGE-M3)

## Overview
BGE-M3 is a multilingual text embedding model from BAAI. This listing returns both dense and sparse embeddings for dense and sparse hybrid retrieval.

Send one text in `text`, or several texts as a JSON array string in `texts_json` for batch embedding. Each text gets a 1,024-value dense vector plus sparse token weights (`sparse_indices` and `sparse_values`). `max_length` (up to 8192) sets how many tokens per text are used before truncation.

## Features
- **Dense and sparse in one call**: a 1,024-dimension dense vector and sparse token weights per text.
- **Multilingual**: one model for texts in many languages.
- **Batch embedding**: pass a JSON array of texts in `texts_json`; `text` is used only when `texts_json` is empty.
- **Long inputs**: `max_length` up to 8192 tokens per text (default 8192).

## Use Cases
1. **Semantic search**: embed documents and queries and rank by vector similarity.
2. **Hybrid retrieval**: combine dense similarity with sparse term weights for retrieval-augmented generation.
3. **Multilingual search**: index content in several languages with one model.
4. **Clustering and deduplication**: group or match similar texts by their vectors.

## Visual Examples
### Example Input
Text: "The buyer shall pay the purchase price on the agreed date."

Settings: `max_length` 8192, `texts_json` `[]` (empty, so `text` is used).

### Example Output
One embedding with a 1,024-value dense vector (first 8 values shown) and 12 sparse token weights:

````json
{
  "dense": [
    -0.006221771240234375,
    0.00901031494140625,
    -0.05133056640625,
    0.0281524658203125,
    -0.0165252685546875,
    0.0170440673828125,
    0.0075836181640625,
    -0.006130218505859375
  ],
  "dense_dim": 1024,
  "sparse_indices": [
    581,
    22113,
    56,
    35299,
    8783,
    70,
    59038,
    27167,
    98,
    176506,
    5622,
    5
  ],
  "sparse_token_count": 12,
  "sparse_values": [
    0.1029052734375,
    0.260009765625,
    0.1966552734375,
    0.220458984375,
    0.27685546875,
    0.11700439453125,
    0.2724609375,
    0.2587890625,
    0.165771484375,
    0.260986328125,
    0.19921875,
    0.1072998046875
  ],
  "text_index": 0,
  "text_length": 58
}
````

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `text` | string | No | `""` |  | Single text to embed. Used when `texts_json` is empty. |
| `texts_json` | string | No | `[]` |  | Optional JSON array of texts for batch embedding, sent as a string, for example `["first text", "second text"]`. |
| `max_length` | integer | No | `8192` | `1` to `8192` | Maximum tokens per text before truncation. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.001 per API unit.
- **1 API unit = 1 request covering up to 4 seconds of processing.** A request that takes longer uses one more unit for each started 4-second block (for example, 5 seconds of processing is 2 units, $0.002).
- A batch in `texts_json` takes longer than a single text, so very large batches can use more than one unit.
- **Example cost**: the example request took 1.81 seconds of processing, so it used 1 API unit = **$0.001**.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/multilingual-embedding-hybrid-retrieval-ifaas-uk-bge-m3`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/multilingual-embedding-hybrid-retrieval-ifaas-uk-bge-m3/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "5ff1b9855a8f333e969d1782e90edc9b3133224ef0acb209539217b0b7af700c",
    "input": {
      "text": "The buyer shall pay the purchase price on the agreed date.",
      "max_length": 8192,
      "texts_json": "[]"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "766h0mt5w5rga0d1d10aengs8w",
  "version": "5ff1b9855a8f333e969d1782e90edc9b3133224ef0acb209539217b0b7af700c",
  "status": "starting",
  "created_at": "2026-10-23T10:13:25.277Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/multilingual-embedding-hybrid-retrieval-ifaas-uk-bge-m3/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "766h0mt5w5rga0d1d10aengs8w",
  "status": "succeeded",
  "output": {
    "embedding": {
      "dense": [
        -0.006221771240234375,
        0.00901031494140625,
        -0.05133056640625,
        0.0281524658203125,
        -0.0165252685546875,
        0.0170440673828125,
        0.0075836181640625,
        -0.006130218505859375
      ],
      "dense_dim": 1024,
      "sparse_indices": [
        581,
        22113,
        56,
        35299,
        8783,
        70,
        59038,
        27167,
        98,
        176506,
        5622,
        5
      ],
      "sparse_token_count": 12,
      "sparse_values": [
        0.1029052734375,
        0.260009765625,
        0.1966552734375,
        0.220458984375,
        0.27685546875,
        0.11700439453125,
        0.2724609375,
        0.2587890625,
        0.165771484375,
        0.260986328125,
        0.19921875,
        0.1072998046875
      ],
      "text_index": 0,
      "text_length": 58
    },
    "embedding_count": 1,
    "embeddings": [
      {
        "dense": [
          -0.006221771240234375,
          0.00901031494140625,
          -0.05133056640625,
          0.0281524658203125,
          -0.0165252685546875,
          0.0170440673828125,
          0.0075836181640625,
          -0.006130218505859375
        ],
        "dense_dim": 1024,
        "sparse_indices": [
          581,
          22113,
          56,
          35299,
          8783,
          70,
          59038,
          27167,
          98,
          176506,
          5622,
          5
        ],
        "sparse_token_count": 12,
        "sparse_values": [
          0.1029052734375,
          0.260009765625,
          0.1966552734375,
          0.220458984375,
          0.27685546875,
          0.11700439453125,
          0.2724609375,
          0.2587890625,
          0.165771484375,
          0.260986328125,
          0.19921875,
          0.1072998046875
        ],
        "text_index": 0,
        "text_length": 58
      }
    ],
    "inference_ms": 1780,
    "load_ms": 3034,
    "model": "BAAI/bge-m3",
    "model_source": "/src/weights/bge-m3",
    "use_fp16": true
  },
  "error": null,
  "created_at": "2026-10-23T10:13:25.277Z",
  "started_at": "2026-10-23T10:14:38.324Z",
  "completed_at": "2026-10-23T10:14:40.137Z"
}
```

`output` is an object. `embeddings` has one entry per input text with `dense` (1,024 numbers, shortened to 8 above), `dense_dim`, `sparse_indices` and `sparse_values` (token ids and their weights), `sparse_token_count`, `text_index` (position in the input) and `text_length` (characters). `embedding` is the entry for the first text, `embedding_count` is the number of texts, and `inference_ms`, `load_ms`, `model`, `model_source` and `use_fp16` describe the run.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a `max_length` above 8192.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/multilingual-embedding-hybrid-retrieval-ifaas-uk-bge-m3";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "5ff1b9855a8f333e969d1782e90edc9b3133224ef0acb209539217b0b7af700c", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
    "text": "The buyer shall pay the purchase price on the agreed date.",
    "max_length": 8192,
    "texts_json": "[]"
  }).then((output) => console.log(JSON.stringify(output, null, 2)));
```

#### Python
```python
import json
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/multilingual-embedding-hybrid-retrieval-ifaas-uk-bge-m3"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "5ff1b9855a8f333e969d1782e90edc9b3133224ef0acb209539217b0b7af700c", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


output = create_and_wait_for_prediction({
    "text": "The buyer shall pay the purchase price on the agreed date.",
    "max_length": 8192,
    "texts_json": "[]"
})
print(json.dumps(output, indent=2))
```

## FAQ
- **How do I embed several texts at once?**
  - Send them as a JSON array string in `texts_json`, for example `["first text", "second text"]`. `output.embeddings` then has one entry per text, in order (`text_index`).
- **What are the sparse values for?**
  - `sparse_indices` and `sparse_values` are token ids and their weights. Use them for keyword-style matching next to the dense vector in hybrid retrieval.
- **How many dimensions does the dense vector have?**
  - 1,024 (`dense_dim`).
- **What happens to long texts?**
  - Each text is truncated to `max_length` tokens (default and maximum 8192).
- **How is a request billed?**
  - $0.001 per request for up to 4 seconds of processing. The example took 1.81 seconds, so it cost one unit.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.

## Contact Us
If you have any questions, reach out to us through the chat on the bottom right of the page. You can also email our support team at hello@magicapi.com.


Embed texts with BAAI's multilingual BGE-M3 and get dense vectors plus sparse token weights for hybrid retrieval, single or batch.