> ## Documentation Index
> Fetch the complete documentation index at: https://developer.swytcho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/embeddings — Swytcho Text Embeddings API

> Convert text into dense vector representations for semantic search, clustering, classification, and retrieval-augmented generation (RAG) pipelines.

The `/v1/embeddings` endpoint converts one or more text strings into high-dimensional numeric vectors. These embeddings capture semantic meaning, so texts with similar meaning produce vectors that are close together in the vector space. Use embeddings to power semantic search, document clustering, recommendation systems, and retrieval-augmented generation (RAG) pipelines.

## Endpoint

```text theme={null}
POST https://api.swytcho.com/v1/embeddings
```

## Request Parameters

<ParamField body="model" type="string" required>
  The ID of the embedding model to use. Embedding models are separate from chat and completion models — call [`GET /v1/models`](/api-reference/models) and filter for models with `object: "embedding"` to see your options.
</ParamField>

<ParamField body="input" type="string | array" required>
  The text(s) to embed. Pass a single string to embed one piece of text, or an array of strings to embed multiple texts in a single request. Each string is embedded independently; the order of the output `data` array matches the order of your input.
</ParamField>

<ParamField body="encoding_format" type="string">
  The format of the returned embedding vectors. Use `"float"` (default) to receive a standard JSON array of floating-point numbers, or `"base64"` to receive a base64-encoded binary blob, which reduces response payload size for large batches.
</ParamField>

## Request Examples

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.swytcho.com/v1/embeddings \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "swytcho-embed-v1",
      "input": "The quick brown fox jumps over the lazy dog.",
      "encoding_format": "float"
    }'
  ```

  ```python Python theme={null}
  import os
  from swytcho import Swytcho

  client = Swytcho(api_key=os.environ["SWYTCHO_API_KEY"])

  response = client.embeddings.create(
      model="swytcho-embed-v1",
      input="The quick brown fox jumps over the lazy dog.",
      encoding_format="float",
  )

  vector = response.data[0].embedding
  print(f"Embedding dimensions: {len(vector)}")
  ```

  ```javascript Node.js theme={null}
  import Swytcho from "swytcho";

  const client = new Swytcho({ apiKey: process.env.SWYTCHO_API_KEY });

  const response = await client.embeddings.create({
    model: "swytcho-embed-v1",
    input: "The quick brown fox jumps over the lazy dog.",
    encoding_format: "float",
  });

  const vector = response.data[0].embedding;
  console.log(`Embedding dimensions: ${vector.length}`);
  ```
</CodeGroup>

## Response Fields

<ResponseField name="object" type="string">
  Always `"list"`.
</ResponseField>

<ResponseField name="model" type="string">
  The embedding model ID that was used to generate the vectors.
</ResponseField>

<ResponseField name="data" type="array">
  An array of embedding objects, one per input string, in the same order as your `input` array.

  <Expandable title="Embedding object fields">
    <ResponseField name="index" type="integer">
      Zero-based index corresponding to the position of this embedding in the input array.
    </ResponseField>

    <ResponseField name="object" type="string">
      Always `"embedding"`.
    </ResponseField>

    <ResponseField name="embedding" type="array | string">
      The embedding vector. When `encoding_format` is `"float"` (default), this is a JSON array of numbers. When `encoding_format` is `"base64"`, this is a base64-encoded string.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics for the request.

  <Expandable title="Usage object fields">
    <ResponseField name="prompt_tokens" type="integer">
      Number of tokens across all input strings.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total tokens consumed (same as `prompt_tokens` for embeddings — there are no completion tokens).
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Response

```json theme={null}
{
  "object": "list",
  "model": "swytcho-embed-v1",
  "data": [
    {
      "index": 0,
      "object": "embedding",
      "embedding": [0.0023064255, -0.009327292, 0.01589467, -0.004121838, 0.0082586454]
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}
```

<Note>
  The number of dimensions in the returned vector depends on the embedding model you choose. Check the model details via [`GET /v1/models/{model_id}`](/api-reference/models) for the `dimensions` field before designing your vector store schema — storing vectors with the wrong dimension will cause index errors. Changing models after populating a vector store requires re-embedding all existing records.
</Note>