Tīrtha is still being built, so some features and models may not work as expected yet. Billing always follows the prices shown. Something broken? Email [email protected].

Tīrtha

Embeddings

An embedding model turns each text into a list of numbers (a vector). Texts that mean similar things get vectors that point the same way, so you can search, group and match by meaning rather than exact words. Use it for search over your own documents, finding duplicates, grouping by topic, and as the first step before a reranker.

Request

POST https://api.tirtha.ai/v1/embeddings with your key. Send model and input (one string or a list of strings). The only other field is encoding_format; the only value served is "float", the default. Any other field is refused by name, never dropped.

Using the OpenAI SDK? Pass encoding_format="float". The SDK asks for the vectors as base64 text unless you say otherwise, and Tīrtha sends plain numbers only today, so a call without it is refused with 400 invalid_encoding_format. Nothing is charged for that refusal.
curl https://api.tirtha.ai/v1/embeddings \
  -H "Authorization: Bearer $TIRTHA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tirtha/qwen3-embedding-8b",
    "input": [
      "Orders ship within three to five business days.",
      "You can reset your password from the login page."
    ]
  }'
import os, requests

API = "https://api.tirtha.ai/v1"
H = {"Authorization": "Bearer " + os.environ["TIRTHA_API_KEY"]}
MODEL = "tirtha/qwen3-embedding-8b"

def embed(texts):
    """One call: up to 64 texts, up to 100,000 characters in total."""
    r = requests.post(API + "/embeddings", headers=H, timeout=130,
                      json={"model": MODEL, "input": texts})
    if r.status_code != 200:
        raise RuntimeError(r.status_code, r.json().get("error"))
    body = r.json()
    print(body["usage"]["tokens"], "tokens, charged $" + body["usage"]["charged"])
    rows = sorted(body["data"], key=lambda d: d["index"])
    return [d["embedding"] for d in rows]

vectors = embed(["Orders ship within three to five business days.",
                 "You can reset your password from the login page."])
print(len(vectors), "vectors of", len(vectors[0]), "numbers")
const API = "https://api.tirtha.ai/v1";

const r = await fetch(API + "/embeddings", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TIRTHA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "tirtha/qwen3-embedding-8b",
    input: [
      "Orders ship within three to five business days.",
      "You can reset your password from the login page.",
    ],
  }),
});
const body = await r.json();
if (!r.ok) throw new Error(r.status + " " + JSON.stringify(body.error));

const vectors = body.data
  .sort((a, b) => a.index - b.index)
  .map((d) => d.embedding);
console.log(vectors.length, "vectors, charged $" + body.usage.charged);
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.tirtha.ai/v1",
                api_key=os.environ["TIRTHA_API_KEY"])

resp = client.embeddings.create(
    model="tirtha/qwen3-embedding-8b",
    input=["Orders ship within three to five business days.",
           "You can reset your password from the login page."],
    encoding_format="float",   # needed: the SDK asks for base64 otherwise
)
vectors = [d.embedding for d in resp.data]
# Tirtha's usage fields: tokens, charged, estimated
print(len(vectors), "vectors, charged $" + resp.usage.model_extra["charged"])

Response

One data entry per text you sent. index is the position of the text in your list: sort by it before pairing vectors with texts. The vector length is fixed per model; Qwen3 Embedding 8B gives 4,096 numbers per text (shortened to 4 in the example).

Example shape; real recorded reply coming. The field names and types are the ones the API returns; the values are examples.

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0213, -0.0087, 0.0441, -0.0129]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [-0.0302, 0.0176, 0.0058, 0.0264]
    }
  ],
  "model": "tirtha/qwen3-embedding-8b",
  "usage": {
    "tokens": 21,
    "charged": "0.000001",
    "estimated": false
  }
}
FieldTypeMeaning
data[].embeddinglist of numbersThe vector.
data[].indexintegerWhich text it belongs to (0 is the first text you sent).
modelstringThe model id you asked for.
usage.tokensintegerTokens the model counted for this call: the billed amount.
usage.chargedstringWhat this call cost, in US dollars, with 6 decimals.
usage.estimatedbooleantrue only if the model did not report a count and our estimate was billed instead.

Pricing

Per 1M input tokens. You pay for the tokens the model counts in your texts; the vectors that come back cost nothing extra. Each model’s price is on the Embeddings tab, the one price list for the site.

Before the call runs, a hold for an upper estimate of its cost is set aside from your credit. The bill is the counted tokens, never the hold, and the reply gives the exact amount in usage.charged. Requests that fail are not charged.

Limits

LimitValue
Texts per callUp to 64
Characters per callUp to 100,000 in total, across all texts
Each textNot empty and not only spaces. The gateway has no separate cap per text: it checks the total. A text longer than the model accepts is refused by the model with 400 request_rejected, and nothing is charged.
Vector formatfloat only (no base64, no dimensions)
Requests per minuteSet per key. A key with a limit gets 429 quota_exceeded over it, with Retry-After: 60. One call with 64 texts counts as one request.
At capacity429 media_busy with Retry-After: 2; nothing is charged.
TimeThe gateway waits up to 120 seconds for the model. Set your client timeout a little above that (the examples use 130).

Errors

StatusCodeMessageWhat to do
400invalid_encoding_formatOnly encoding_format 'float' is served.The OpenAI SDK sends base64 unless told otherwise: pass encoding_format="float".
400invalid_input'input' must be 1-64 non-empty strings.Also sent when the texts add up to more than 100,000 characters, or one is empty or only spaces.
404model_not_foundUnknown embedding model.Use an id from the Embeddings tab, with the tirtha/ prefix.
400request_rejectedThe request was rejected. Nothing was charged.The model refused the input, most often a text longer than it accepts. Split long texts.
402insufficient_creditsNot enough prepaid credit for this request (it may need <amount>).Add credits. A real recorded reply is below.

Recorded reply, 2026-11-13: HTTP 402 from a key with no credit.

{
  "error": {
    "message": "Not enough prepaid credit for this request (it may need 0.000002).",
    "type": "invalid_request_error",
    "code": "insufficient_credits"
  }
}

Every other error these routes can return (key, terms, rate limit, spend cap, busy, billing) is on Common errors, with what to do for each. Anything refused before the model runs costs nothing.

Best practices

  1. Fill every call.

    Send up to 64 texts per call instead of one call per text: fewer round trips, and a per-minute limit counts calls, not texts. This helper fills each call to both limits:

    # uses embed() from the Python request example
    def embed_all(texts, max_texts=64, max_chars=100_000):
        """Fill each call up to both limits, keeping the order."""
        out, batch, size = [], [], 0
        for i, t in enumerate(texts):
            if len(t) > max_chars:
                raise ValueError("text %d is longer than %d characters; split it first"
                                 % (i, max_chars))
            full = len(batch) == max_texts or size + len(t) > max_chars
            if batch and full:
                out += embed(batch)
                batch, size = [], 0
            batch.append(t)
            size += len(t)
        if batch:
            out += embed(batch)
        return out
  2. Embed a text once, then keep the vector.

    You usually do not need to recompute a vector for the same text and model, so store it and pay once. Key the store on the model id plus the text, and clear it when you change models, so vectors from two models never mix.

    # uses MODEL from the request example and embed_all() from tip 1
    import hashlib, json, os
    
    CACHE = "vectors.jsonl"   # one JSON line per text: key + vector
    seen = {}
    if os.path.exists(CACHE):
        for line in open(CACHE):
            row = json.loads(line)
            seen[row["key"]] = row["vector"]
    
    def key(text):
        return hashlib.sha256((MODEL + "\n" + text).encode()).hexdigest()
    
    def embed_cached(texts):
        new = [t for t in dict.fromkeys(texts) if key(t) not in seen]
        if new:
            with open(CACHE, "a") as f:
                for t, v in zip(new, embed_all(new)):
                    seen[key(t)] = v
                    f.write(json.dumps({"key": key(t), "vector": v}) + "\n")
        return [seen[key(t)] for t in texts]
  3. Use the same model for documents and queries.

    A query vector can only be compared with document vectors from the same model. If you switch models, re-embed everything: vectors from two models are not comparable, even at the same length.

  4. Follow the model card: instruction on queries, normalize, then cosine.

    Qwen3 Embedding 8B expects an instruction before each query and none before documents. Its model page gives the format and asks for normalized vectors compared by cosine. After normalizing, cosine similarity is a plain dot product, which vector databases compute fastest. The full example below does all three. Other models list their own rules in the same How to use it box.

  5. Chunk by meaning, and keep chunks well under the model’s limit.

    Split at paragraphs or headings, not at a fixed character count. A chunk that mixes two topics matches neither well. Long text, code and non-English text use more tokens per character, so leave room.

  6. Plan the storage before you embed a million texts.

    A 4,096-number vector stored as 32-bit floats is 16 KB. A million chunks is about 16 GB of vectors before any index. Store them as binary floats (a vector database or a NumPy array), not as JSON text, which is several times larger.

  7. Check the total when invalid_input comes back under 64 texts.

    The same error covers the 100,000-character total, an empty string and a string of only spaces. Strip empty texts and check the total length before you send.

  8. Log usage.charged per call.

    Every reply says what it cost. Summing it in your own logs gives a live cost per job. With the OpenAI SDK it is in resp.usage.model_extra["charged"].

Full example

Search with embeddings and rerank, following the advice above: documents embedded once as they are, the query with its instruction, normalized vectors, cosine by dot product, then the reranker on the top candidates. It runs as pasted.

import os, requests

API = "https://api.tirtha.ai/v1"
H = {"Authorization": "Bearer " + os.environ["TIRTHA_API_KEY"]}
TASK = ("Given a web search query, retrieve relevant passages "
        "that answer the query")

def post(path, body):
    r = requests.post(API + path, headers=H, json=body, timeout=130)
    if r.status_code != 200:
        raise RuntimeError(r.status_code, r.json().get("error"))
    return r.json()

def normalize(v):
    n = sum(x * x for x in v) ** 0.5
    return [x / n for x in v]

def embed(texts):
    body = post("/embeddings", {"model": "tirtha/qwen3-embedding-8b",
                                "input": texts})
    rows = sorted(body["data"], key=lambda d: d["index"])
    return [normalize(d["embedding"]) for d in rows]

docs = ["Orders ship within three to five business days.",
        "You can reset your password from the login page.",
        "Refunds go back to the original payment method."]
question = "How long does shipping take?"

# 1. documents as they are, once; store these vectors
doc_vectors = embed(docs)
# 2. the question with the instruction, same model
q = embed(["Instruct: " + TASK + "\nQuery:" + question])[0]
# 3. normalized vectors: the dot product is the cosine similarity
scores = [sum(a * b for a, b in zip(q, d)) for d in doc_vectors]
order = sorted(range(len(docs)), key=lambda i: scores[i], reverse=True)
candidates = order[:30]          # with a real collection: 20 to 50
# 4. rerank the candidates with the plain question, best first
hits = post("/rerank", {"model": "tirtha/qwen3-reranker-8b",
                        "query": question,
                        "documents": [docs[i] for i in candidates],
                        "top_n": 2})["results"]
for h in hits:                   # index points into the list you sent
    print(round(h["relevance_score"], 3), docs[candidates[h["index"]]])

Checked against the API code on 2026-11-14. Tīrtha is still being built; limits and fields may change, and this page changes with them.