Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Helicone/helicone/llms.txt

Use this file to discover all available pages before exploring further.

Integrate Helicone with Vercel AI SDK to track and monitor your AI applications with streaming support and edge runtime compatibility.

​
Quick Start

Integrate Helicone with Vercel AI SDK by configuring the provider with Helicone’s base URL: 
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';

export async function POST(req: Request) {
  const { messages } = await req.json();

  // Configure OpenAI provider with Helicone
  const result = await streamText({
    model: openai('gpt-4o-mini', {
      baseURL: 'https://oai.helicone.ai/v1',
      headers: {
        'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`,
      },
    }),
    messages,
  });

  return result.toDataStreamResponse();
}

​
Installation

npm install ai @ai-sdk/openai

​
Configuration

​
Environment Variables

Set up your environment:
.env.local
OPENAI_API_KEY=sk-...
HELICONE_API_KEY=sk-helicone-...

​
Provider Configuration

Configure different providers: 
import { openai } from '@ai-sdk/openai';

const model = openai('gpt-4o-mini', {
  baseURL: 'https://oai.helicone.ai/v1',
  headers: {
    'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`,
  },
});

​
Streaming Support

Helicone fully supports streaming with Vercel AI SDK:

​
Text Streaming

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: openai('gpt-4o-mini', {
      baseURL: 'https://oai.helicone.ai/v1',
      headers: {
        'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`,
      },
    }),
    messages,
  });

  // Stream response to client
  return result.toDataStreamResponse();
}

​
Object Streaming

import { streamObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const schema = z.object({
  recipe: z.object({
    name: z.string(),
    ingredients: z.array(z.string()),
    steps: z.array(z.string()),
  }),
});

export async function POST(req: Request) {
  const result = await streamObject({
    model: openai('gpt-4o-mini', {
      baseURL: 'https://oai.helicone.ai/v1',
      headers: {
        'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`,
      },
    }),
    schema,
    prompt: 'Generate a recipe for chocolate chip cookies',
  });

  return result.toTextStreamResponse();
}

​
Client-Side Integration

Use Helicone with client-side Vercel AI SDK hooks:
app/page.tsx
'use client';

import { useChat } from 'ai/react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: '/api/chat', // Points to your API route with Helicone
  });

  return (
    <div>
      {messages.map((message) => (
        <div key={message.id}>
          {message.role}: {message.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}

​
Advanced Features

​
Session Tracking

Track multi-turn conversations: 
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { v4 as uuidv4 } from 'uuid';

export async function POST(req: Request) {
  const { messages } = await req.json();
  const sessionId = uuidv4();

  const result = await streamText({
    model: openai('gpt-4o-mini', {
      baseURL: 'https://oai.helicone.ai/v1',
      headers: {
        'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`,
        'Helicone-Session-Id': sessionId,
        'Helicone-Session-Name': 'Chat Application',
        'Helicone-Session-Path': '/api/chat',
      },
    }),
    messages,
  });

  return result.toDataStreamResponse();
}

​
User Tracking

Track requests by user: 
const result = await streamText({
  model: openai('gpt-4o-mini', {
    baseURL: 'https://oai.helicone.ai/v1',
    headers: {
      'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`,
      'Helicone-User-Id': 'user-123',
    },
  }),
  messages,
});

​
Custom Properties

Add metadata to your requests: 
const result = await streamText({
  model: openai('gpt-4o-mini', {
    baseURL: 'https://oai.helicone.ai/v1',
    headers: {
      'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`,
      'Helicone-Property-Environment': 'production',
      'Helicone-Property-App': 'chatbot',
      'Helicone-Property-Version': 'v1.2.0',
    },
  }),
  messages,
});

​
Tool Calls

Track tool usage: 
import { streamText, tool } from 'ai';
import { z } from 'zod';

const result = await streamText({
  model: openai('gpt-4o-mini', {
    baseURL: 'https://oai.helicone.ai/v1',
    headers: {
      'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`,
    },
  }),
  messages,
  tools: {
    weather: tool({
      description: 'Get the weather in a location',
      parameters: z.object({
        location: z.string().describe('The location to get the weather for'),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 72,
      }),
    }),
  },
});

// Helicone tracks tool calls automatically

​
Edge Runtime Support

Helicone works seamlessly with Edge Runtime:
app/api/chat/route.ts
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

export const runtime = 'edge';

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: openai('gpt-4o-mini', {
      baseURL: 'https://oai.helicone.ai/v1',
      headers: {
        'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`,
      },
    }),
    messages,
  });

  return result.toDataStreamResponse();
}

​
Troubleshooting

Make sure to pass headers in the provider configuration:
const model = openai('gpt-4o-mini', {
  baseURL: 'https://oai.helicone.ai/v1',
  headers: {  // ✓ Correct
    'Helicone-Auth': `Bearer ${process.env.HELICONE_API_KEY}`,
  },
});
Ensure you’re using .toDataStreamResponse() or .toTextStreamResponse():
const result = await streamText(...);
return result.toDataStreamResponse(); // ✓ Correct
Helicone is fully compatible with Edge runtime. If you encounter issues:
  1. Verify environment variables are set in your hosting platform
  2. Check that runtime = 'edge' is exported
  3. Ensure you’re using supported dependencies

​
Examples from Source

See real integration examples:

​
Next Steps

Sessions

Track multi-turn conversations

Custom Properties

Add metadata to requests

User Analytics

Analyze user behavior

Dashboard

Monitor streaming performance

Build docs developers (and LLMs) love

Get started for freeTalk to us