> For the complete documentation index, see [llms.txt](https://docs.halfred.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.halfred.ai/02-sdk-integration/03-openai-compatibility.md).

# OpenAI SDK Compatibility

Use Halfred as a drop-in replacement for OpenAI with existing OpenAI SDK libraries. Simply point your client to Halfred's endpoint.

## Why Use OpenAI SDK with Halfred?

* **Ready-to-use SDKs**: Access Halfred through battle-tested OpenAI SDKs available in most common programming languages (Go, PHP, Ruby, Java, .NET, Rust, and more)
* **Drop-in replacement**: Use existing OpenAI code with zero modifications
* **Intelligent model routing**: Benefit from Halfred's profile-based model selection
* **Cost optimization**: Automatic selection of the best model for your use case
* **Multi-provider access**: Access models from OpenAI, Anthropic, Google, and more through a single interface
* **Enhanced reliability**: Built-in failover and load balancing

💡 **Tip**: For the most up-to-date OpenAI SDK documentation and library references for your programming language, visit the [official OpenAI SDK libraries page](https://platform.openai.com/docs/libraries). All official and community-maintained OpenAI SDKs listed there are compatible with Halfred.

## Quick Setup

### Base URL Configuration

Instead of using OpenAI's default endpoint, configure your client to use Halfred's API:

```
Base URL: https://api.halfred.ai/v1/
API Key: Your Halfred API key (starts with "halfred_")
```

## Language-Specific Examples

### JavaScript/TypeScript (Node.js)

#### Installation

```bash
npm install openai
```

#### Configuration

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  baseURL: "https://api.halfred.ai/v1/",
});

// Use exactly like the OpenAI SDK
async function main() {
  const completion = await openai.chat.completions.create({
    model: "standard", // Use Halfred profiles: lite, standard, deepthink, dev
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "What is the capital of France?" },
    ],
    temperature: 0.7,
  });

  console.log(completion.choices[0].message.content);
}

main();
```

#### Environment Variables

```bash
# .env file
OPENAI_API_KEY=halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.halfred.ai/v1/
```

```javascript
import OpenAI from "openai";

// Automatically uses OPENAI_API_KEY and OPENAI_BASE_URL from environment
const openai = new OpenAI();

const completion = await openai.chat.completions.create({
  model: "lite",
  messages: [{ role: "user", content: "Hello!" }],
});
```

### Python

#### Installation

```bash
pip install openai
```

#### Configuration

```python
from openai import OpenAI

client = OpenAI(
    api_key="halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    base_url="https://api.halfred.ai/v1/"
)

# Use exactly like the OpenAI client
completion = client.chat.completions.create(
    model="lite",  # Use Halfred profiles: lite, standard, deepthink, dev
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"}
    ],
    temperature=0.7
)

print(completion.choices[0].message.content)
```

#### Environment Variables

```bash
# .env file or environment
export OPENAI_API_KEY="halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export OPENAI_BASE_URL="https://api.halfred.ai/v1/"
```

```python
from openai import OpenAI

# Automatically uses OPENAI_API_KEY and OPENAI_BASE_URL from environment
client = OpenAI()

completion = client.chat.completions.create(
    model="lite",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

### Go

#### Installation

```bash
go get github.com/sashabaranov/go-openai
```

#### Configuration

```go
package main

import (
    "context"
    "fmt"
    "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx")
    config.BaseURL = "https://api.halfred.ai/v1/"

    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "standard", // Use Halfred profiles
            Messages: []openai.ChatCompletionMessage{
                {
                    Role:    openai.ChatMessageRoleSystem,
                    Content: "You are a helpful assistant.",
                },
                {
                    Role:    openai.ChatMessageRoleUser,
                    Content: "What is the capital of France?",
                },
            },
            Temperature: 0.7,
        },
    )

    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Println(resp.Choices[0].Message.Content)
}
```

### PHP

#### Installation

```bash
composer require openai-php/client
```

#### Configuration

```php
<?php

require_once 'vendor/autoload.php';

use OpenAI;

$client = OpenAI::factory()
    ->withApiKey('halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx')
    ->withBaseUri('https://api.halfred.ai/v1/')
    ->make();

$response = $client->chat()->create([
    'model' => 'standard', // Use Halfred profiles
    'messages' => [
        ['role' => 'system', 'content' => 'You are a helpful assistant.'],
        ['role' => 'user', 'content' => 'What is the capital of France?'],
    ],
    'temperature' => 0.7,
]);

echo $response->choices[0]->message->content;
```

### Ruby

#### Installation

```bash
gem install ruby-openai
```

#### Configuration

```ruby
require 'openai'

client = OpenAI::Client.new(
  access_token: 'halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  uri_base: 'https://api.halfred.ai/v1/'
)

response = client.chat(
  parameters: {
    model: 'lite', # Use Halfred profiles
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'What is the capital of France?' }
    ],
    temperature: 0.7
  }
)

puts response.dig('choices', 0, 'message', 'content')
```

## Model Selection

When using the OpenAI SDK with Halfred, use Halfred's profile names instead of specific model names:

### Available Models

| Model Name  | Halfred Profile | Description                                |
| ----------- | --------------- | ------------------------------------------ |
| `lite`      | LITE            | Fast and cost-effective for simple tasks   |
| `standard`  | STANDARD        | Balanced performance for most applications |
| `deepthink` | DEEPTHINK       | Advanced reasoning for complex tasks       |
| `dev`       | DEV             | Free tier for development and testing      |

### Alternative Model Names

You can also use the prefixed format:

* `halfred-lite`
* `halfred-standard`
* `halfred-deepthink`
* `halfred-dev`

Both formats are equivalent and will work identically.

## Supported Features

### ✅ Fully Supported

* **Chat Completions**: Full support for conversational AI
* **Message Roles**: system, user, assistant roles
* **Temperature**: Control randomness (0.0 to 2.0)
* **Response Format**: JSON mode and structured outputs
* **Token Usage**: Accurate token counting and usage statistics

## Response Format

Halfred returns responses in the exact same format as OpenAI, with additional metadata:

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o",
  "provider": "openai",
  "profile": "standard",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}
```

### Additional Fields

Halfred adds these extra fields to the standard OpenAI response:

* `provider`: The underlying AI provider used (e.g., "openai", "anthropic")
* `profile`: The Halfred profile that was selected

## Migration from OpenAI

### Step 1: Update Configuration

Replace your OpenAI configuration:

```javascript
// Before (OpenAI)
const openai = new OpenAI({
  apiKey: "sk-your-openai-key",
});

// After (Halfred)
const openai = new OpenAI({
  apiKey: "halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  baseURL: "https://api.halfred.ai/v1/",
});
```

### Step 2: Update Model Names

Replace specific OpenAI model names with Halfred profiles:

```javascript
// Before (OpenAI)
model: "gpt-4o";
model: "gpt-3.5-turbo";

// After (Halfred)
model: "standard"; // Automatically selects best model
model: "lite"; // For cost-effective tasks
```

### Step 3: Test Your Integration

Your existing code should work without any other changes. Test with a simple completion:

```javascript
const completion = await openai.chat.completions.create({
  model: "dev",
  messages: [{ role: "user", content: "Hello, world!" }],
});

console.log(completion.choices[0].message.content);
```

## Best Practices

### Model Selection Strategy

```javascript
// For simple tasks (cost-effective)
const quickResponse = await openai.chat.completions.create({
  model: "lite",
  messages: [{ role: "user", content: "Summarize this in one sentence." }],
});

// For most applications (balanced)
const standardResponse = await openai.chat.completions.create({
  model: "standard",
  messages: [{ role: "user", content: "Explain quantum computing." }],
});

// For complex reasoning (high-quality)
const deepResponse = await openai.chat.completions.create({
  model: "deepthink",
  messages: [{ role: "user", content: "Analyze this complex business scenario..." }],
});

// For development/testing (free)
const testResponse = await openai.chat.completions.create({
  model: "dev",
  messages: [{ role: "user", content: "Test message" }],
});
```

### Error Handling

```javascript
try {
  const completion = await openai.chat.completions.create({
    model: "standard",
    messages: [{ role: "user", content: "Hello!" }],
  });

  console.log(completion.choices[0].message.content);
} catch (error) {
  if (error.status === 401) {
    console.error("Invalid API key");
  } else if (error.status === 429) {
    console.error("Rate limit exceeded or insufficient credits");
  } else {
    console.error("API error:", error.message);
  }
}
```

## Troubleshooting

### Common Issues

#### Authentication Error

```
Error: 401 Unauthorized
```

**Solution**: Ensure you're using a valid Halfred API key (format: `halfred_xxxx...`).

#### Invalid Model Error

```
Error: Model 'gpt-4' not found
```

**Solution**: Use Halfred profile names (`lite`, `standard`, `deepthink`, `dev`) instead of specific model names.

#### Base URL Not Set

```
Error: Connection refused
```

**Solution**: Make sure you've set the `baseURL` to `https://api.halfred.ai/v1/`.

### Timeout Configuration

```javascript
const openai = new OpenAI({
  apiKey: "halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  baseURL: "https://api.halfred.ai/v1/",
  timeout: 30000, // 30 seconds
});
```

### Retry Logic

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  baseURL: "https://api.halfred.ai/v1/",
  maxRetries: 3,
});
```

## Support

For OpenAI SDK compatibility issues:

* Check our [API Reference](https://docs.halfred.ai/04-api-reference/01-endpoints.md) for detailed endpoint documentation
* Contact support at <support@halfred.ai>
* Join our [community Discord](https://discord.gg/wS2awX4EV7)
