Embeddings API

The Embeddings API converts text into numerical vectors for text similarity calculations, semantic search, clustering analysis, and other use cases.

Basic Information

API Endpoint

https://api.routin.ai/v1/embeddings

Authentication Add your API Key in the request header:

Authorization: Bearer YOUR_API_KEY

MeteorAI is fully compatible with the OpenAI Embeddings API and supports multiple embedding models.

Request Parameters

Required Parameters

Parameter	Type	Description
`model`	string	Model name, such as `text-embedding-3-small`, `text-embedding-3-large`
`input`	string or array	Text to be embedded, can be a single string or array of strings

Optional Parameters

Parameter	Type	Default	Description
`encoding_format`	string	`float`	Return format: `float` or `base64`
`dimensions`	integer	-	Dimensions of the returned vector (only supported by some models)
`user`	string	-	User identifier

Response Format

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        -0.006929283,
        -0.005336422,
        ...
        -0.009327292
      ]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

Code Examples

Basic Usage

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.routin.ai/v1"
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="人工智能正在改变世界"
)

# Get the embedding vector
embedding = response.data[0].embedding
print(f"Vector dimensions: {len(embedding)}")
print(f"First 5 values: {embedding[:5]}")

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.routin.ai/v1',
});

async function main() {
  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: '人工智能正在改变世界',
  });

  const embedding = response.data[0].embedding;
  console.log(`Vector dimensions: ${embedding.length}`);
  console.log(`First 5 values: ${embedding.slice(0, 5)}`);
}

main();

const OpenAI = require('openai');

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.routin.ai/v1',
});

client.embeddings.create({
  model: 'text-embedding-3-small',
  input: '人工智能正在改变世界',
}).then(response => {
  const embedding = response.data[0].embedding;
  console.log(`Vector dimensions: ${embedding.length}`);
  console.log(`First 5 values: ${embedding.slice(0, 5)}`);
});

using OpenAI.Embeddings;

var client = new EmbeddingClient(
    model: "text-embedding-3-small",
    apiKey: "YOUR_API_KEY",
    new OpenAIClientOptions
    {
        Endpoint = new Uri("https://api.routin.ai/v1")
    }
);

var response = await client.GenerateEmbeddingAsync("人工智能正在改变世界");

var embedding = response.Value.ToFloats();
Console.WriteLine($"Vector dimensions: {embedding.Count}");
Console.WriteLine($"First 5 values: {string.Join(", ", embedding.Take(5))}");

curl https://api.routin.ai/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "人工智能正在改变世界"
  }'

Batch Embeddings

Process multiple texts at once for improved efficiency.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.routin.ai/v1"
)

texts = [
    "人工智能正在改变世界",
    "机器学习是人工智能的一个分支",
    "深度学习推动了AI的发展"
]

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=texts
)

# Process each embedding
for i, embedding_data in enumerate(response.data):
    embedding = embedding_data.embedding
    print(f"Text {i}: {texts[i]}")
    print(f"Vector dimensions: {len(embedding)}")
    print()

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.routin.ai/v1',
});

async function main() {
  const texts = [
    '人工智能正在改变世界',
    '机器学习是人工智能的一个分支',
    '深度学习推动了AI的发展',
  ];

  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: texts,
  });

  response.data.forEach((embeddingData, i) => {
    console.log(`Text ${i}: ${texts[i]}`);
    console.log(`Vector dimensions: ${embeddingData.embedding.length}`);
    console.log();
  });
}

main();

const OpenAI = require('openai');

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.routin.ai/v1',
});

const texts = [
  '人工智能正在改变世界',
  '机器学习是人工智能的一个分支',
  '深度学习推动了AI的发展',
];

client.embeddings.create({
  model: 'text-embedding-3-small',
  input: texts,
}).then(response => {
  response.data.forEach((embeddingData, i) => {
    console.log(`Text ${i}: ${texts[i]}`);
    console.log(`Vector dimensions: ${embeddingData.embedding.length}`);
    console.log();
  });
});

using OpenAI.Embeddings;

var client = new EmbeddingClient(
    model: "text-embedding-3-small",
    apiKey: "YOUR_API_KEY",
    new OpenAIClientOptions
    {
        Endpoint = new Uri("https://api.routin.ai/v1")
    }
);

var texts = new[]
{
    "人工智能正在改变世界",
    "机器学习是人工智能的一个分支",
    "深度学习推动了AI的发展"
};

var response = await client.GenerateEmbeddingsAsync(texts);

for (int i = 0; i < response.Value.Count; i++)
{
    var embedding = response.Value[i].ToFloats();
    Console.WriteLine($"Text {i}: {texts[i]}");
    Console.WriteLine($"Vector dimensions: {embedding.Count}");
    Console.WriteLine();
}

Calculate Text Similarity

Use cosine similarity to calculate semantic similarity between texts.

from openai import OpenAI
import numpy as np

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.routin.ai/v1"
)

def cosine_similarity(a, b):
    """Calculate cosine similarity"""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# Texts to compare
text1 = "猫是一种可爱的宠物"
text2 = "狗是人类最好的朋友"
text3 = "我喜欢养小猫"

# Get embeddings
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=[text1, text2, text3]
)

embeddings = [data.embedding for data in response.data]

# Calculate similarity
sim_1_2 = cosine_similarity(embeddings[0], embeddings[1])
sim_1_3 = cosine_similarity(embeddings[0], embeddings[2])

print(f"Text 1 vs Text 2 similarity: {sim_1_2:.4f}")
print(f"Text 1 vs Text 3 similarity: {sim_1_3:.4f}")

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.routin.ai/v1',
});

function cosineSimilarity(a: number[], b: number[]): number {
  const dotProduct = a.reduce((sum, val, i) => sum + val * b[i], 0);
  const normA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
  const normB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
  return dotProduct / (normA * normB);
}

async function main() {
  const text1 = '猫是一种可爱的宠物';
  const text2 = '狗是人类最好的朋友';
  const text3 = '我喜欢养小猫';

  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: [text1, text2, text3],
  });

  const embeddings = response.data.map(d => d.embedding);

  const sim12 = cosineSimilarity(embeddings[0], embeddings[1]);
  const sim13 = cosineSimilarity(embeddings[0], embeddings[2]);

  console.log(`Text 1 vs Text 2 similarity: ${sim12.toFixed(4)}`);
  console.log(`Text 1 vs Text 3 similarity: ${sim13.toFixed(4)}`);
}

main();

using OpenAI.Embeddings;

var client = new EmbeddingClient(
    model: "text-embedding-3-small",
    apiKey: "YOUR_API_KEY",
    new OpenAIClientOptions
    {
        Endpoint = new Uri("https://api.routin.ai/v1")
    }
);

double CosineSimilarity(ReadOnlyMemory<float> a, ReadOnlyMemory<float> b)
{
    var aSpan = a.Span;
    var bSpan = b.Span;

    double dotProduct = 0, normA = 0, normB = 0;
    for (int i = 0; i < aSpan.Length; i++)
    {
        dotProduct += aSpan[i] * bSpan[i];
        normA += aSpan[i] * aSpan[i];
        normB += bSpan[i] * bSpan[i];
    }

    return dotProduct / (Math.Sqrt(normA) * Math.Sqrt(normB));
}

var texts = new[]
{
    "猫是一种可爱的宠物",
    "狗是人类最好的朋友",
    "我喜欢养小猫"
};

var response = await client.GenerateEmbeddingsAsync(texts);

var embeddings = response.Value.Select(e => e.ToFloats()).ToArray();

var sim12 = CosineSimilarity(embeddings[0], embeddings[1]);
var sim13 = CosineSimilarity(embeddings[0], embeddings[2]);

Console.WriteLine($"Text 1 vs Text 2 similarity: {sim12:F4}");
Console.WriteLine($"Text 1 vs Text 3 similarity: {sim13:F4}");

Supported Models

MeteorAI supports multiple embedding models:

OpenAI Models

text-embedding-3-small: 1536 dimensions, cost-effective, suitable for most scenarios
text-embedding-3-large: 3072 dimensions, higher accuracy, suitable for demanding scenarios
text-embedding-ada-002: 1536 dimensions, second-generation embedding model

Other Providers

Depending on your configuration, may also support:

Cohere: embed-english-v3.0, embed-multilingual-v3.0
Voyage AI: voyage-2, voyage-large-2
Jina AI: jina-embeddings-v2-base-en

Different models have varying dimensions and performance. We recommend choosing a model based on your use case and conducting comparative testing.

Use Cases

1. Semantic Search

Embed documents and store them in a vector database for semantic search.

# Example: Store document embeddings
documents = ["Document 1 content", "Document 2 content", "Document 3 content"]
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=documents
)
# Store embeddings in a vector database (e.g., Pinecone, Milvus, Qdrant)

2. Text Clustering

Group similar texts together.

from sklearn.cluster import KMeans
import numpy as np

# Get embeddings
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=texts
)
embeddings = np.array([data.embedding for data in response.data])

# K-means clustering
kmeans = KMeans(n_clusters=3)
clusters = kmeans.fit_predict(embeddings)

3. Recommendation Systems

Recommend similar content based on user preferences and content embeddings.

# User preference embedding
user_preference = client.embeddings.create(
    model="text-embedding-3-small",
    input="User's preferred content description"
).data[0].embedding

# Calculate similarity with candidate content, recommend the most similar

4. Anomaly Detection

Detect anomalous text that differs from normal data.

# Calculate average similarity of new text with normal samples
# Mark as anomaly if below threshold

Best Practices

Batch Processing: Call the API in batches whenever possible to reduce network overhead
Choose the Right Model: Select models based on accuracy requirements and budget
Cache Embeddings: Cache embeddings for unchanging text to avoid recomputation
Normalization: Ensure vectors are normalized before calculating similarity
Dimension Selection: Use the dimensions parameter to reduce dimensions and save storage and computation costs
Monitor Costs: Embeddings are billed by token, so control input text length

Error Handling

Always add error handling logic in production environments.

from openai import OpenAI, APIError, RateLimitError

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.routin.ai/v1"
)

try:
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input="测试文本"
    )
    print(response.data[0].embedding[:5])
except RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
except APIError as e:
    print(f"API error: {e}")
except Exception as e:
    print(f"Unknown error: {e}")

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.routin.ai/v1',
});

async function main() {
  try {
    const response = await client.embeddings.create({
      model: 'text-embedding-3-small',
      input: '测试文本',
    });
    console.log(response.data[0].embedding.slice(0, 5));
  } catch (error) {
    if (error instanceof OpenAI.APIError) {
      console.error(`API error [${error.status}]: ${error.message}`);
    } else {
      console.error('Unknown error:', error);
    }
  }
}

main();

using OpenAI.Embeddings;
using OpenAI;

var client = new EmbeddingClient(
    model: "text-embedding-3-small",
    apiKey: "YOUR_API_KEY",
    new OpenAIClientOptions
    {
        Endpoint = new Uri("https://api.routin.ai/v1")
    }
);

try
{
    var response = await client.GenerateEmbeddingAsync("测试文本");
    var embedding = response.Value.ToFloats();
    Console.WriteLine(string.Join(", ", embedding.Take(5)));
}
catch (ClientResultException ex)
{
    Console.WriteLine($"API error [{ex.Status}]: {ex.Message}");
}
catch (Exception ex)
{
    Console.WriteLine($"Unknown error: {ex.Message}");
}

Common Error Codes

Error Code	Description	Solution
401	Invalid API Key	Check Authorization header
429	Rate limit exceeded	Reduce request frequency
400	Invalid request parameters	Check input and model parameters
500	Server error	Retry later

More Resources

Chat Completions API - Chat interface
Images API - Image generation interface
Audio API - Speech recognition and synthesis interface

Embeddings API

On this page