TokenLab

Text

Create Embedding

Creates an embedding vector representing the input text

POST
/v1/embeddings

Use GET /v1/models?recommended_for=embedding to list current embedding models. Use a model whose details list the embedding or text-embedding operation. A model that lists multimodal-embedding returns 400 unsupported_endpoint here; send it to Create Multimodal Embeddings.

Request Body

This endpoint returns after the vectors are ready. For large batches, set your HTTP client timeout to at least 120s.

modelstringrequired

ID of the embedding model to use (e.g., text-embedding-3-small).

inputstring | arrayrequired

Text to embed: a string or an array of strings. Models that support token input also accept number[] for one token sequence or number[][] for multiple sequences. The number of items, tokens per item, and tokens per request depend on the model; read them in GET /v1/models/{model}.

encoding_formatstringdefault: float

Format for the embeddings: float or base64.

dimensionsinteger

Number of dimensions of each returned vector, a positive integer. Send it only when the model details list dimensions; the maximum depends on the model.

userstring

A unique identifier representing your end-user for abuse monitoring.

Response

objectstring

Always list.

dataarray

Array of embedding objects.

Each object contains:

  • object (string): embedding
  • index (integer): Index in the input array
  • embedding (array | string): A numeric vector for float, or a Base64 string for base64.
modelstring

Model used.

usageobject

Token usage with prompt_tokens and total_tokens.

Request

curl -X POST "https://api.tokenlab.sh/v1/embeddings" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "The quick brown fox jumps over the lazy dog"
  }'

The example vector is shortened for readability.

Response

Response
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0194, 0.0081]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}

Batch Embeddings

# Embed multiple texts at once
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=[
        "First document text",
        "Second document text",
        "Third document text"
    ]
)

for i, data in enumerate(response.data):
    print(f"Document {i}: {len(data.embedding)} dimensions")

Errors

StatusCodeCause
400invalid_requestA field is missing or has the wrong type. param names it
400unsupported_endpointThe model is not published for this endpoint
413The request body is too large

Handle other statuses as in Handle API errors.

For models that list multimodal-embedding, use Create Multimodal Embeddings.

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Headers

X-TokenLab-Delivery-Policy?string

Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.

Value in

  • "auto"
  • "verified"
  • "official"

Request Body

application/json

Response

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json