API Reference
Embeddings
POST /v1/embeddings — create vector embeddings for text
Embeddings
POST /v1/embeddings
Create a vector representation of text. Use embeddings for semantic search, clustering, classification, and retrieval-augmented generation (RAG).
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Embedding model ID, e.g. text-embedding-3-small |
input | string or array | Yes | Text(s) to embed. Max 8,192 tokens per string for most models |
encoding_format | string | No | float (default) or base64 |
dimensions | integer | No | Number of output dimensions (supported by text-embedding-3-*) |
Example Request
curl https://api.soxai.io/v1/embeddings \
-H "Authorization: Bearer $SOXAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-3-small",
"input": [
"SoxAI is an enterprise AI gateway.",
"A unified interface for multiple AI providers."
]
}'Example Response
{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.0023, -0.0115, 0.0098, ...]
},
{
"object": "embedding",
"index": 1,
"embedding": [0.0019, -0.0087, 0.0102, ...]
}
],
"model": "text-embedding-3-small",
"usage": {
"prompt_tokens": 16,
"total_tokens": 16
}
}Supported Models
| Model | Dimensions | Max Input Tokens | Notes |
|---|---|---|---|
text-embedding-3-small | 1536 (default) | 8,192 | Best cost/performance ratio |
text-embedding-3-large | 3072 (default) | 8,192 | Highest quality |
text-embedding-ada-002 | 1536 | 8,192 | Legacy, still widely used |
Reducing Dimensions
For text-embedding-3-* models, you can request fewer dimensions to reduce storage and compute costs:
{
"model": "text-embedding-3-large",
"input": "Hello, world!",
"dimensions": 256
}This uses Matryoshka Representation Learning — the shortened vector retains most of the semantic information.
Batch Embedding
Pass an array to embed multiple texts in one request (more efficient than individual calls):
texts = ["doc1 content", "doc2 content", "doc3 content"]
response = client.embeddings.create(
model="text-embedding-3-small",
input=texts,
)
vectors = [item.embedding for item in response.data]