Embeddings

POST /v1/embeddings generates a vector embedding for input text. Use it for search, clustering, classification, and RAG.

Request

Body

Field	Type	Required	Description
`model`	`string`	Yes	Embedding model slug (e.g. `text-embedding-3-small`).
`input`	`string \| string[]`	Yes	Text to embed. Single string or batch.
`dimensions`	`integer`	No	Output dimensionality (for models that support it).
`encoding_format`	`"float" \| "base64"`	No	Default `"float"`.
`user`	`string`	No	End-user identifier.

Response

{
  object: "list";
  data: Array<{
    object: "embedding";
    index: number;
    embedding: number[];       // length matches `dimensions`
  }>;
  model: string;
  usage: {
    prompt_tokens: number;
    total_tokens: number;
  };
}

Example

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="The quick brown fox jumps over the lazy dog.",
)

vector = response.data[0].embedding
# len(vector) == 1536

Batching

Pass an array to embed multiple inputs in one request:

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["doc one", "doc two", "doc three"],
)

# response.data[0].embedding  # vector for "doc one"
# response.data[1].embedding  # vector for "doc two"
# response.data[2].embedding  # vector for "doc three"

Batching is faster and cheaper than separate requests for the same total token count. Up to 2048 inputs per request.

Choosing a dimension

text-embedding-3-small and text-embedding-3-large support adjustable dimensions via the dimensions parameter. Shorter vectors save storage and speed up retrieval at a small quality cost:

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="compress me",
    dimensions=256,   # default 1536
)