POST /v1/embeddings

OpenAI-compatible embeddings. Single value or batch, with optional dimension truncation.

FIG.

FIG. 00 · POST /V1/EMBEDDINGSINPUT → VECTOR

/v1/embeddings returns a vector representation of one or many input strings. Wire format is OpenAI-compatible — pass the same model id to the AI SDK's streamText family (specifically embed / embedMany) and you get the same vectors with a friendlier TypeScript surface.

FIG. 01BATCH SHAPE

SCHEMATIC

`input` accepts a single string or an array of up to 2048 items. The response carries one `embedding` per input, in order, with token usage reported once per request. `dimensions` truncates and re-normalizes on supported models.

Endpoint

POST https://synapse.garden/api/v1/embeddings

Request body

{
  model: string,                  // e.g. "openai/text-embedding-3-large"
  input: string | string[],       // single string or batch (up to 2048 items)
  dimensions?: number,            // optional truncation (OpenAI v3 models only)
  encoding_format?: "float" | "base64", // default: "float"
  user?: string,                  // end-user identifier (forwarded for abuse detection)
}

Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.012, -0.034, 0.089, ...]
    },
    ...
  ],
  "model": "openai/text-embedding-3-large",
  "usage": {
    "prompt_tokens": 24,
    "total_tokens": 24
  }
}

For encoding_format: "base64", embedding is a base64-encoded Float32Array — useful when you're piping vectors into a binary store and want to avoid JSON overhead.

Examples

curl — single

curl https://synapse.garden/api/v1/embeddings \
  -H "Authorization: Bearer $MG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-large",
    "input": "The quick brown fox"
  }'

curl — batch

curl https://synapse.garden/api/v1/embeddings \
  -H "Authorization: Bearer $MG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-large",
    "input": ["First sentence.", "Second sentence.", "Third sentence."]
  }'

OpenAI SDK

const res = await client.embeddings.create({
  model: "openai/text-embedding-3-large",
  input: ["The quick brown fox", "Jumps over the lazy dog"],
})

for (const { embedding, index } of res.data) {
  console.log(`#${index} → ${embedding.length}d vector`)
}

AI SDK

import { embed, embedMany } from "ai"

const { embedding } = await embed({
  model: "openai/text-embedding-3-large",
  baseURL: "https://synapse.garden/api/v1",
  apiKey: process.env.MG_KEY,
  value: "The quick brown fox",
})

const { embeddings } = await embedMany({
  model: "openai/text-embedding-3-large",
  values: ["...", "...", "..."],
})

Dimension truncation

OpenAI v3 embedding models support truncating the output dimension:

curl https://synapse.garden/api/v1/embeddings \
  -H "Authorization: Bearer $MG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-large",
    "input": "...",
    "dimensions": 1024
  }'

The model truncates and re-normalizes — quality degrades gracefully. 1024 is fine for most retrieval tasks.

Errors

Same envelope as the other endpoints. Common ones for embeddings:

HTTP	Code	When
400	`INVALID_REQUEST`	`input` longer than the model's max context
400	`INVALID_REQUEST`	Batch larger than 2048 items
404	`MODEL_NOT_FOUND`	Embedding model doesn't exist
422	`INVALID_REQUEST`	`dimensions` not supported by this model

Pricing

Embedding models are billed per million input tokens. Output dimension doesn't affect cost. Browse /models filtered by Embeddings for live rates.