> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/integrations/gateway/helicone/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/_mcp/server.

# Helicone (gateway)

> Replace Helicone Gateway routing with the OpenAI-compatible Respan 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](/docs/integrations/helicone) instead.

#### Set up Respan Gateway

Create an account at [platform.respan.ai](https://platform.respan.ai), grab an [API key](https://platform.respan.ai/platform/api/api-keys), and add [credits](https://platform.respan.ai/platform/api/billing) or a [provider key](https://platform.respan.ai/platform/api/providers).

## Setup

#### Install an OpenAI-compatible client

**`Python`**

```bash Python
pip install openai
```

**`TypeScript`**

```bash TypeScript
npm install openai
```

#### Set environment variables

```bash
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.

> **Warning**
>
> 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.

#### Point the client to Respan Gateway

**`Python`**

```python Python
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)
```

**`TypeScript`**

```typescript TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.RESPAN_API_KEY,
  baseURL: process.env.RESPAN_BASE_URL ?? "https://api.respan.ai/api",
});

const response = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Say hello in three languages." }],
});
console.log(response.choices[0]?.message.content);
```

#### View your request log

Open the [Logs page](https://platform.respan.ai/platform/requests) 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.

**`Python`**

```python Python
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,
)
```

**`TypeScript`**

```typescript TypeScript
await client.chat.completions.create({ model: "gpt-5.5", messages });
await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4-5-20250929",
  messages,
});
await client.chat.completions.create({
  model: "gemini/gemini-3.5-flash",
  messages,
});
```

See the [full model list](https://platform.respan.ai/platform/models).

## 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.

**`Python`**

```python Python
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"},
    },
)
```

**`TypeScript`**

```typescript TypeScript
type RespanChatRequest =
  OpenAI.Chat.ChatCompletionCreateParamsNonStreaming & {
    customer_identifier?: string;
    thread_identifier?: string;
    fallback_models?: string[];
    metadata?: Record<string, unknown>;
  };

const request: RespanChatRequest = {
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Help with my order." }],
  customer_identifier: "user_123",
  thread_identifier: "conversation_456",
  fallback_models: ["gpt-5-mini"],
  metadata: { plan: "pro" },
};

const response = await client.chat.completions.create(request);
```

See [Respan params & metadata](/docs/documentation/features/gateway/respan-params) 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](/docs/integrations/helicone), not both.

> Replace Helicone Gateway routing with the OpenAI-compatible Respan Gateway.