Skip navigation
Contents

API

Embeddings

POST /v1/embeddings — create embedding vectors for semantic search, RAG and clustering. Same request/response as the OpenAI Embeddings API; shares the wallet, API keys and rate limits with chat.

A single input#

Only models of type Embedding in the pricing table (Type column) can be used. Calling a chat model on this endpoint is rejected with model_type_mismatch.

Embed a string
curl https://<host>/v1/embeddings \
  -H "Authorization: Bearer sk-kompa-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Any là API LLM trả trước theo token."
  }'
Response
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, …] }
  ],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 12, "total_tokens": 12 }
}

Batches and dimensions#

Send an array of strings to get several vectors in one request (up to 2,048 items). Results come back in the same order, each with an index. The dimensions parameter shortens the vectors if the model supports it.

Batch + dimensions
curl https://<host>/v1/embeddings \
  -H "Authorization: Bearer sk-kompa-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["Hà Nội", "Thành phố Hồ Chí Minh", "Đà Nẵng"],
    "dimensions": 256
  }'

Batch for speed and fewer rate limits

A request with 500 inputs counts once against your rpm, not 500 times. Batches of a few hundred inputs per request work well.

Token inputs#

input can also be an array of token ids (one input) or an array of arrays of token ids (several inputs) — useful when you have already tokenized your text. Token ids must be integers ≥ 0 and match the model’s tokenizer.

Token arrays
# one tokenised input
curl https://<host>/v1/embeddings \
  -H "Authorization: Bearer sk-kompa-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "text-embedding-3-small", "input": [9906, 1917, 0]}'

# several tokenised inputs
curl https://<host>/v1/embeddings \
  -H "Authorization: Bearer sk-kompa-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "text-embedding-3-small", "input": [[9906, 1917], [15339, 11, 1917]]}'

Parameters#

  • model
    Rule
    Required. An embedding model.
  • input
    Rule
    Required. A non-empty string, an array of strings, an array of token ids, or an array of arrays of token ids. Up to 2,048 items.
  • dimensions
    Rule
    Optional positive integer. Only applies to models that support it; other models may return a 400 error.
  • encoding_format
    Rule
    float (default) or base64.
  • user
    Rule
    Optional string.
  • stream
    Rule
    Ignored (embeddings don’t stream).

The maximum body size is 10 MB. Responses always include the X-Request-Id header.

Billing#

  • Only input tokens are billed, at the model’s input price (USD / 1M tokens). There are no output tokens.
  • Billed tokens = usage.prompt_tokens in the response.
  • The hold before the call = estimated tokens (strings: tokenizer +10% safety margin; token arrays: exact length) × input price. Insufficient available balance → 402 insufficient_balance.
  • Provider errors are not billed. General details: Billing.

Common errors#

400 model_type_mismatch
HTTP/1.1 400 Bad Request

{"error": {"message": "The model `gpt-4o-mini` is a chat model; use /v1/chat/completions instead.",
           "type": "invalid_request_error", "code": "model_type_mismatch"}}
  • 400 model_type_mismatch
    Cause
    The model is a chat model (or an embedding model was called on /v1/chat/completions). The message names the correct endpoint.
  • 400 invalid_request
    Cause
    input empty / wrong type, more than 2,048 items, dimensions not a positive integer, invalid encoding_format.
  • 404 model_not_found
    Cause
    Unknown model name, or the model is disabled.
  • 402 insufficient_balance
    Cause
    Not enough balance for the hold — top up or send less input.

All error codes: Error codes.