> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Direct Embeddings
> Turn one string, or a batch of up to 2048 strings, into embedding vectors with a Gloo embedding model. OpenAI-compatible. No guardrails, routing, or streaming.
Model choice, input limits, pricing, and using the OpenAI SDK against this endpoint.
Common errors: not an embedding model, invalid input, input longer than the model's limit, provider unavailable.
## OpenAPI
````yaml post /ai/v2/direct/embeddings
openapi: 3.1.0
info:
title: AI API
description: |-
Optimized for high-speed inference and scalability by Gloo AI
[Swagger UI](./docs) | [ReDoc UI](./redoc)
version: 1.0.0
servers:
- url: https://platform.ai.gloo.com
security:
- bearerAuth: []
tags:
- name: Content Controls
- name: Data Engine
- name: Ingestion & Enrichment
- name: answers
- name: chat
- name: completions
- name: content
- name: core
- name: data
- name: get-models
- name: ingestion
- name: sotc
paths:
/ai/v2/direct/embeddings:
post:
tags:
- v2
summary: Direct Embeddings
description: >-
Turn one string, or a batch of up to 2048 strings, into embedding
vectors with a Gloo embedding model. OpenAI-compatible. No guardrails,
routing, or streaming.
operationId: post-v2-direct-embeddings
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmbeddingsRequest'
responses:
'200':
description: Embeddings, one per input string, in input order.
content:
application/json:
schema:
$ref: '#/components/schemas/EmbeddingsResponse'
'400':
description: >-
Bad Request - not an embedding model, invalid `input`,
`encoding_format` or `dimensions`, or the provider rejected the
request (for example, an input longer than the model's
`max_input_tokens`). Not retryable.
content:
application/json:
schema:
type: object
required:
- detail
properties:
detail:
type: object
properties:
message:
type: string
type:
type: string
code:
type: string
retryable:
type: boolean
param:
type: string
example:
detail:
message: >-
Model 'gloo-openai-gpt-4.1-mini' is not an embedding model.
/ai/v2/direct/embeddings serves the embedding models listed
by /platform/v2/models.
type: invalid_request_error
code: invalid_request_error
retryable: false
param: model
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'503':
description: >-
The embedding provider is unavailable or rate-limited. Retry with
exponential backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/AiErrorResponse'
components:
schemas:
EmbeddingsRequest:
type: object
title: EmbeddingsRequest
required:
- model
- input
additionalProperties: true
description: >-
OpenAI-compatible embeddings request. Parameters not listed here are
forwarded to the model provider unchanged.
properties:
model:
type: string
title: Model
description: >-
An embedding model's Gloo Model ID (e.g.
`gloo-openai-text-embedding-3-small`). Only models whose
`output_modalities` include `embeddings` on `GET
/platform/v2/models` are accepted.
examples:
- gloo-openai-text-embedding-3-small
input:
title: Input
description: >-
The text to embed: a non-empty string, or an array of 1 to 2048
non-empty strings. Each string must fit within the model's
`max_input_tokens`. Arrays of token IDs are not accepted.
oneOf:
- type: string
minLength: 1
pattern: \S
- type: array
items:
type: string
minLength: 1
pattern: \S
minItems: 1
maxItems: 2048
examples:
- - In the beginning was the Word.
- Love is patient.
encoding_format:
type: string
enum:
- float
- base64
title: Encoding Format
description: >-
How each vector is encoded. `float` returns an array of numbers;
`base64` returns the little-endian float32 bytes as a base64 string.
When omitted, the provider's default applies (an array of floats).
dimensions:
type: integer
exclusiveMinimum: 0
title: Dimensions
description: >-
Number of dimensions to return, for models that support shortened
embeddings (such as the OpenAI `text-embedding-3` models). Omit it
for other models.
user:
type: string
title: User
description: Accepted for OpenAI SDK compatibility and ignored.
EmbeddingsResponse:
type: object
title: EmbeddingsResponse
required:
- object
- data
- model
properties:
object:
type: string
const: list
data:
type: array
items:
$ref: '#/components/schemas/Embedding'
description: One embedding per input string, in input order.
model:
type: string
description: The `model` value exactly as you sent it.
usage:
type: object
description: >-
Tokens billed for the request. Omitted if the provider reported no
usage.
properties:
prompt_tokens:
type: integer
total_tokens:
type: integer
example:
object: list
data:
- object: embedding
index: 0
embedding:
- 0.4155
- 0.7861
- -0.2673
- 0.3721
- object: embedding
index: 1
embedding:
- -0.0755
- -0.301
- -0.6606
- 0.6841
model: gloo-openai-text-embedding-3-small
usage:
prompt_tokens: 11
total_tokens: 11
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
AiErrorResponse:
type: object
title: AiErrorResponse
description: >-
AI API error response with existing detail field plus enriched error
metadata.
required:
- detail
- error
properties:
detail:
description: Existing endpoint-specific error detail. May be a string or object.
error:
$ref: '#/components/schemas/AiError'
additionalProperties: true
Embedding:
type: object
title: Embedding
required:
- object
- index
- embedding
properties:
object:
type: string
const: embedding
index:
type: integer
description: Position of the corresponding string in `input`.
embedding:
description: >-
The vector: an array of floats, or a base64 string when
`encoding_format` is `base64`.
oneOf:
- type: array
items:
type: number
- type: string
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
AiError:
type: object
title: AiError
description: >-
Standard AI API error object emitted by global provider/model error
handlers.
required:
- message
- type
- code
- name
- category
- description
- fault
- retryable
- trace_id
properties:
message:
type: string
description: Request-specific customer-facing error message.
type:
type: string
description: Stable wire-format error type.
code:
type: integer
description: Stable numeric internal error code.
name:
type: string
description: Stable symbolic error code name.
category:
type: string
enum:
- client_error
- provider_error
- platform_error
description: Error category derived from the numeric code range.
description:
type: string
description: Stable one-sentence explanation of what the error code means.
fault:
type: string
enum:
- client
- provider
- internal
description: System responsible for the failure.
retryable:
type: boolean
description: Whether retrying the same request may succeed.
trace_id:
type:
- string
- 'null'
description: Sentry trace identifier when available.
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: api-key
x-default:
description: >-
Bearer authentication header of the form Bearer ``, where
`` is your [API key](/studio/manage-api-credentials).
````