Skip to main content
The OpenAI embeddings API accepts an optional dimensions parameter to truncate the returned vector. Aurous Labs accepts the parameter on the wire and validates it against each model’s supported set (publishing 400 embeddings_unsupported_dimensions for out-of-set values), but on v1.0 the parameter is validated only — the upstream model is dispatched without it, and the response vector is always the model’s native dimension. True truncation will land in a future model version. Plan around the native dimension for now; we publish the supported set on each model row so your client can adapt without a redeploy when truncation ships.

​
Check which dimensions a model supports

Call GET /v1/models and read aurous_metadata.dimensions for the model row. The field is an array of supported integers (e.g. [1024, 2048]) or null when the model returns a fixed shape with no truncation support. 
// excerpt from GET /v1/models for an embedding model
{
  "id": "aurous-embed-vision-1.0",
  "object": "model",
  "kind": "embedding",
  "aurous_metadata": {
    "context_window": 128000,
    "dimensions": [1024, 2048],     // ← supported output dimensions
    "max_input_items": 100,
    "capabilities": ["multimodal_input"]
  }
}
When aurous_metadata.dimensions is null, do not send the dimensions parameter — the response vector will be the model’s native dimension. When the array is populated, you may send dimensions set to one of those values. On v1.0 the request will succeed (the value passes the whitelist gate) but the response vector will still be the model’s native dimension — the parameter is reserved for the upcoming truncation rollout. Check data[0].embedding.length after the first successful call to see the actual shape. Picking a value NOT in the supported list returns 400 embeddings_unsupported_dimensions.

​
Why lower dimensions can be useful

When a model supports multiple dimensions, the tradeoff is storage cost vs retrieval quality:
  • Lower dimensions — smaller vectors. Cheaper to store at index scale, faster cosine similarity (every comparison touches fewer floats), and a smaller transfer footprint between your service and your vector database. Slight recall loss vs the native dimension — usually a few percent on a clean evaluation set, sometimes negligible in practice.
  • Higher dimensions — richer semantic representation, best recall. The native dimension is what the model was trained to output, so it’s the default for accuracy-sensitive workloads.
The platform doesn’t take a position on which to choose — that’s a benchmark call against your own data. The recommendation is to start with the model’s native dimension and only truncate after measuring the recall delta on your evaluation set. The day-1 embedding model returns its native dimension whether or not you pass dimensions. Omit the parameter and read the shape off the response: 
curl -X POST https://api.aurous-labs.com/v1/embeddings \
  -H "Authorization: Bearer $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aurous-embed-vision-1.0",
    "input": "The quick brown fox jumps over the lazy dog."
  }'

​
Example 2 — what happens when you pass an unsupported value

Sending dimensions: 512 to aurous-embed-vision-1.0 (whose supported set is [1024, 2048]): 
curl -X POST https://api.aurous-labs.com/v1/embeddings \
  -H "Authorization: Bearer $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aurous-embed-vision-1.0",
    "input": "Hello world.",
    "dimensions": 512
  }'

HTTP/1.1 400 Bad Request
Aurous-Request-Id: req_01HXMQ7Z3K8Y2ABCDEFGHJKM
Content-Type: application/json

{
  "error": {
    "type": "invalid_request",
    "code": "embeddings_unsupported_dimensions",
    "message": "Model aurous-embed-vision-1.0 only accepts 1024, 2048 for dimensions; received 512.",
    "doc_url": "https://docs.aurous-labs.com/errors#embeddings_unsupported_dimensions",
    "request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKM"
  }
}
No credits are charged for a request rejected at the DTO boundary — the 400 happens before the model is called, so there’s nothing to refund. Fix the request and retry.

​
Forward compatibility

aurous_metadata.dimensions is the source of truth. When a future model with a different supported set ships, its row will list the supported values and the validator picks them up automatically. The error code stays the same; only the supported set changes. Read the metadata at request time (or cache it with a short TTL) so your client adapts without a redeploy.
  • Overview — embeddings surface and quick start.
  • Multimodal — text + image + video parts in one request.
  • Pricing — credit math and worked examples.
  • Estimate — preview cost without charging.