POST /v1/embeddings

POST https://gateway.roadie.paroaria.ai/v1/embeddings
Authorization: Bearer rd_sk_prod_…
Content-Type: application/json

Generate embedding vectors for one or more inputs. Only embeddings-capable models are eligible; a non-embeddings model is rejected 404 not_found_error (embeddings_not_supported).

Authentication

Authenticated with a secret key (rd_sk_…) or a client token. A client token must carry the ai.embed scope, or the request fails 403 permission_error (insufficient_scope). A publishable key (rd_pk_…) is mint-only and is rejected 403 (publishable_key_mint_only).

Request body

Field	Type	Required	Notes
`model`	string	yes	An embeddings-capable model (e.g. `openai/text-embedding-3-small`) or an alias resolving to one.
`input`	string \| string[]	yes	One non-empty string, or a non-empty batch of strings.
`dimensions`	integer	no	Requested output dimensionality, where the model supports it.
`user`	`{ id, plan? }`	no	The end user to attribute and limit.
`metadata`	object<string,string>	no	Free-form string tags.
`provider_options`	object	no	Per-provider passthrough options, keyed by provider id.

Example

{
  "model": "openai/text-embedding-3-small",
  "input": ["The quick brown fox.", "A second document to embed."]
}

Response

200 OK — one vector per input, in order:

{
  "id": "req_01J8…",
  "model": "openai/text-embedding-3-small",
  "provider": "openai",
  "data": [
    { "index": 0, "embedding": [0.0123, -0.0456, "…"] },
    { "index": 1, "embedding": [0.0789, -0.0021, "…"] }
  ],
  "usage": { "input_tokens": 14, "output_tokens": 0, "total_tokens": 14, "source": "provider" },
  "cost": { "estimated_usd": 0.0000007 },
  "gateway": { "fallback_used": false, "retries": 0, "latency_ms": 88 }
}

The response id equals the X-Request-Id response header. Embeddings support the same idempotency, retries, limits, budgets, and error envelope as /v1/chat.

Introduction

Data plane

OpenAI-compatible

Control plane

Errors

POST /v1/embeddings

Authentication

Request body

Example

Response

​Authentication

​Request body

​Example

​Response

Authentication

Request body

Example

Response