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:

  2. Understand Core Concepts:

  3. Dive Into the API:

  4. Optimize Your Integration:

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?

PreviousGetting StartedNextAuthentication

Last updated