Embeddings

Create vector embeddings with type: "embedding" on the same External API endpoint.

Only available when supported_features.embedding is true and models appear under embedding_providers in GET https://ai.lumowp.com/api/external/ai.

Request

POST /api/external/ai
Content-Type: application/json
X-API-Key: your-api-key-here

Single input

{
  "type": "embedding",
  "model": "text-embedding-3-small",
  "input": "semantic search example"
}

Batch input

{
  "type": "embedding",
  "model": "text-embedding-3-small",
  "input": ["first document", "second document"]
}

Parameters

Parameter	Type	Required	Description
type	string	Yes	Must be "embedding"
model	string	Yes	Embedding-capable model from discovery
input	string or string[]	Yes	Text to embed
provider	string	No	Must match the resolved model provider if set
stream	boolean	No	Must be omitted or false

Success response

{
  "success": true,
  "data": {
    "embeddings": [[0.012, -0.044, 0.091]],
    "model": "text-embedding-3-small",
    "provider": "openai",
    "dimensions": 1536,
    "tokens_used": 8,
    "remaining_tokens": 99120
  }
}

Exact fields can include usage/cost helpers similar to text responses. Prefer reading keys from a live successful response while integrating.

Limits

See limits.max_embedding_inputs from GET https://ai.lumowp.com/api/external/ai. Oversized batches return 400 / 413 depending on the failure mode.

Discovery tip

curl -X GET "https://ai.lumowp.com/api/external/ai" \
  -H "X-API-Key: $LUMO_AI_API_KEY"

Then pick a model from embedding_providers[].models[] (check dimensions when present).

OpenAI SDK compatibility

POST /v1/embeddings accepts the standard model, input, dimensions, encoding_format, and user fields. encoding_format may be float or base64. Custom dimensions are forwarded to the supplier and succeed only when that model/provider supports them; the gateway verifies the returned vector length instead of silently truncating vectors.

result = client.embeddings.create(
    model="your-embedding-model",
    input=["first chunk", "second chunk"],
    encoding_format="float",
    dimensions=1024,
)