Gateway Quickstart

Make your first request through the AI Gateway in under 5 minutes

Get started with the AI Gateway and access 100+ LLM models through a single OpenAI-compatible API.

1. Get your Helicone API key

   1. Sign up for Helicone (free account)
   2. Navigate to API Keys
   3. Click Create API Key
   4. Copy your key and save it as HELICONE_API_KEY in your environment

   Your Helicone API key is all you need - no provider API keys required when using credits.

2. Install the OpenAI SDK

   The gateway uses the OpenAI SDK format, so install it if you haven’t already:

   npm

   npm install openai
   
3. Make your first request

   Change just two lines from standard OpenAI code:

   TypeScript

   import { OpenAI } from "openai";
   
   const client = new OpenAI({
     baseURL: "https://ai-gateway.helicone.ai",
     apiKey: process.env.HELICONE_API_KEY,
   });
   
   const response = await client.chat.completions.create({
     model: "gpt-4o-mini",
     messages: [
       { role: "user", content: "What is the capital of France?" }
     ],
   });
   
   console.log(response.choices[0].message.content);
   

   Python

   from openai import OpenAI
   import os
   
   client = OpenAI(
       base_url="https://ai-gateway.helicone.ai",
       api_key=os.getenv("HELICONE_API_KEY")
   )
   
   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)
   

   cURL

   curl https://ai-gateway.helicone.ai/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $HELICONE_API_KEY" \
     -d '{
       "model": "gpt-4o-mini",
       "messages": [
         { "role": "user", "content": "What is the capital of France?" }
       ]
     }'
   
4. View your request in the dashboard

   Within seconds, your request appears in the Helicone Dashboard:

   • See the full request and response
   • Track costs and token usage
   • Monitor latency and performance
   • Add custom metadata and properties

   

Try Different Models

The gateway supports 100+ models. Just change the model name:

OpenAI GPT-4o

model: "gpt-4o"

Browse all available models →

Using Your Own API Keys (BYOK)

Want to use your own provider API keys instead of credits?

1. Add your provider keys

   1. Go to Provider Settings
   2. Select your provider (OpenAI, Anthropic, etc.)
   3. Add your API key
   4. Save
2. Make requests as usual

   No code changes needed - the gateway automatically uses your keys:

   const response = await client.chat.completions.create({
     model: "gpt-4o-mini",
     messages: [{ role: "user", content: "Hello!" }],
   });
   // Uses your OpenAI API key automatically
   

When you provide your own keys, the gateway tries them first. If they fail, it automatically falls back to Helicone’s managed keys (credits) for reliability.

Common Use Cases

Streaming Responses

The gateway fully supports streaming:

const stream = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Tell me a story" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Multi-provider Access

Switch providers by specifying them in the model string:

// Use Claude through Anthropic's API
model: "claude-sonnet-4/anthropic"

// Use Claude through AWS Bedrock
model: "claude-sonnet-4/bedrock"

// Use Claude through Vertex AI
model: "claude-sonnet-4/vertex"

// Let gateway choose the best provider
model: "claude-sonnet-4"

Automatic Fallbacks

Specify fallback chains for maximum reliability:

const response = await client.chat.completions.create({
  model: "gpt-4o-mini/openai,gpt-4o-mini/azure,gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }],
});
// Tries OpenAI → Azure → All other providers

Learn more about fallback strategies →

Next Steps

Provider Routing

Learn how the gateway intelligently routes requests

Automatic Fallbacks

Build resilient apps with provider failover

Prompt Management

Deploy prompts without code changes

Advanced Features

Explore caching, rate limits, and security

Troubleshooting

Authentication failed (401)

• Check that you’re using your Helicone API key, not an OpenAI key
• Verify the key is set correctly in your environment: echo $HELICONE_API_KEY
• Generate a new key at API Keys

Model not found

• Check the Model Registry for correct model names
• Model names are case-sensitive: use gpt-4o-mini not GPT-4o-mini
• Some models require BYOK (e.g., Azure-specific deployments)

Request not showing in dashboard

• Requests appear within 2-3 seconds (check for errors in your code)
• Verify you’re using https://ai-gateway.helicone.ai as the base URL
• Check you’re logged into the correct Helicone account

Insufficient credits error

• Add credits at Billing Settings
• Or add your provider API keys at Provider Settings