Skip to navigation
IntegrationIntegrationsLLM SDKs

Helicone (gateway)

Use Respan Gateway when you want to replace Helicone Gateway routing with Respan request logs, provider routing, fallbacks, prompt management, and metadata. This gateway-only path does not require HeliconeManualLogger, a Helicone API key, or a Respan Helicone instrumentor.

For applications that keep sending Manual Logger records to Helicone and want to trace those records in Respan, use the Helicone tracing setup instead.

Create an account at platform.respan.ai, grab an API key, and add credits or a provider key.

Setup

1

Install an OpenAI-compatible client

pip install openai
2

Set environment variables

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

No HELICONE_API_KEY or provider API key is required when billing through Respan Gateway credits. For BYOK, configure the provider credential in Respan.

When migrating an existing Helicone proxy client, remove Helicone-Auth, Helicone-Target-Url, Helicone-Target-Provider, and any other Helicone-specific headers. Replace the client API key with RESPAN_API_KEY before changing the base URL so a Helicone secret is never sent to Respan.

3

Point the client to Respan Gateway

import os
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["RESPAN_API_KEY"],
    base_url=os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api"),
)
response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Say hello in three languages."}],
)
print(response.choices[0].message.content)
4

View your request log

Open the Logs page to inspect the routed request, response, model, usage, latency, and gateway metadata.

Switch models

Keep the same OpenAI-compatible client and change the model ID to route to another supported model.

client.chat.completions.create(model="gpt-5.5", messages=messages)
client.chat.completions.create(
    model="anthropic/claude-sonnet-4-5-20250929",
    messages=messages,
)
client.chat.completions.create(
    model="gemini/gemini-3.5-flash",
    messages=messages,
)

See the full model list.

Respan parameters

Attach identifiers, configure fallbacks, and add metadata with Respan request fields. Python’s OpenAI SDK accepts them through extra_body; in TypeScript, extend the OpenAI request type and send the fields at the request-body root.

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Help with my order."}],
    extra_body={
        "customer_identifier": "user_123",
        "thread_identifier": "conversation_456",
        "fallback_models": ["gpt-5-mini"],
        "metadata": {"plan": "pro"},
    },
)

See Respan params & metadata for the full list.

Keep Helicone Manual Logger in parallel

You can call Respan Gateway inside a Helicone Manual Logger callback, but the two systems record different telemetry for the same model call:

  • Respan Gateway automatically creates a request log for the routed call.
  • HeliconeInstrumentor creates a separate canonical span for the Helicone manual-log lifecycle.
  • Helicone continues receiving its own Manual Logger record.

Use this dual-observability setup only when those separate records are intentional. Otherwise, use the gateway-only setup on this page or the Manual Logger tracing setup, not both.