#openai api

text-embedding-3-small Dimensions Explained: 1536 vs 1024 vs 512

If you use text-embedding-3-small, one small setting can quietly affect your whole retrieval system: embedding dimensions.

The default vector length is 1536 dimensions. That is a good default. But it is not always the cheapest or fastest choice once you store millions of chunks in a vector database.

This guide explains what text-embedding-3-small dimensions means, when to keep 1536, when to test smaller vectors, and how to call an OpenAI-compatible embeddings endpoint with real code.

What are text-embedding-3-small dimensions?

An embedding turns text into a list of numbers. That list is a vector.

For text-embedding-3-small, the default vector has 1536 numbers. If you embed the sentence:

“API gateways help developers route model calls.”

The model returns one vector that represents the meaning of that whole input. The vector is not one number per word. It is one semantic representation for the input text you send.

You then store that vector in a vector database such as pgvector, Pinecone, Milvus, Weaviate, Chroma, or Qdrant. When a user searches, you embed the query and compare it against stored vectors.

Official OpenAI documentation states that text-embedding-3-small defaults to 1536 dimensions, while text-embedding-3-large defaults to 3072 dimensions. It also supports a dimensions parameter that can reduce the output vector length.

External references:

OpenAI embeddings guide

OpenAI text-embedding-3-small model page

Stack Overflow discussion on embedding dimensions

Default text-embedding-3-small dimensions: why 1536 is common

1536 dimensions is popular because it is the default. It is also a practical balance between quality and cost for many semantic search and RAG workloads.

Use the default 1536 dimensions when:

You are building your first retrieval system.

You do not have evaluation data yet.

Your dataset is small enough that vector storage is not painful.

Search quality matters more than a few gigabytes of storage.

You want fewer moving parts during the first launch.

That last point matters. If your app is still early, the biggest risk is usually not vector size. It is bad chunking, weak retrieval evaluation, missing metadata filters, or poor prompts.

Start simple. Then optimize.

The dimensions parameter: what changes and what does not

The dimensions parameter lets you request a shorter embedding vector.

For example, instead of asking for the default 1536-dimensional vector, you can request 1024, 768, or 512 dimensions if your provider supports it for that model.

What changes:

Area1536 dimensions1024 / 768 / 512 dimensionsVector storageLargerSmallerIndex memoryLargerSmallerSearch latencyOften higherOften lowerRetrieval qualityStrong baselineMust be testedAPI input token costUsually unchangedUsually unchanged

What does not usually change: the number of input tokens you send. Embedding API pricing is normally based on input tokens, not the final vector size.

That means smaller dimensions mainly help with storage, index memory, and retrieval speed. They are not a magic way to reduce the embedding generation bill.

Storage math: 1536 vs 1024 vs 512 dimensions

A float32 number uses 4 bytes. So the raw vector size is:

vector_size_bytes = dimensions × 4

For one vector:

DimensionsBytes per vectorStorage vs 153615366,144 bytesBaseline10244,096 bytes~33% smaller7683,072 bytes~50% smaller5122,048 bytes~67% smaller

For 1 million chunks, raw float32 vector storage looks like this:

DimensionsRaw vector storageWith rough 35% index overhead1536~5.72 GiB~7.72 GiB1024~3.81 GiB~5.15 GiB768~2.86 GiB~3.86 GiB512~1.91 GiB~2.57 GiB

This is why dimensions start to matter at scale. A small difference per vector becomes real infrastructure cost when you store millions of chunks.

Quick calculator for embedding dimensions

Here is a small Python tool you can use to estimate storage and rough generation cost.

#!/usr/bin/env python3 import argparse def gib(n): return n / (1024 ** 3) def main(): parser = argparse.ArgumentParser() parser.add_argument("--documents", type=int, required=True) parser.add_argument("--avg-tokens", type=int, required=True) parser.add_argument("--dimensions", type=int, nargs="+", default=[1536, 1024, 768, 512]) parser.add_argument("--price-per-million", type=float, default=0.02) args = parser.parse_args() total_tokens = args.documents * args.avg_tokens estimated_cost = total_tokens / 1_000_000 * args.price_per_million print(f"Documents: {args.documents:,}") print(f"Estimated input tokens: {total_tokens:,}") print(f"Embedding generation cost: ${estimated_cost:,.2f}") print() print("Dims Raw GiB With 35% index overhead") for dim in args.dimensions:

AI API 调用报“模型不可用”？先别急着换模型，可能是 /chat/completions、/responses、/messages 用错了

很多人在配置 AI 工具、中转 API、OpenAI 兼容接口的时候，会碰到一个很烦的问题：

model unavailable unsupported endpoint invalid request body not found schema mismatch

看起来像是模型不能用，或者服务挂了。

但实际排查下来，经常不是模型问题，而是接口端点和请求格式没对上。

尤其是下面这三个 endpoint，非常容易被混用：

/v1/chat/completions /v1/responses /v1/messages

它们名字都像“聊天接口”，但其实分别对应不同的 API 体系。

如果你把 A 体系的请求体发到 B 体系的 endpoint，就算模型真实存在，也可能报“模型不可用”。

这篇文章不讲太多概念，直接按排错思路讲：什么时候该用哪个端点，以及怎么判断自己填错了。

---

一句话判断

先给最重要的结论：

OpenAI 兼容工具：用 /v1/chat/completions OpenAI Responses API：用 /v1/responses Anthropic / Claude 原生工具：用 /v1/messages

如果你用的是普通 AI 客户端，比如各种聊天 UI、Cursor 类工具、FastGPT、LiteLLM、OpenAI SDK 兼容模式，一般优先考虑：

/v1/chat/completions

如果文档明确写了 Responses API，再考虑：

/v1/responses

如果工具明确是 Claude / Anthropic 原生 SDK，再考虑：

/v1/messages

---

为什么明明模型存在，却会提示不可用？

因为一次 API 请求不是只有模型名。

它至少包含三部分：

1. 模型名 2. endpoint 3. 请求体 schema

这三个必须匹配。

举个例子：

你选了一个 Claude 模型，但你的工具是 OpenAI-compatible 客户端。这个时候它可能应该走：

/v1/chat/completions

而不是：

/v1/messages

反过来，如果你的工具是 Anthropic 原生 SDK，代码里写的是 Claude Messages API 格式，那你把 endpoint 改成 /v1/chat/completions 也可能失败。

所以不要只看模型名。

更准确的判断方式是：

客户端类型 + endpoint + 请求格式

这三个要一致。

---

第一类：/v1/chat/completions

这是最常见的 OpenAI 兼容聊天接口。

典型请求格式：

{ "model": "gpt-5.5", "messages": [ { "role": "user", "content": "帮我解释一下 API endpoint 的区别" } ] }

完整 curl 示例：

curl https://crazyrouter.com/v1/chat/completions \ -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.5",

/v1/chat/completions vs /v1/responses vs /v1/messages: Какой endpoint AI API выбрать?

Распространённая проблема в AI API шлюзах — это не API ключ, не модель и не SDK. Это endpoint.

Пользователь выбирает существующую модель, но отправляет запрос на неправильный endpoint. В результате:

модель недоступна;

endpoint не поддерживается;

неверное тело запроса;

tool calling не работает;

несовпадение формата streaming;

Claude модель работает в одном инструменте, но падает в другом.

Это руководство объясняет различия между тремя семействами endpoint:

/v1/chat/completions /v1/responses /v1/messages

Краткая версия:

EndpointРодная экосистемаЛучше всего дляСтиль запроса/v1/chat/completionsOpenAI-совместимый legacy/текущий chatБольшинство приложений, SDKs, LiteLLM, Cursor-style инструменты, простой chatmessages: [{role, content}]/v1/responsesНовый OpenAI Responses APITool use, multimodal, reasoning items, новые OpenAI-style агентыinput, tools, structured response items/v1/messagesAnthropic Claude APIClaude-native SDKs и Claude-style приложенияmessages плюс top-level system, Anthropic schema

Если ваш клиент говорит "OpenAI-compatible", начните с:

https://crazyrouter.com/v1/chat/completions

или установите base URL на:

https://crazyrouter.com/v1

и позвольте SDK добавить /chat/completions.

Если ваш инструмент специально требует OpenAI Responses API, используйте /v1/responses.

Если ваш инструмент использует Anthropic-native SDK и ожидает Claude Messages API, используйте /v1/messages.

Самая распространённая ошибка

Самая распространённая ошибка — смешивание семейства моделей и семейства endpoint.

Например, Claude модель может быть доступна через OpenAI-совместимый шлюз, но это не означает автоматически, что тело вашего запроса должно использовать Anthropic-native /v1/messages schema.

Аналогично, инструмент, который отправляет Anthropic-native запросы на /v1/messages, не может быть исправлен только изменением имени модели. Endpoint и тело запроса должны совпадать.

Думайте об этом так:

имя модели + endpoint + schema запроса должны совпадать

Если один из трёх неправильный, модель может выглядеть недоступной, даже если сама модель работает нормально.

Что такое /v1/chat/completions

/v1/chat/completions — это классический OpenAI-совместимый chat endpoint.

Типичный запрос выглядит так:

curl https://crazyrouter.com/v1/chat/completions \ -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.5", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Explain API endpoints in one paragraph."} ] }'

Используйте /v1/chat/completions когда:

приложение говорит, что поддерживает OpenAI-совместимый API;

конфиг запрашивает OPENAI_BASE_URL или base_url;

тело запроса использует messages с role и content;

вы используете режим совместимости обычного OpenAI SDK;

вы настраиваете инструменты типа Cursor-style клиентов, LiteLLM-style роутеров, FastGPT-style приложений или многих chat UI.

Для большинства пользователей это самый безопасный endpoint по умолчанию.

Что такое /v1/responses

/v1/responses — это новый OpenAI Responses API endpoint.

Он разработан вокруг более общего объекта response и может представлять:

текстовый вывод;

tool calls;

multimodal ввод;

reasoning items;

structured output;

agent-подобные workflows.

Упрощённый запрос выглядит так:

curl https://crazyrouter.com/v1/responses \ -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.5", "input": "Explain the difference between chat completions and responses." }'

Используйте /v1/responses когда:

инструмент явно говорит, что использует OpenAI Responses API;

/v1/chat/completions vs /v1/responses vs /v1/messages: どのAI APIエンドポイントを使うべき？

AI APIゲートウェイにおける一般的なサポート問題は、APIキーでもなく、モデルでもなく、SDKでもありません。エンドポイントです。

ユーザーが存在するモデルを選択しても、リクエストを間違ったエンドポイントに送信してしまいます。結果は次のようになります：

モデル利用不可；

サポートされていないエンドポイント；

無効なリクエストボディ；

ツール呼び出しが機能しない；

ストリーミング形式の不一致；

Claudeモデルはあるツールでは動作するが別のツールでは失敗。

このガイドでは、3つのエンドポイントファミリーの違いを説明します：

/v1/chat/completions /v1/responses /v1/messages

簡易版：

エンドポイントネイティブエコシステム最適な用途リクエストスタイル/v1/chat/completionsOpenAI互換のレガシー/現在のチャットほとんどのアプリ、SDK、LiteLLM、Cursorスタイルツール、シンプルなチャットmessages: [{role, content}]/v1/responsesより新しいOpenAI Responses APIツール使用、マルチモーダル、推論アイテム、より新しいOpenAIスタイルのエージェントinput、tools、構造化応答アイテム/v1/messagesAnthropic Claude APIClaude ネイティブSDKとClaudeスタイルのアプリmessagesとトップレベルのsystem、Anthropicスキーマ

クライアントが「OpenAI互換」と言う場合は、以下から始めてください：

https://crazyrouter.com/v1/chat/completions

またはベースURLを次のように設定：

https://crazyrouter.com/v1

SDKが/chat/completionsを追加します。

ツールが特にOpenAI Responses APIを必要とする場合は、/v1/responsesを使用します。

ツールがAnthropicネイティブでClaudeのMessages APIを期待する場合は、/v1/messagesを使用します。

最も一般的な間違い

最も一般的な間違いは、モデルファミリーとエンドポイントファミリーを混ぜることです。

例えば、ClaudeモデルはOpenAI互換ゲートウェイを通じて公開できますが、それはリクエストボディがAnthropicネイティブの/v1/messagesスキーマを使用すべきということを自動的に意味しません。

同様に、Anthropicネイティブのリクエストを/v1/messagesに送信するツールは、モデル名を変更するだけでは修正できません。エンドポイントとリクエストボディが一致する必要があります。

このように考えてください：

モデル名 + エンドポイント + リクエストスキーマが一致する必要があります

この3つのうち1つが間違っていると、モデル自体が正常に動作していてもモデルが利用不可に見える場合があります。

/v1/chat/completionsとは

/v1/chat/completionsは古典的なOpenAI互換チャットエンドポイントです。

典型的なリクエストは次のようになります：

curl https://crazyrouter.com/v1/chat/completions \ -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.5", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Explain API endpoints in one paragraph."} ] }'

以下の場合に/v1/chat/completionsを使用してください：

アプリがOpenAI互換APIをサポートしていると述べている；

設定がOPENAI_BASE_URLまたはbase_urlを要求している；

リクエストボディがroleとcontentを持つmessagesを使用している；

一般的なOpenAI SDK互換モードを使用している；

Cursorスタイルクライアント、LiteLLMスタイルルーター、FastGPTスタイルアプリ、または多くのチャットUIなどのツールを設定している。

多くのユーザーにとって、これが最も安全なデフォルトエンドポイントです。

/v1/responsesとは

/v1/responsesはより新しいOpenAI Responses APIエンドポイントです。

より一般的な応答オブジェクトの周りに設計されており、以下のようなものを表現できます：

テキスト出力；

ツール呼び出し；

マルチモーダル入力；

推論アイテム；

構造化出力；

エージェントのようなワークフロー。

簡略化されたリクエストは次のようになります：

curl https://crazyrouter.com/v1/responses \ -H "Authorization: Bearer $CRAZYROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.5", "input": "Explain the difference between chat completions and responses." }'

以下の場合に/v1/responsesを使用してください：

ツールがOpenAI Responses APIを使用していると明示的に述べている；