Embeddings

The /v1/embeddings endpoint generates dense numerical vector representations of text strings, enabling semantic search, retrieval-augmented generation (RAG), vector similarity search, and automated text clustering. Operating with full OpenAI API wire compatibility, nRouter lets developers route embedding requests across providers like OpenAI, Cohere, Voyage, and Google Vertex AI with unified key governance, automated cloud failover, and zero-markup pricing.

POST https://api.nrouter.ai/v1/embeddings

Architectural Role & Lifecycle

Embedding generation is typically the highest-throughput endpoint in modern AI pipelines, feeding real-time RAG ingestion and vector indexing workloads. nRouter optimizes this path for minimum overhead:

1. Phase 1: In-Memory Virtual Key Validation: Authenticates the sk-nrouter-... bearer token against memory structures in microseconds and validates model ACLs.
2. Phase 2: High-Throughput TPM & RPM Checks: Validates tenant sliding-window rate limits, accommodating massive indexing batches without blocking.
3. Phase 3: Input Screening & Preflight Safety: Evaluates input strings for malicious injection payloads. If a safety threshold is crossed, the call is rejected with HTTP 400 (x-nr-guardrails: blocked).
4. Phase 4: Token-Level Credit Reservation: Calculates the exact input token count across the batch and reserves the corresponding credit balance. Blocked requests cost $0.
5. Upstream Execution & Response Stamping: Dispatches the batch to the upstream provider cloud. Upon successful return, exact spend is settled and edge telemetry headers are stamped on the response.

Request Parameters

The request body must be a JSON object:

Response Payloads

Standard Embedding Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        -0.0069292834,
        -0.005336422,
        -0.024047505,
        0.008456123,
        0.012398451
      ]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

Headers Reference

Inbound Request Headers

Outbound Response Headers

SDK Code Examples

import { nRouter } from "@nrouter_ai/sdk";

const client = new nRouter({
  apiKey: process.env.NROUTER_API_KEY,
});

const embedding = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: ["Semantic search query", "Vector database document chunk"],
  dimensions: 512,
});

console.log(`Generated ${embedding.data.length} vectors.`);
console.log(`Vector dimensions: ${embedding.data[0].embedding.length}`);
console.log(`Total tokens: ${embedding.usage.total_tokens}`);

Error Codes & Troubleshooting

{
  "error": {
    "type": "invalid_request",
    "message": "Input text exceeds maximum token context length of 8192.",
    "code": "input_too_large"
  }
}

curl -X POST "https://example.com/v1/embeddings" \  -H "Content-Type: application/json" \  -d '{    "model": "text-embedding-3-small",    "input": "The quick brown fox jumps over the lazy dog."  }'

{  "object": "list",  "model": "text-embedding-3-small",  "data": [    {      "object": "embedding",      "index": 0,      "embedding": [        0.0023,        -0.009,        0.015      ]    }  ],  "usage": {    "prompt_tokens": 5,    "total_tokens": 5  }}