API reference

Embeddings

Turn text into vectors for similarity workflows. Select an embedding-capable model and keep vector dimensions consistent in your own index.

How it fits together

01Create embedding vectors for one or more inputs

Select an action to see its complete inputs, request, response, and status codes.

Create embedding vectors for one or more inputs

POST/v1/embeddings

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

Content typeapplication/json

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`Idempotency-Key`	Header	string	Optional	Supported	Replay key for an admitted run; a repeat returns the first result.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.
`dimensions`	Body	integer	Optional	Conditional	Output vector width. Accepted only on a model whose catalog entry publishes that width; every other value is refused before any provider call.
`encoding_format`	Body	string	Optional	Supported	float or base64.
`input`	Body	string \| array<value>	Required	Supported	A string, an array of strings, a token array, or an array of token arrays. Batch size and per-item and total token counts are bounded by service configuration.
`model`	Body	string	Required	Supported	Public logical embedding model ID.
`user`	Body	string	Optional	Supported	Provider abuse-monitoring user identifier.

A compatible model and provider route are required for conditional fields.

Request

curl -X POST 'https://api.mahvashai.ir/v1/embeddings' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "model": "<embedding-model-from-GET-/v1/models>",
  "input": "A short document to embed."
}'

Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.012,
        -0.021,
        0.037
      ]
    }
  ],
  "model": "<embedding-model-id>",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	Create embedding vectors for one or more inputs.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
402	The account cannot authorize the request cost.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.
502	The selected provider returned an invalid or failed response.
503	A dependency is temporarily unavailable.