Lunos

Documentation

🧬 Embeddings

The Embedding API generates vector representations of text for use in semantic search, similarity, clustering, and recommendation systems. It supports multiple models and output formats for maximum flexibility.

Note: You need an API key to use this endpoint. See the Quickstart Guide to get started.

How to Generate Embeddings (Step-by-Step)

  1. Choose your preferred client library or use cURL for direct API calls.
  2. Set your API key and endpoint URL.
  3. Configure the request parameters (input, model, response_format, etc.).
  4. Send the request and use the returned vector(s) in your application.

Example: Using OpenAI Library

Generate an embedding using the OpenAI Node.js library:

1const response = await openai.embeddings.create({
2  model: 'text-embedding-3-small',
3  input: 'Hello, world!',
4});
5console.log(response.data[0].embedding);
Parameters:
  • model: The embedding model to use (e.g., text-embedding-3-small).
  • input: The text or array of texts to embed.

Example: Using Lunos Client

Generate an embedding using the official Lunos client:

1const client = new LunosClient({ apiKey: 'YOUR_API_KEY' });
2const response = await client.embedding.embed({
3  input: 'Hello, world!',
4  model: 'openai/text-embedding-3-small',
5  response_format: 'float',
6  appId: 'my-embedding-service-v1.0',
7});
8console.log(response.data[0].embedding);
Parameters:
  • input: The text(s) to embed.
  • model: Model ID (e.g., openai/text-embedding-3-small).
  • response_format: Output format (float or base64).

Example: Using cURL

Direct API call for embedding generation:

1curl -X POST   https://api.lunos.tech/v1/embeddings   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -H "X-App-ID: my-embedding-service-v1.0"   -d '{
2    "model": "openai/text-embedding-3-small",
3    "input": "Hello, world!",
4    "response_format": "float"
5  }'

App Tracking: The X-App-ID header allows you to track embedding generation usage per application. This helps with analytics, billing, and performance monitoring across different apps.

Example Response

1{
2  "object": "list",
3  "data": [
4    {
5      "object": "embedding",
6      "embedding": [0.1, 0.2, 0.3, ...],
7      "index": 0
8    }
9  ],
10  "model": "text-embedding-3-small",
11  "usage": {
12    "prompt_tokens": 10,
13    "total_tokens": 10
14  }
15}

Important: Your API key is sensitive. Never share it publicly or commit it to version control.

Best Practices & Tips

  • Use response_format: 'base64' for compact, portable output.
  • Batch multiple texts in a single request for efficiency.
  • Choose the right model for your use case (see Model Discovery).

Troubleshooting

  • Authentication error: Verify your API key and permissions.
  • Unexpected output: Check your model and input parameters.
  • Request issues: Ensure your request payload matches the API specification.