POST/v1/embeddings

Create embeddings

Creates embedding vectors representing the input text, using an OpenAI-compatible request and response format. Any SDK that supports OpenAI embeddings works by changing the base URL and API key.

Calling an asymmetric model

Some embedding models are asymmetric: they encode the same sentence differently depending on whether it is a search query or a stored document. When you call one, embed documents as-is (the default) and set extra.input_type to query for search queries, so the model applies its instruct prefix. Sending queries without it silently degrades retrieval quality. sionic-ai/comsat-embed-ko-8b-preview is asymmetric.

Headers

AuthorizationstringRequired
Bearer token for authentication. Format: Bearer YOUR_API_KEY
x-opengateway-user-idstringOptional
User identifier for analytics and tracking.
x-opengateway-session-idstringOptional
Session identifier for analytics and tracking.

Request body

modelstringRequired
ID of the embedding model to use, in the owner/model format, such as sionic-ai/comsat-embed-ko-8b-preview.
inputstring or arrayRequired
Text to embed — a single string or an array of strings. Each input is limited to 8,192 tokens; longer inputs are rejected with 400 (they are never silently truncated). Batches are limited to 128 inputs per request. Token ID arrays are not supported.
encoding_formatstringOptional
Format of the returned vectors: float (default) or base64.
dimensionsintegerOptional
Number of dimensions for the output vectors. Supported values for comsat-embed-ko-8b-preview are 2048 and 4096 (default). Other values are rejected with 400.
userstringOptional
End-user identifier forwarded to the provider when supported.
extraobjectOptional🔌
OpenGateway-specific extension parameters. OpenAI SDKs pass this via extra_body.
input_typestring🔌

query or document (default). Applies to the whole batch. Use query when embedding search queries for retrieval.

fallbacksarray🔌

List of fallback model IDs to try if the primary target fails.

Returns

Returns an OpenAI-compatible embeddings response.

objectstring
Always list.
dataarray
One embedding object per input, in request order.
data[].embeddingarray or string
The embedding vector — an array of floats, or a base64-encoded string when encoding_format is base64.
data[].indexinteger
Index of the corresponding input.
modelstring
The requested model ID.
usageobject
Token usage. Embeddings have no output tokens, so prompt_tokens equals total_tokens. Query encoding includes the model's instruct prefix tokens.

Request

# Document embedding (default)
curl https://apis.opengateway.ai/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "sionic-ai/comsat-embed-ko-8b-preview",
    "input": "Seoul is the capital of South Korea."
  }'


# Query embedding (for search queries)
curl https://apis.opengateway.ai/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "sionic-ai/comsat-embed-ko-8b-preview",
    "input": "What is the capital of South Korea?",
    "extra": {"input_type": "query"}
  }'

Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0388, 0.0105, -0.0030, ...]
    }
  ],
  "model": "sionic-ai/comsat-embed-ko-8b-preview",
  "usage": {
    "prompt_tokens": 7,
    "total_tokens": 7
  }
}