OpenAI Integration

Integrate Helicone with OpenAI for complete observability

Integrate Helicone with OpenAI to track, monitor, and optimize your GPT-4, GPT-3.5, and other OpenAI model usage.

Quick Start

Integrate Helicone with OpenAI by changing your base URL and adding your API key:

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url="https://oai.helicone.ai/v1",
    default_headers={
        "Helicone-Auth": f"Bearer {os.getenv('HELICONE_API_KEY')}",
    },
)

# Use the client normally
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "What is the capital of France?"}
    ],
)

print(response.choices[0].message.content)

Installation

Python

pip install openai

Node.js

npm install openai

Configuration

Basic Setup

Only two changes are needed:

1. Change base URL to https://oai.helicone.ai/v1
2. Add Helicone-Auth header with your API key

Environment Variables

Set up your environment:

.env

OPENAI_API_KEY=sk-...
HELICONE_API_KEY=sk-helicone-...

Features

Streaming Support

Helicone fully supports streaming responses:

Python

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Write a story"}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Enable include_usage: true in stream_options to capture token usage for streaming requests.

Function Calling

Track function calls and tool usage:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state",
                    },
                },
                "required": ["location"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    tools=tools,
)

# Helicone automatically logs function calls

Vision Models

Log image inputs with GPT-4 Vision:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg",
                    },
                },
            ],
        }
    ],
)

# Helicone tracks image assets automatically

Caching

Enable caching to reduce costs and latency:

Python

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url="https://oai.helicone.ai/v1",
    default_headers={
        "Helicone-Auth": f"Bearer {os.getenv('HELICONE_API_KEY')}",
        "Helicone-Cache-Enabled": "true",
    },
)

Learn more about caching →

Custom Properties

Add metadata to your requests:

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "Helicone-Property-Session": "session-123",
        "Helicone-Property-User": "[e-mail]",
        "Helicone-Property-Environment": "production",
    },
)

Learn more about custom properties →

Advanced Usage

User Tracking

Track requests by user:

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "Helicone-User-Id": "user-123",
    },
)

Session Tracking

Group related requests into sessions:

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "Helicone-Session-Id": "session-abc",
        "Helicone-Session-Name": "Customer Support Chat",
        "Helicone-Session-Path": "/chat/support",
    },
)

Prompt Tracking

Track prompt versions:

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "Helicone-Prompt-Id": "prompt-v2",
    },
)

Azure OpenAI

Helicone also supports Azure OpenAI deployments:

from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://oai.helicone.ai/v1",
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
    api_version="2024-02-01",
    default_headers={
        "Helicone-Auth": f"Bearer {os.getenv('HELICONE_API_KEY')}",
        "Helicone-Target-URL": os.getenv("AZURE_OPENAI_ENDPOINT"),
    },
)

Troubleshooting

Requests not appearing in dashboard

Check these common issues:

1. Verify your HELICONE_API_KEY is correct
2. Ensure base URL is https://oai.helicone.ai/v1 (with /v1)
3. Check that Helicone-Auth header includes Bearer prefix
4. Wait 10-30 seconds for requests to appear

Still not working? Check the response headers for Helicone-Status:

response = client.chat.completions.create(...).with_response()
print(response.response.headers.get('Helicone-Status'))

SSL/Certificate errors

If you encounter SSL errors, ensure you’re using the latest version of the OpenAI SDK:

pip install --upgrade openai

Rate limiting issues

Helicone does not add rate limits. If you’re hitting rate limits, they’re from OpenAI. The error message will be passed through from OpenAI’s API.

Examples from Source

See real integration examples in the repository:

• Basic chat completion
• Async logging
• Custom properties

Next Steps

Custom Properties

Add metadata to your requests

Caching

Enable intelligent caching

Sessions

Track multi-turn conversations

Dashboard

Explore your analytics