Create Embeddings

POST /v1/embeddings — full parameter reference with code examples for the Skytells SDK, REST, and OpenAI client.

POSThttps://api.skytells.ai/v1/embeddings

Convert one or more text strings into high-dimensional float vectors. Vectors from the same model occupy the same space, so you can measure semantic similarity with cosine similarity or dot product.

Returns an EmbeddingResponse object.

Request Body

modelrequiredstring

The embedding model to use. Example: "skytells-embed-3-large". See Models for available IDs.

inputrequiredstring | string[] | integer[] | integer[][]

Text to embed. Accepts:

A single string — embeds one piece of text
A string[] array — embeds multiple texts in one request (batching)
A token ID array or array of token ID arrays for pre-tokenized inputs

Each string has a token limit determined by the model. Batch inputs share the same request and return embeddings in the same order.

// Single string
"The cat sat on the mat."

// Batch of three strings
[
  "Machine learning is a subset of AI.",
  "Neural networks learn from data.",
  "Deep learning uses many layers."
]

encoding_formatstring

The format of the returned embedding vectors. Values:

"float" (default) — returns a number[] suitable for direct use
"base64" — returns a base64-encoded binary representation of the float32 array; more compact over the wire, requires decoding on the client side

// Decode a base64 embedding
const bytes = Buffer.from(embedding, 'base64');
const floats = new Float32Array(bytes.buffer);

dimensionsinteger

The number of dimensions to reduce the output vector to. Only supported on models that explicitly support dimension reduction. Reduction truncates the vector mathematically (not just slicing) to preserve relative distances. Useful for storage- or latency-constrained applications.

Must be a positive integer ≤ the model's native dimension (e.g. ≤ 3072 for skytells-embed-3-large).

userstring

An opaque identifier for the end-user. Used for abuse monitoring and rate-limit attribution. Does not affect the embedding result.

REST

# Single embedding
curl https://api.skytells.ai/v1/embeddings \
-H "Content-Type: application/json" \
-H "x-api-key: $SKYTELLS_API_KEY" \
-d '{
  "model": "skytells-embed-3-large",
  "input": "Semantic search is powerful."
}'

# Batch embeddings
curl https://api.skytells.ai/v1/embeddings \
-H "Content-Type: application/json" \
-H "x-api-key: $SKYTELLS_API_KEY" \
-d '{
  "model": "skytells-embed-3-large",
  "input": [
    "Machine learning",
    "Deep learning",
    "Neural networks"
  ]
}'

# With base64 encoding for compact transfer
curl https://api.skytells.ai/v1/embeddings \
-H "Content-Type: application/json" \
-H "x-api-key: $SKYTELLS_API_KEY" \
-d '{
  "model": "skytells-embed-3-large",
  "input": "Store this compactly.",
  "encoding_format": "base64"
}'

Response

200 OK

{
"object": "list",
"model": "skytells-embed-3-large",
"data": [
  {
    "object": "embedding",
    "index": 0,
    "embedding": [0.0023064255, -0.009327292, 0.015797942, "..."]
  }
],
"usage": {
  "prompt_tokens": 6,
  "total_tokens": 6
}
}

Response

A successful call returns an EmbeddingResponse object.

200 OK

{
  "object": "list",
  "model": "skytells-embed-3-large",
  "data": [{ "object": "embedding", "index": 0, "embedding": [0.0023, -0.0093, "..."] }],
  "usage": { "prompt_tokens": 6, "total_tokens": 6 }
}

See the full EmbeddingResponse and Embedding objects for complete field definitions.

Batch Embeddings

Send up to hundreds of strings in a single request by passing a string[] to input. Responses are returned in the same order as the inputs and can be matched by data[i].index.

Batch embed and store

REST

curl https://api.skytells.ai/v1/embeddings \
-H "Content-Type: application/json" \
-H "x-api-key: $SKYTELLS_API_KEY" \
-d '{
  "model": "skytells-embed-3-large",
  "input": [
    "Skytells is an AI platform.",
    "Build production-ready AI apps.",
    "Access leading models via a single API."
  ]
}' | jq '.data | map({ index: .index, dims: (.embedding | length) })'

Response

200 OK

{
"object": "list",
"model": "skytells-embed-3-large",
"data": [
  { "object": "embedding", "index": 0, "embedding": [0.0023, -0.0093, 0.0157, "..."] },
  { "object": "embedding", "index": 1, "embedding": [0.0031, -0.0071, 0.0204, "..."] },
  { "object": "embedding", "index": 2, "embedding": [-0.0011, 0.0142, -0.0088, "..."] }
],
"usage": {
  "prompt_tokens": 21,
  "total_tokens": 21
}
}

Semantic Similarity

Compute cosine similarity between two embedding vectors to measure semantic relatedness:

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));
}

const result = await client.embeddings.create({
  model: 'skytells-embed-3-large',
  input: [
    'The cat is on the mat.',
    'A feline rests on a rug.',
    'Linear algebra is useful in ML.',
  ],
});

const [a, b, c] = result.data.map(d => d.embedding);

console.log(cosineSimilarity(a, b));  // ~0.93 — semantically similar
console.log(cosineSimilarity(a, c));  // ~0.72 — semantically different

OpenAPI Reference

The interactive spec below is generated directly from the Skytells OpenAPI schema. It covers every accepted parameter with its type, constraints, and default value. Use the Try it panel to send a live request — set your x-api-key in the auth field first.

Authorization

apiKey

x-api-key<token>

Your Skytells API key. Obtain one from Dashboard → API Keys.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

model*string

Value in"deepbrain-router" | "gpt-5" | "gpt-5.4"

input*|array<>

Text to embed. String or array of strings for batch embedding.

encoding_format?string

Format of the returned embedding vectors.

Default"float"

Value in"float" | "base64"

dimensions?integer

Number of dimensions in the output vector.

Response Body

`application/json`

curl -X POST "https://api.skytells.ai/v1/embeddings" \  -H "Content-Type: application/json" \  -d '{    "model": "deepbrain-router",    "input": "The quick brown fox jumps over the lazy dog."  }'

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0023064255,
        -0.009327292,
        0.015797101
      ]
    }
  ],
  "model": "deepbrain-router",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

Expected Errors

All errors follow the Skytells error schema. Always branch on error.error_id — never on error.message. Pass error.request_id to Support when reporting issues.

HTTP	`error_id`	Cause
`401`	`UNAUTHORIZED`	Missing or invalid `x-api-key`
`402`	`INSUFFICIENT_CREDITS`	Account balance too low (includes $1 safety margin)
`403`	`FORBIDDEN`	Key valid but access denied or account suspended
`400`	`INVALID_REQUEST`	Malformed JSON or invalid body shape
`400`	`INVALID_PARAMETER`	Missing `model` / `input`, invalid `encoding_format` or `dimensions`
`404`	`MODEL_NOT_FOUND`	Unknown or unavailable embedding model
`422`	`CONTENT_POLICY_VIOLATION`	Input text blocked by safety policy
`429`	`RATE_LIMITED`	Too many requests at the edge layer
`503`	`INFERENCE_RATE_LIMITED`	Inference layer busy; retry with backoff
`503`	`SERVICE_UNAVAILABLE`	Service temporarily down
`504`	`INFERENCE_TIMEOUT`	Request timed out
`500`	`INFERENCE_ERROR`	Provider error or embeddings not supported by provider
`500`	`INTERNAL_ERROR`	Unexpected gateway error

For retry guidance and error-handling code examples, see Inference Errors.

How is this guide?

Create Embeddings