Quick Start Guide

Get started with Halfred in less than 5 minutes. Learn how to create an account, generate an API key, and make your first API call.

Step 1: Create Your Account

1. Go to halfred.ai and sign up for a free account using Google, GitHub, or email

2. Verify your email address (if using email sign-up)

3. Log in to your dashboard

Step 2: Get Your API Key

When you log in for the first time, Halfred automatically:

• Creates a default project for you

• Generates your first API key

• Displays it on your dashboard

Important: Copy and securely store your API key immediately - this is the only time you'll see it!

Your API key will look like this: halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Security Note: Never expose your API key in client-side code or commit it to version control.

If You Need to Generate a New Key Later

If you lost your key or need to revoke it:

1. Go to your dashboard

2. Find the "Your Key" section

3. Click the 3-dots menu (⋮)

4. Select "Revoke Key & Get New One"

5. Copy your new key immediately

Step 3: Add Credits (Optional for Testing)

1. Go to Credits in your dashboard

2. Click "Top up Credits"

3. Select the amount you want to add ($5 minimum)

4. Complete the secure payment via Stripe

Halfred offers a free DEV profile for testing, but it has rate limits and is limited to Lite profile models, making it unsuitable for production use. For production applications:

Step 4: Make Your First API Call

Choose your preferred method:

Using the Halfred Node.js SDK

npm install halfred.ai

import { Halfred } from "halfred.ai";

const client = new Halfred({
  apiKey: "halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

async function main() {
  const completion = await client.chat.completions.create({
    model: "lite",
    messages: [{ role: "user", content: "Hello, Halfred!" }],
  });

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

main();

Using the Halfred Python SDK

pip install halfred

from halfred import Halfred

client = Halfred(api_key="halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx")

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

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

Using cURL (REST API)

curl -X POST "https://api.halfred.ai/v1/chat/completions" \
  -H "Authorization: Bearer halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lite",
    "messages": [
      {"role": "user", "content": "Hello, Halfred!"}
    ]
  }'

Step 5: Understanding the Response

You'll receive a response in this format:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677652288,
  "provider": "halfred-router",
  "model": "gpt-4o",
  "profile": "LITE",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm Halfred. How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 12,
    "total_tokens": 22
  }
}

Key fields:

• choices[0].message.content: The AI's response

• usage: Token consumption for billing

• profile: The Halfred profile used

• provider & model: The actual model that handled your request

💡 Tip: Try the Playground

Your Halfred dashboard includes an advanced Playground interface where you can:

• Test API requests interactively

• Experiment with different profiles (Lite, Standard, DeepThink, Dev)

• See real-time responses

• View recent logs and request status

• Fine-tune parameters before integrating into your code

This is a great way to explore Halfred's capabilities without writing any code!

Step 6: Choose Your Profile

Halfred offers different profiles optimized for various use cases:

Profile	Use Case	Price per M tokens (output)
LITE	Simple tasks, UI assistants, cost-sensitive apps	$0.50
STANDARD	Most production applications (recommended)	$2.50
DEEPTHINK	Complex reasoning, long documents, R&D	$12.50
DEV	Free tier for development and testing	$0.00

For the most up-to-date pricing, please refer to the Profile Dashboard (requires login).

Learn more about profiles in our Model Profiles guide.

What's Next?

Now that you've made your first API call:

1. Explore SDKs:

   • Node.js SDK Documentation

   • Python SDK Documentation

2. Understand Core Concepts:

   • Model Profiles

   • Pricing & Credits

   • Tokens Explained

3. Dive Into the API:

   • Complete REST API Reference

   • Error Handling

4. Optimize Your Integration:

   • Best Practices

Troubleshooting

"Invalid API key" Error

• Make sure you copied the entire API key including the halfred_ prefix

• Verify the key hasn't been revoked in your dashboard

• Check that you're using the correct project's API key

"Insufficient credits" Error

• Add credits in your dashboard under Credits or in your account settings

• Use the free DEV profile for testing: model: "dev"

Rate Limit Errors

• Implement exponential backoff retry logic

• Consider upgrading your plan for higher rate limits

Need Help?

• Email: [email protected]

• Discord: Join our community

• FAQ: halfred.ai/#faq