Skip to main content

​
Endpoint

POST /v1/embeddings
Creates an embedding vector representing the input text.

​
Request

​
Headers

​
Content-Type
string
required
Must be application/json
​
x-portkey-provider
string
required
The AI provider to use (e.g., openai, cohere, google)
​
x-portkey-api-key
string
required
Your API key for the specified provider

​
Body Parameters

​
model
string
required
The embedding model to use (e.g., text-embedding-3-small, text-embedding-ada-002)
​
input
string | array
required
The text or array of texts to generate embeddings for
​
encoding_format
string
default:"float"
Format of the embeddings: float or base64
​
dimensions
integer
Number of dimensions for the embedding (only supported by some models)
​
user
string
Unique identifier for the end-user

​
Response

​
object
string
Object type, always list
​
model
string
The model used for embeddings
​
data
array
Array of embedding objects
​
object
string
Object type, always embedding
​
embedding
array
The embedding vector (array of floats)
​
index
integer
Index of the embedding in the input array
​
usage
object
Token usage information
​
prompt_tokens
integer
Number of tokens in the input
​
total_tokens
integer
Total tokens used

​
Examples

​
Basic Embedding Request

curl http://localhost:8787/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "x-portkey-provider: openai" \
  -H "x-portkey-api-key: sk-..." \
  -d '{
    "model": "text-embedding-3-small",
    "input": "The quick brown fox jumps over the lazy dog"
  }'

​
Response

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

​
Python SDK

from portkey_ai import Portkey

client = Portkey(
    provider="openai",
    Authorization="sk-..."
)

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"Embedding dimensions: {len(embedding)}")
print(f"First 5 values: {embedding[:5]}")

​
JavaScript SDK

import Portkey from 'portkey-ai';

const client = new Portkey({
  provider: 'openai',
  Authorization: 'sk-...'
});

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'The quick brown fox jumps over the lazy dog'
});

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

​
Batch Embeddings

curl http://localhost:8787/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "x-portkey-provider: openai" \
  -H "x-portkey-api-key: sk-..." \
  -d '{
    "model": "text-embedding-3-small",
    "input": [
      "First document to embed",
      "Second document to embed",
      "Third document to embed"
    ]
  }'

​
Python Batch Example

from portkey_ai import Portkey

client = Portkey(
    provider="openai",
    Authorization="sk-..."
)

texts = [
    "First document to embed",
    "Second document to embed",
    "Third document to embed"
]

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

for i, embedding_obj in enumerate(response.data):
    print(f"Document {i+1}: {len(embedding_obj.embedding)} dimensions")

​
Using Cohere

curl http://localhost:8787/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "x-portkey-provider: cohere" \
  -H "x-portkey-api-key: your-cohere-api-key" \
  -d '{
    "model": "embed-english-v3.0",
    "input": "Embed this text"
  }'

​
Custom Dimensions

from portkey_ai import Portkey

client = Portkey(
    provider="openai",
    Authorization="sk-..."
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Embed this text",
    dimensions=512  # Reduce from default 1536 to 512
)

print(f"Dimensions: {len(response.data[0].embedding)}")

​
Similarity Search Example

import numpy as np
from portkey_ai import Portkey

client = Portkey(
    provider="openai",
    Authorization="sk-..."
)

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

# Create embeddings
documents = [
    "The cat sat on the mat",
    "The dog played in the park",
    "A feline rested on a rug"
]

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

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

# Compare similarity
similarity = cosine_similarity(embeddings[0], embeddings[2])
print(f"Similarity between doc 1 and 3: {similarity:.4f}")

​
Supported Models

​
OpenAI

  • text-embedding-3-small - 1536 dimensions (default)
  • text-embedding-3-large - 3072 dimensions
  • text-embedding-ada-002 - 1536 dimensions (legacy)

​
Cohere

  • embed-english-v3.0 - English embeddings
  • embed-multilingual-v3.0 - Multilingual embeddings
  • embed-english-light-v3.0 - Lightweight English

​
Google

  • text-embedding-004 - Google’s text embeddings
  • text-multilingual-embedding-002 - Multilingual

​
Use Cases

  • Semantic Search: Find similar documents or passages
  • Clustering: Group similar texts together
  • Recommendations: Recommend similar content
  • Classification: Use embeddings as features for ML models
  • Anomaly Detection: Identify outliers in text data

Build docs developers (and LLMs) love

Get started for freeTalk to us