Use llama_index.llms.openai.OpenAI. Official constructor knobs are api_base and default_headers. LlamaIndex passes those through as the OpenAI SDK base_url. Set api_base to https://gateway.traccia.ai/openai/v1.

What this Gateway accepts

OpenAI: POST /openai/v1/chat/completions and GET /openai/v1/models, also under /agents/{agent_id}/v1 and /openai/agents/{agent_id}/v1 with the agent ID in the path. Anthropic: POST /anthropic/v1/messages. Gemini Developer API: POST /google/{v1beta|v1}/models/{model}:generateContent and :streamGenerateContent. Embeddings, the OpenAI Responses API, Assistants, Azure OpenAI paths, Vertex AI paths, and Anthropic Batches are not this Gateway. Those requests 404.

Headers

Header	Value
X-Traccia-Api-Key	Workspace key from Settings → API Keys
X-Traccia-Agent-Id	Same Agent ID you would pass to init

Keep the provider API key on the client. The Gateway forwards it and does not store it. Missing Traccia key returns 401. Missing agent ID returns 400. For OpenAI-compatible clients that allow only one extra header, such as n8n, put the agent ID in the URL instead: https://gateway.traccia.ai/agents/<agent-id>/v1. If both are set, the header wins.

OpenAI LLM

python

import os
from llama_index.llms.openai import OpenAI

llm = OpenAI(
    model="gpt-4o-mini",
    api_key=os.environ["OPENAI_API_KEY"],
    api_base="https://gateway.traccia.ai/openai/v1",
    default_headers={
        "X-Traccia-Api-Key": os.environ["TRACCIA_API_KEY"],
        "X-Traccia-Agent-Id": "billing-bot",
    },
)

response = llm.complete("hello")

Do not put /chat/completions in api_base. The OpenAI client appends that path.

What 404s

OpenAIResponses Is Not This Gateway

LlamaIndex's OpenAIResponses class posts to the Responses API. This Gateway does not implement /v1/responses. Stay on the Chat Completions OpenAI class.

Gateway: LlamaIndex

Headers

OpenAI LLM

What 404s

Next Steps

Gateway Overview

Policies