Embeddings

⚠️

Preview — this feature is being built; the design below is the spec.

POST https://app.syntic.ai/v1/embeddings

An embedding turns a piece of text into a list of numbers (a vector). Texts with similar meaning get vectors that are close together, so you can search by meaning, group similar items, find duplicates and recommend related content. The request and response follow the widely used OpenAI-compatible embeddings shape, so existing client code works after changing the base URL and key.

When to use it

Semantic search and retrieval for a knowledge base (then pass the best passages to chat, with citations).
Clustering support tickets or feedback by topic.
Finding near-duplicate records.
Recommending “similar items”.

Authentication

Authorization: Bearer sk_live_..., Content-Type: application/json.

Request body

Field	Type	Required	Details
`model`	string	Yes	`syntic-embed-1`.
`input`	string or array of strings	Yes	Up to 2,048 strings, each up to 8,192 tokens, 300,000 tokens per request in total. Empty strings are not allowed.
`dimensions`	integer	No	Shorten vectors to 256, 512 or 1,024 (default 1,024). Shorter vectors use less storage at a small cost in quality.
`encoding_format`	string	No	`float` (default) or `base64` (smaller response).
`input_type`	string	No	`document` or `query`. Use `document` when indexing and `query` when searching for slightly better matches. Default `document`.
`user`	string	No	End-user id, as on Request parameters.

Response

{
  "object": "list",
  "model": "syntic-embed-1",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789] },
    { "object": "embedding", "index": 1, "embedding": [0.0021, 0.0334, -0.0102] }
  ],
  "usage": { "prompt_tokens": 18, "total_tokens": 18 }
}

Field	Description
`data[].index`	Position of the input this vector belongs to.
`data[].embedding`	The vector: `dimensions` floats (or a base64 string of little-endian float32). Vectors are normalised to length 1, so cosine similarity equals the dot product.
`usage.prompt_tokens`	Tokens billed.

Examples

curl https://app.syntic.ai/v1/embeddings \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "syntic-embed-1",
    "input": ["How do I reset my router?", "Router factory reset steps"],
    "input_type": "document"
  }'

async function embed(texts, inputType = 'document') {
  const resp = await fetch('https://app.syntic.ai/v1/embeddings', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ model: 'syntic-embed-1', input: texts, input_type: inputType }),
  })
  const data = await resp.json()
  if (!resp.ok) throw new Error(`${data.error.code}: ${data.error.message}`)
  return data.data.map(d => d.embedding)
}
 
const dot = (a, b) => a.reduce((s, x, i) => s + x * b[i], 0)
const [q] = await embed(['reset router'], 'query')
const docs = await embed(articles.map(a => a.text))
const best = docs.map((v, i) => [dot(q, v), articles[i]]).sort((x, y) => y[0] - x[0]).slice(0, 3)

import os, requests
 
def embed(texts, input_type="document"):
    resp = requests.post(
        "https://app.syntic.ai/v1/embeddings",
        headers={"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}"},
        json={"model": "syntic-embed-1", "input": texts, "input_type": input_type},
        timeout=60,
    )
    data = resp.json()
    if not resp.ok:
        raise RuntimeError(data["error"]["message"])
    return [d["embedding"] for d in data["data"]]
 
q = embed(["reset router"], "query")[0]
vectors = embed([a["text"] for a in articles])
scores = sorted(((sum(x * y for x, y in zip(q, v)), a) for v, a in zip(vectors, articles)), reverse=True)

Errors

Unified envelope.

Status	`code`	`param`	Cause
400	`input_required`	`input`	Missing or empty.
400	`input_too_long`	`input[i]`	One string over 8,192 tokens.
400	`too_many_inputs`	`input`	Over 2,048 strings or 300,000 tokens.
400	`invalid_dimensions`	`dimensions`	Not 256, 512 or 1,024.
404	`model_not_found`	`model`	Unknown embedding model. Chat models cannot embed.
429	`rate_limited`		Over the per-minute token limit.

Limits and pricing


Price	$0.02 per million tokens (usage credits). Included in plan allowances at a weight of 1 embedding token = 0.01 chat input tokens.
Rate limit	1,000,000 tokens per minute per organisation on the first tier
Batches	Not available for embeddings; send up to 2,048 inputs per request instead

Vectors from different embedding models are not comparable. If the model changes, re-embed your stored documents.

Build notes for the platform team

Serve from a hosted embedding model under the Syntic name; confirm licence terms before launch.
Normalise vectors server-side. Truncate for dimensions only if the model was trained for it; otherwise offer just the native size.
Separate usage line embeddings in reports.

Get a model Files

Was this page helpful?