Embeddings API Objects

Type definitions for every object the Embeddings API returns — EmbeddingResponse, Embedding, EmbeddingUsage.

This page defines every named object returned by POST /v1/embeddings. Reference these from guides and other docs:

"Returns an EmbeddingResponse object."

The `EmbeddingResponse` Object

The top-level response object returned by POST /v1/embeddings.

interface EmbeddingResponse {
  object: "list";
  model:  string;
  data:   Embedding[];
  usage:  EmbeddingUsage;
}

Field	Type	Description
`object`	`"list"`	Type discriminator — always `"list"`
`model`	`string`	The resolved model identifier used to generate the embeddings
`data`	`Embedding[]`	One entry per input string, in request order. Match to inputs by `data[i].index`
`usage`	`EmbeddingUsage`	Token counts for the request

Example:

{
  "object": "list",
  "model": "skytells-embed-3-large",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023064255, -0.009327292, 0.015797847, "..."]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [-0.003712451, 0.011408234, -0.005432891, "..."]
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}

The `Embedding` Object

A single embedding vector for one input string. Part of the data[] array in an EmbeddingResponse.

interface Embedding {
  object:    "embedding";
  index:     number;
  embedding: number[] | string;
}

Field	Type	Description
`object`	`"embedding"`	Type discriminator
`index`	`number`	Zero-based position corresponding to the input array. Use this to match each embedding to its source string when batch-embedding
`embedding`	`number[] \| string`	The embedding vector. `number[]` when `encoding_format: "float"` (default); a base64-encoded binary string when `encoding_format: "base64"`

Dimension by model:

Model	Dimensions (default)	Supports `dimensions` reduction
`skytells-embed-3-large`	3072	Yes
`skytells-embed-3-small`	1536	Yes

Decoding a base64 embedding:

const bytes = Buffer.from(embedding, 'base64');
const floats = new Float32Array(bytes.buffer);
// floats is now equivalent to the float[] you'd get with encoding_format: "float"

Using embeddings for cosine similarity:

function cosineSimilarity(a: number[], b: number[]): number {
  let dot = 0, magA = 0, magB = 0;
  for (let i = 0; i < a.length; i++) {
    dot  += a[i] * b[i];
    magA += a[i] * a[i];
    magB += b[i] * b[i];
  }
  return dot / (Math.sqrt(magA) * Math.sqrt(magB));
}

// Returns a value between -1 and 1; higher = more semantically similar
const similarity = cosineSimilarity(embeddingA, embeddingB);

Embeddings are unit-normalized before being returned. This means dot product and cosine similarity are equivalent (dot(a, b) == cosine(a, b) for unit vectors), so you can skip the normalization step in performance-critical code.

The `EmbeddingUsage` Object

Token consumption for an embeddings request.

interface EmbeddingUsage {
  prompt_tokens: number;
  total_tokens:  number;
}

Field	Type	Description
`prompt_tokens`	`number`	Number of tokens in all input strings combined
`total_tokens`	`number`	Always equal to `prompt_tokens` for embeddings (there are no completion tokens)

Embeddings are billed per input token. Batching multiple strings into one request does not reduce the token count — total_tokens reflects the sum of all inputs in the batch.

How is this guide?

The EmbeddingResponse Object

The Embedding Object

The EmbeddingUsage Object

On this page

The `EmbeddingResponse` Object

The `Embedding` Object

The `EmbeddingUsage` Object