Python 88.3%
TypeScript 7.6%
Shell 4.1%
1# OpenAI Embeddings API (`POST /v1/embeddings`)23**Status:** DOCUMENTED + LIVE_VERIFIED (all three models, `dimensions`, `encoding_format=base64`, token-array input, error shapes).4**Sources:** [Embeddings reference](https://developers.openai.com/api/reference/resources/embeddings) · [Vector embeddings guide](https://developers.openai.com/api/docs/guides/embeddings) · [Pricing](https://developers.openai.com/api/docs/pricing) · model pages `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002` · OpenAPI `CreateEmbeddingRequest` / `CreateEmbeddingResponse`.5**Last verified:** 2026-09-18.6**Machine-readable:** endpoints fragment, `parameters/openai-embeddings.json`, `objects/openai-media-objects.json`, `prices/openai-media.json`.78## Model matrix910| Model | Native dims | `dimensions` param | Max input tokens | Price (per 1M input tokens) | ~Pages / $ | MTEB | Knowledge | Batch | Live (input `"OK"`) |11|---|---|---|---|---|---|---|---|---|---|12| `text-embedding-3-small` | **1536** | ✓ (1…1536) | 8 192 | **$0.02** | 62 500 | 62.3 % | ≤ Sep 2021 | ✓ | 200 · 1536 floats · `prompt_tokens: 1` · ‖v‖₂ = 1.0001 |13| `text-embedding-3-large` | **3072** | ✓ (1…3072) | 8 192 | **$0.13** | 9 615 | 64.6 % | ≤ Sep 2021 | ✓ | 200 · 3072 floats · ‖v‖₂ = 0.9998 |14| `text-embedding-ada-002` | 1536 | ✗ (400) | 8 192 | $0.10 | 12 500 | 61.0 % | — | ✓ | 200 · 1536 floats · response `model: "text-embedding-ada-002-v2"` · ‖v‖₂ = 1.0000 |1516Standard-tier prices; Batch tier prices for embeddings are not broken out on the pricing page (Batch supported per model pages). Regional endpoints: `/v1/embeddings` available in all regions; UAE lists `text-embedding-3-large` specifically. Observed header on our key: `x-ratelimit-limit-requests: 10000` (account-specific, not a documented limit).1718## Request1920| Param | Type | Required | Default | Notes |21|---|---|---|---|---|22| `input` | `string` \| `string[]` \| `int[]` \| `int[][]` | ✓ | — | non-empty; ≤ 8 192 tokens **per input**; arrays 1–2 048 items; ≤ **300 000 tokens summed per request**; tokenizer `cl100k_base` (tiktoken) |23| `model` | string | ✓ | — | see matrix |24| `dimensions` | int | — | native | text-embedding-3-* only (Matryoshka); API returns re-normalized vectors |25| `encoding_format` | `float` \| `base64` | — | `float` | base64 = raw little-endian float32 bytes (4 × dims), smaller/faster to parse |26| `user` | string | — | — | end-user id for abuse monitoring |2728Live probes: `dimensions: 16` + `base64` on 3-small → `embedding` = 88 base64 chars = 64 bytes = 16 float32, L2 norm 1.0003; `dimensions` on ada-002 → `400 invalid_request_error "This model does not support specifying dimensions."` (`param: null`, plus a non-standard top-level `detail` object); `input: [[11380]]` (token array) → 200, `prompt_tokens: 1`.2930## Response3132```json33{"object":"list","model":"text-embedding-3-small",34 "data":[{"object":"embedding","index":0,"embedding":[/* 1536 floats or a base64 string */]}],35 "usage":{"prompt_tokens":1,"total_tokens":1}}36```37`data[i].index` matches the position in the `input` array. Billing = `usage.total_tokens` × price.3839## Normalization, distance, dimensions4041- OpenAI embeddings are **unit-length (L2 = 1)** — cosine similarity = dot product; cosine and Euclidean rankings are identical (guide FAQ; confirmed live to ±3e-4).42- Prefer the `dimensions` parameter over manual truncation. If you truncate client-side, **re-normalize** (guide shows `normalize_l2`). `text-embedding-3-large` cut to 256 dims still beats full ada-002 on MTEB (guide).43- Use cases in the guide: search, clustering, recommendations, anomaly detection, classification, zero-shot classification, 2-D t-SNE visualisation, features for regression/classification, cold-start recommendations, code search.4445## Batching and limits4647- Up to 2 048 inputs per call and 300 k tokens total; count tokens first with tiktoken (`cl100k_base`).48- For large offline jobs use the Batch API (`/v1/embeddings` supported by all three models) — 24 h window, discounted tier.49- Empty strings are rejected; token arrays let you pre-tokenize and control truncation yourself.5051## Examples and tests5253`examples/openai/embeddings/` — `create.sh|py|ts` (LIVE_VERIFIED; the `.py` also shows `dimensions` + base64 decoding). `tests/openai/test_embeddings.py` (cheap, always runs).54