Create embeddings with the Grok API

POST https://api.x.ai/v1/embeddings returns vector representations of text. Docs examples use model id v1. Embedding models share the same spend-tier RPS/TPM system as text models — see Handle Grok API rate limits.

For retrieval quality, prepend "query: " on query strings and "passage: " on passage/document strings.

Minimal curl

curl https://api.x.ai/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "v1",
    "input": ["passage: This is an example content to embed..."],
    "encoding_format": "float"
  }'

input accepts a string, an array of strings, an array of ints (token ids), or an array of int arrays. Optional dimensions truncates/pads the output length. encoding_format is float or base64.

OpenAI-compatible Python

import os
from openai import OpenAI

client = OpenAI(api_key=os.getenv("XAI_API_KEY"), base_url="https://api.x.ai/v1")

response = client.embeddings.create(
    model="v1",
    input=[
        "query: best practices for prompt caching",
        "passage: Sticky routing keeps multi-turn prefixes on one replica.",
    ],
    encoding_format="float",
)

for item in response.data:
    print(item.index, len(item.embedding), item.embedding[:3])
print(response.usage)

Response shape: object: "list", data[].embedding, data[].index, plus usage.prompt_tokens / usage.total_tokens.

List embedding models

curl https://api.x.ai/v1/embedding-models \
  -H "Authorization: Bearer $XAI_API_KEY"

curl https://api.x.ai/v1/embedding-models/v1 \
  -H "Authorization: Bearer $XAI_API_KEY"

GET /v1/embedding-models returns ids, aliases, modalities, and token prices. GET /v1/embedding-models/{model_id} returns the same fields for one model.

Pitfalls

• Embedding queries and passages without the query: / passage: prefixes the docs recommend.
• Pointing the OpenAI client at the default OpenAI host — set base_url="https://api.x.ai/v1".
• Ignoring embedding TPM when batching large corpora — same tier caps as text; batch and back off on 429.