# QFOXAI OpenAI-Compatible Starter Kit

QFOXAI works with OpenAI-compatible clients. Use your full `qf_...` API key and the `/v1` base URL. Direct HTTP requests may omit `model`; QFOXAI then applies key, project, smart-routing, and platform defaults.

## Connection Settings

| Setting | Value |
| --- | --- |
| Base URL | `https://qfoxai.com/v1` |
| API Key | `qf_your_full_secret_key` |
| Auth header | `Authorization: Bearer qf_your_full_secret_key` |
| Default model | `QFOXAI` |

## 5-Minute Checklist

1. Create or copy a QFOXAI API key from your dashboard.
2. Set `QFOXAI_API_KEY=qf_your_full_secret_key` in your server environment.
3. Set your OpenAI-compatible base URL to `https://qfoxai.com/v1`.
4. Use `QFOXAI` when your SDK requires a model, or choose another alias returned by `GET /v1/models`.
5. Test with the cURL request below, then move to your SDK or app.

## cURL

```bash
curl -X POST "https://qfoxai.com/v1/chat/completions" \
  -H "Authorization: Bearer qf_your_full_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"QFOXAI","messages":[{"role":"user","content":"Hello QFOXAI"}],"max_tokens":300}'
```

## Laravel

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('QFOXAI_API_KEY'))
    ->acceptJson()
    ->retry(2, 300)
    ->post('https://qfoxai.com/v1/chat/completions', [
        'model' => 'QFOXAI',
        'messages' => [
            ['role' => 'user', 'content' => 'Hello QFOXAI'],
        ],
        'max_tokens' => 300,
    ])
    ->throw()
    ->json();

$answer = data_get($response, 'choices.0.message.content');
$tokens = data_get($response, 'usage.total_tokens');
```

## JavaScript / Node

```js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.QFOXAI_API_KEY,
  baseURL: "https://qfoxai.com/v1",
});

const response = await client.chat.completions.create({
  model: "QFOXAI",
  messages: [{ role: "user", content: "Hello QFOXAI" }],
  max_tokens: 300,
});

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

## Python

```python
from openai import OpenAI

client = OpenAI(
    api_key="qf_your_full_secret_key",
    base_url="https://qfoxai.com/v1",
)

response = client.chat.completions.create(
    model="QFOXAI",
    messages=[{"role": "user", "content": "Hello QFOXAI"}],
    max_tokens=300,
)

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

## Cost And Quota Estimate

Use this before large chat, image, embedding, or background requests to preview estimated tokens, cost, and whether the request fits the active plan.

```bash
curl -X POST "https://qfoxai.com/v1/estimate" \
  -H "Authorization: Bearer qf_your_full_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"QFOXAI","endpoint":"chat","messages":[{"role":"user","content":"Write a short support reply"}],"max_tokens":300}'
```

Read `estimate.total_tokens`, `estimate.estimated_cost`, `quota.monthly_tokens_remaining_after_request`, and `will_fit_current_plan` before sending a heavier request.
## Image Generation

Use the same API key and quota system for image generation when your plan has image access.

```bash
curl -X POST "https://qfoxai.com/v1/images/generations" \
  -H "Authorization: Bearer qf_your_full_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"QFOXAI Image","prompt":"A realistic product photo for a SaaS landing page","size":"1024x1024","n":1}'
```

The response returns QFOXAI image URLs or base64 image data depending on the active platform configuration.
## Website Chat Widget

Create a widget in the QFOXAI dashboard, copy the public widget key, and load it before `</body>`:

```html
<script src="https://qfoxai.com/widgets/YOUR_PUBLIC_WIDGET_KEY.js" async></script>
```

## Useful Endpoints

- `GET https://qfoxai.com/v1/models`
- `GET https://qfoxai.com/v1/key`
- `GET https://qfoxai.com/v1/health`
- `POST https://qfoxai.com/v1/chat/completions`
- `POST https://qfoxai.com/v1/images/generations`
- `POST https://qfoxai.com/v1/estimate`
- `POST https://qfoxai.com/v1/embeddings`
- `POST https://qfoxai.com/v1/moderations`
- `POST https://qfoxai.com/v1/batches`

## Connection Test Checklist

Before going live, verify these calls from your backend:

1. `GET https://qfoxai.com/v1/health` returns a healthy JSON response.
2. `GET https://qfoxai.com/v1/models` returns at least one public QFOXAI model alias.
3. `GET https://qfoxai.com/v1/key` returns active key status and quota details.
4. `POST https://qfoxai.com/v1/chat/completions` returns a normal answer.
5. If enabled for the plan, `POST https://qfoxai.com/v1/images/generations` returns a generated image.
6. Optional: `POST https://qfoxai.com/v1/estimate` previews usage before a large request.
## Production Tips

- Store the full `qf_...` secret on the server, never in browser JavaScript.
- Use the base URL only up to `/v1`; your SDK/client appends `/chat/completions`.
- Read `X-QFOXAI-*` and rate-limit response headers for usage, quota, and request ID.
- Use `POST /v1/estimate` to preview cost and quota fit before large customer actions.
- Use `GET /v1/key` to show upgrade/renew prompts when quota is low.
- Add retry with short backoff for temporary service errors.
- Rotate keys from the QFOXAI dashboard if a key is exposed.