> ## Documentation Index > Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt > Use this file to discover all available pages before exploring further. # Output Dimensions > When the `dimensions` parameter is supported, when it's rejected, and the storage vs recall tradeoff. 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`](/api-reference/openapi#tag/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. ```jsonc theme={null} // 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. ## Example 1 — recommended call for `aurous-embed-vision-1.0` (no `dimensions`) 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: ```bash cURL theme={null} 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." }' ``` ```typescript Node.js (OpenAI SDK) theme={null} import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.aurous-labs.com/v1", apiKey: process.env.AUROUS_API_KEY!, }); const res = await client.embeddings.create({ model: "aurous-embed-vision-1.0", input: "The quick brown fox jumps over the lazy dog.", }); console.log("native dim:", res.data[0].embedding.length); ``` ```python Python (OpenAI SDK) theme={null} from openai import OpenAI client = OpenAI( base_url="https://api.aurous-labs.com/v1", api_key="al_live_xxxxxxxxxxxxxxxx", ) res = client.embeddings.create( model="aurous-embed-vision-1.0", input="The quick brown fox jumps over the lazy dog.", ) print("native dim:", len(res.data[0].embedding)) ``` ## 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]`): ```bash theme={null} 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 theme={null} 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. ## Related * [Overview](/api-reference/embeddings/overview) — embeddings surface and quick start. * [Multimodal](/api-reference/embeddings/multimodal) — text + image + video parts in one request. * [Pricing](/api-reference/embeddings/pricing) — credit math and worked examples. * [Estimate](/api-reference/embeddings/estimate) — preview cost without charging.