LlamaIndex quickstart: n4n.ai API key setup

Connecting LlamaIndex to a multi-provider LLM gateway saves you from vendor lock-in and rate-limit headaches. This llamaindex n4n.ai api key setup tutorial gets you from an empty directory to a working RAG query against the n4n.ai OpenAI-compatible endpoint in about ten minutes.

Prerequisites

This llamaindex n4n.ai api key setup tutorial assumes you already have a few things in place:

Python 3.10 or newer installed locally
pip and virtual environment familiarity
An n4n.ai API key from your dashboard (treat it like any other secret)
A shell terminal and basic editor

If you don’t have the key yet, generate one and keep it handy. We’ll load it from an environment variable rather than hard-coding it.

Step 1: Scaffold the project

Create a clean working directory and a virtual environment to avoid polluting your global Python:

mkdir llamaindex-n4n && cd llamaindex-n4n
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

An isolated environment keeps dependency conflicts away when you later add vector stores or observability.

Step 2: Install LlamaIndex and helpers

Install the core package plus python-dotenv for env loading. LlamaIndex splits LLM and embedding clients into sub-packages, but the meta llama-index install pulls the OpenAI-compatible clients we need.

pip install llama-index python-dotenv

Expect a few dozen dependencies to resolve. If you’re on a fresh venv, this takes under a minute.

Step 3: Store the API key

Write the key to a .env file. Never commit this file to git; add it to .gitignore immediately.

echo "N4N_API_KEY=sk-your-actual-key" > .env
echo ".env" >> .gitignore

Loading it in Python takes three lines:

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.environ["N4N_API_KEY"]

Step 4: Configure the LLM and embeddings

LlamaIndex’s OpenAI class speaks the OpenAI REST contract, so pointing it at any OpenAI-compatible gateway is just a base-URL swap. n4n.ai exposes an OpenAI-compatible endpoint that fronts 240+ models with automatic fallback, so we set api_base accordingly and pick a model the gateway supports.

from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

llm = OpenAI(
    api_key=api_key,
    api_base="https://api.n4n.ai/v1",
    model="gpt-4o-mini",
    temperature=0.1,
)

embed_model = OpenAIEmbedding(
    api_key=api_key,
    api_base="https://api.n4n.ai/v1",
    model="text-embedding-3-small",
)

Use temperature=0.1 for deterministic retrieval answers. The embedding model must match the dimension expected by the default VectorStoreIndex (1536 for this model). If you switch embedding models, verify dimension compatibility before indexing.

Step 5: Build a minimal corpus

We’ll skip file loaders and use in-memory Document objects to keep the focus on wiring. Two sentences are enough to prove retrieval works.

from llama_index.core import Document, VectorStoreIndex

docs = [
    Document(text="The gateway routes requests to multiple providers with per-token metering."),
    Document(text="LlamaIndex abstracts indexing and retrieval for RAG pipelines."),
]

index = VectorStoreIndex.from_documents(
    docs,
    llm=llm,
    embed_model=embed_model,
)

from_documents chunks, embeds, and builds an in-memory vector index. For production you’d swap to a persistent store like pgvector, but the API key setup is identical.

Step 6: Query the index

Create a query engine and ask a question that requires the first document:

query_engine = index.as_query_engine()
response = query_engine.query("What does the gateway do with tokens?")
print(str(response))

Expected output:

The gateway routes requests to multiple providers with per-token metering.

If you see a raw API error instead, jump to troubleshooting below.

Full runnable script

Here is the whole flow in one file (main.py) for copy-paste verification:

import os
from dotenv import load_dotenv
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.core import Document, VectorStoreIndex

load_dotenv()
api_key = os.environ["N4N_API_KEY"]

llm = OpenAI(
    api_key=api_key,
    api_base="https://api.n4n.ai/v1",
    model="gpt-4o-mini",
    temperature=0.1,
)
embed_model = OpenAIEmbedding(
    api_key=api_key,
    api_base="https://api.n4n.ai/v1",
    model="text-embedding-3-small",
)

docs = [
    Document(text="The gateway routes requests to multiple providers with per-token metering."),
    Document(text="LlamaIndex abstracts indexing and retrieval for RAG pipelines."),
]
index = VectorStoreIndex.from_documents(docs, llm=llm, embed_model=embed_model)

resp = index.as_query_engine().query("What does the gateway do with tokens?")
print(str(resp))

Run it:

python main.py

You should get the single sentence answer. That confirms the llamaindex n4n.ai api key setup tutorial produced a live connection.

Why use a gateway with LlamaIndex

Direct OpenAI calls hard-code a single vendor into your stack. When that vendor throttles you or deprecates a model, you edit client code and redeploy. A gateway that speaks the OpenAI protocol lets you change the api_base and model strings only.

The gateway also centralizes per-token metering, so you get one usage report across providers instead of stitching billing dashboards. For a RAG system that issues embedding, completion, and rerank calls, that visibility is the difference between guessing and knowing your unit economics.

Fallbacks matter too. If a primary provider returns 429s, a correctly configured gateway routes to a secondary without your application noticing. LlamaIndex doesn’t need to know which backend served the token; it just needs a compliant response.

Passing routing and cache hints

Gateways that honor client routing directives let you steer traffic without changing models. In practice this means extra headers or a qualified model string. The gateway forwards provider cache-control hints, so if you mark a prompt as cacheable, the upstream provider’s caching semantics are preserved.

With LlamaIndex’s OpenAI client you can inject headers by wrapping the underlying client, but the simpler path is to keep routing rules server-side. Put staging vs. production traffic in different gateway keys, and let the gateway map them to providers. Your Python code stays boring, which is exactly what you want.

Troubleshooting

401 Unauthorized — Your N4N_API_KEY is missing or malformed. Print os.environ["N4N_API_KEY"] to verify loading.

ConnectionError — Check the api_base URL. It must point at the gateway’s /v1 path, not a dashboard root.

Embedding dimension mismatch — If you change text-embedding-3-small to a different model, the vector store may reject inserts. Match the model to the index’s expected dim.

Rate limits — Gateways mitigate this with fallback, but client-side retries with backoff still help under bursty traffic.

Next steps

The llamaindex n4n.ai api key setup tutorial stops at a minimal proof. From here, add a real loader (SimpleDirectoryReader), persist the index, and pass routing hints through your gateway’s documented mechanism if needed. You now have a provider-agnostic RAG loop that won’t break when one model vendor has a bad day.