Embeddings API

OpenAI-compatible embedding endpoint for generating vector representations of text.

Endpoint

POST /api/client/v1/embeddings

Request

{
  "model": "text-embedding-ada-002",
  "input": "Hello world",
  "request_id": "optional-correlation-id"
}

Parameters

Field	Type	Required	Description
model	string	Yes	Embedding model key
input	string | string[]	Yes	Text to embed (single or batch)
request_id	string	No	Client-provided correlation ID

Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0092, 0.0156, ...]
    }
  ],
  "model": "text-embedding-ada-002",
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  },
  "request_id": "req_abc123"
}

Batch Input

{
  "model": "text-embedding-ada-002",
  "input": ["Hello world", "How are you?", "Embedding example"]
}

Returns multiple embedding objects indexed by position.

Errors

Status	Description
400	Missing model or input
401	Invalid API token
500	Model not found
500	Model is not configured for embeddings
429	Rate limit or quota exceeded
500	Provider error (circuit breaker / upstream)

Example

curl -X POST https://gateway.example.com/api/client/v1/embeddings \
  -H "Authorization: Bearer cpeer_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "Hello world"
  }'