Embeddings

The Embeddings API converts text into high-dimensional vector representations. These vectors capture semantic meaning and are essential for semantic search, clustering, recommendation systems, and RAG applications.

Endpoint Info

Item	Value
URL	/v1/embeddings
Method	POST
Auth	Bearer Token (API Key)
Content-Type	application/json

Request Parameters

Parameter	Type	Required	Description
model	string	Yes	Embedding model ID
input	string / array	Yes	Text or array of texts to embed
encoding_format	string	No	Output format: float (default) or base64
dimensions	integer	No	Number of dimensions for output embeddings (text-embedding-3 models only)

Available Models

Model	Dimensions	Max Input Tokens	Description
text-embedding-3-small	1536	8191	Fast, cost-effective embeddings
text-embedding-3-large	3072	8191	Highest quality embeddings
text-embedding-ada-002	1536	8191	Legacy model, still supported

cURL Examples

Single Text

curl https://api.quickapi.store/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "The quick brown fox jumps over the lazy dog"
  }'

Batch Texts

curl https://api.quickapi.store/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "text-embedding-3-small",
    "input": [
      "Machine learning is fascinating",
      "The weather is beautiful today",
      "Python is a versatile programming language",
      "Quantum computing will revolutionize technology"
    ]
  }'

With Custom Dimensions

curl https://api.quickapi.store/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "text-embedding-3-large",
    "input": "Reduce dimensions for faster similarity search",
    "dimensions": 256
  }'

Base64 Encoding Format

curl https://api.quickapi.store/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Return embeddings in base64 format",
    "encoding_format": "base64"
  }'

💡 Batch Processing

Always batch multiple texts in a single request when possible. It's more cost-effective and reduces latency compared to sending individual requests.

Response Example

Single Text Response

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

Batch Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023064255, -0.009327292, "..."]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [-0.00451234, 0.00892341, "..."]
    },
    {
      "object": "embedding",
      "index": 2,
      "embedding": [0.00672341, -0.00234123, "..."]
    },
    {
      "object": "embedding",
      "index": 3,
      "embedding": [-0.00123456, 0.00567890, "..."]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 28,
    "total_tokens": 28
  }
}

Python Example

from openai import OpenAI
import numpy as np

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

# Single text embedding
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="The quick brown fox jumps over the lazy dog"
)
embedding = response.data[0].embedding
print(f"Dimensions: {len(embedding)}")
print(f"First 5 values: {embedding[:5]}")

# Batch embeddings
texts = [
    "Machine learning is fascinating",
    "The weather is beautiful today",
    "Python is a versatile programming language",
    "Quantum computing will revolutionize technology"
]
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=texts
)
for i, data in enumerate(response.data):
    print(f"Text {i}: {len(data.embedding)} dimensions")

# With custom dimensions
response = client.embeddings.create(
    model="text-embedding-3-large",
    input="Reduce dimensions for faster similarity search",
    dimensions=256
)
print(f"Custom dimensions: {len(response.data[0].embedding)}")

# Cosine similarity example
def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

resp1 = client.embeddings.create(
    model="text-embedding-3-small",
    input="Machine learning"
)
resp2 = client.embeddings.create(
    model="text-embedding-3-small",
    input="Artificial intelligence"
)
resp3 = client.embeddings.create(
    model="text-embedding-3-small",
    input="Pizza recipe"
)

sim_12 = cosine_similarity(resp1.data[0].embedding, resp2.data[0].embedding)
sim_13 = cosine_similarity(resp1.data[0].embedding, resp3.data[0].embedding)
print(f"ML vs AI similarity: {sim_12:.4f}")
print(f"ML vs Pizza similarity: {sim_13:.4f}")

⚠️ Dimension Reduction

When using the dimensions parameter, reducing dimensions too aggressively may degrade embedding quality. Test your downstream task performance to find the optimal balance between speed and accuracy.