Embedding

Embedding & Reranker Quickstart

This quickstart walks you through generating your first embedding with Infron.

Embedding quickstart

Basic Request

To generate embeddings, send a POST request to /embeddings with your text input and chosen model:

Python

import requests

response = requests.post(
  "https://llm.onerouter.pro/v1/embeddings",
  headers={
    "Authorization": f"Bearer {{API_KEY_REF}}",
    "Content-Type": "application/json",
  },
  json={
    "model": "{{MODEL}}",
    "input": "The quick brown fox jumps over the lazy dog"
  }
)

data = response.json()
embedding = data["data"][0]["embedding"]
print(f"Embedding dimension: {len(embedding)}")

TypeScript (fetch)

cURL

Batch Processing

You can generate embeddings for multiple texts in a single request by passing an array of strings:

Python

import requests

response = requests.post(
  "https://llm.onerouter.pro/v1/embeddings",
  headers={
    "Authorization": f"Bearer {{API_KEY_REF}}",
    "Content-Type": "application/json",
  },
  json={
    "model": "{{MODEL}}",
    "input": [
      "Machine learning is a subset of artificial intelligence",
      "Deep learning uses neural networks with multiple layers",
      "Natural language processing enables computers to understand text"
    ]
  }
)

data = response.json()
for i, item in enumerate(data["data"]):
  print(f"Embedding {i}: {len(item['embedding'])} dimensions")

TypeScript (fetch)

cURL

Semantic Search

Here's a complete example of building a semantic search system using embeddings:

Python

import requests
import numpy as np

API_KEY = "{{API_KEY_REF}}"

# Sample documents
documents = [
  "The cat sat on the mat",
  "Dogs are loyal companions",
  "Python is a programming language",
  "Machine learning models require training data",
  "The weather is sunny today"
]

def cosine_similarity(a, b):
  """Calculate cosine similarity between two vectors"""
  dot_product = np.dot(a, b)
  magnitude_a = np.linalg.norm(a)
  magnitude_b = np.linalg.norm(b)
  return dot_product / (magnitude_a * magnitude_b)

def semantic_search(query, documents):
  """Perform semantic search using embeddings"""
  # Generate embeddings for query and all documents
  response = requests.post(
    "https://llm.onerouter.pro/v1/embeddings",
    headers={
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json",
    },
    json={
      "model": "{{MODEL}}",
      "input": [query] + documents
    }
  )
  
  data = response.json()
  query_embedding = np.array(data["data"][0]["embedding"])
  doc_embeddings = [np.array(item["embedding"]) for item in data["data"][1:]]
  
  # Calculate similarity scores
  results = []
  for i, doc in enumerate(documents):
    similarity = cosine_similarity(query_embedding, doc_embeddings[i])
    results.append({"document": doc, "similarity": similarity})
  
  # Sort by similarity (highest first)
  results.sort(key=lambda x: x["similarity"], reverse=True)
  
  return results

# Search for documents related to pets
results = semantic_search("pets and animals", documents)
print("Search results:")
for i, result in enumerate(results):
  print(f"{i + 1}. {result['document']} (similarity: {result['similarity']:.4f})")

Expected output:

Search results:
1. Dogs are loyal companions (similarity: 0.8234)
2. The cat sat on the mat (similarity: 0.7891)
3. The weather is sunny today (similarity: 0.3456)
4. Machine learning models require training data (similarity: 0.2987)
5. Python is a programming language (similarity: 0.2654)

Reranker quickstart

In the example below, we use the Rerank API endpoint to index the list of documents from most to least relevant to the query "What is the capital of the United States?".

Example with Texts

Request

In this example, the documents being passed in are a list of strings:

Python

import requests
import json

url = "https://llm.onerouter.pro/v1/rerank"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{API_KEY}}"
}
data = {
    "model": "voyage-rerank-2.5",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
        "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.",
        "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
        "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
        "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.",
        "Capital punishment has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment.",
    ]        
}

response = requests.post(url, headers=headers, data=json.dumps(data))

print(response.json())

cURL

Response

{
  "id": "26c8ad0bb95011f0a5edda799fbd82e9",
  "results": [
    {
      "index": 3, // "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) ..."
      "relevance_score": 0.9990564
    },
    {
      "index": 4, // "Capital punishment has existed in the United States since before the United States was a country. As of 2017 ..."
      "relevance_score": 0.7516481
    },
    {
      "index": 1, // "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division ..."
      "relevance_score": 0.08882029
    },
    {
      "index": 0, // "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a ..."
      "relevance_score": 0.058238626
    },
    {
      "index": 2, // ""Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people ..."
      "relevance_score": 0.019946935
    }
  ]
}

Example with Structured Data:

If your documents contain structured data, for best performance we recommend formatting them as YAML strings.

Request

Python

import requests
import json

url = "https://llm.onerouter.pro/v1/rerank"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{API_KEY}}"
}
data = {
    "model": "voyage-rerank-2.5",
    "query": "What is the capital of the United States?",
    "top_n": 3,
    "documents": [
        {
            "Title": "Facts about Carson City",
            "Content": "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.",
        },
        {
            "Title": "The Commonwealth of Northern Mariana Islands",
            "Content": "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
        },
        {
            "Title": "The Capital of United States Virgin Islands",
            "Content": "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
        },
        {
            "Title": "Washington D.C.",
            "Content": "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.",
        },
        {
            "Title": "Capital Punishment in the US",
            "Content": "Capital punishment has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment.",
        },
    ]        
}

response = requests.post(url, headers=headers, data=json.dumps(data))

print(response.json())

cURL

In the documents parameter, we are passing in a list YAML strings, representing the structured data.

Response

{
  "id": "26c8ad0bb95011f0a5edda799fbd82e9",
  "results": [
    {
      "index": 3, // "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) ..."
      "relevance_score": 0.9990564
    },
    {
      "index": 4, // "Capital punishment has existed in the United States since before the United States was a country. As of 2017 ..."
      "relevance_score": 0.7516481
    },
    {
      "index": 1, // "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division ..."
      "relevance_score": 0.08882029
    },
    {
      "index": 0, // "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a ..."
      "relevance_score": 0.058238626
    },
    {
      "index": 2, // ""Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people ..."
      "relevance_score": 0.019946935
    }
  ]
}