> 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/01-getting-started/01-quickstart.md).

# 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](https://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

```bash
npm install halfred.ai
```

```javascript
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

```bash
pip install halfred
```

```python
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)

```bash
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:

```json
{
  "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*](https://halfred.ai/app/project-profile) *(requires login).*

Learn more about profiles in our [Model Profiles guide](https://docs.halfred.ai/03-concepts/01-profiles.md).

## What's Next?

Now that you've made your first API call:

1. **Explore SDKs**:
   * [Node.js SDK Documentation](https://docs.halfred.ai/02-sdk-integration/01-nodejs.md)
   * [Python SDK Documentation](https://docs.halfred.ai/02-sdk-integration/02-python.md)
2. **Understand Core Concepts**:
   * [Model Profiles](https://docs.halfred.ai/03-concepts/01-profiles.md)
   * [Pricing & Credits](https://docs.halfred.ai/03-concepts/02-pricing.md)
   * [Tokens Explained](https://docs.halfred.ai/03-concepts/03-tokens.md)
3. **Dive Into the API**:
   * [Complete REST API Reference](https://docs.halfred.ai/04-api-reference/01-endpoints.md)
   * [Error Handling](https://docs.halfred.ai/04-api-reference/02-errors.md)
4. **Optimize Your Integration**:
   * [Best Practices](https://docs.halfred.ai/05-advanced/01-best-practices.md)

## 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**: <support@halfred.ai>
* **Discord**: [Join our community](https://discord.gg/wS2awX4EV7)
* **FAQ**: [halfred.ai/#faq](https://halfred.ai/#faq)
