docs/API_COOKBOOK.md

# OpenAI-compatible API cookbook

The Space exposes a private OpenAI-compatible chat API at
`https://abalanescu-flow.hf.space/v1`. The bearer token is the `FLOW_API_KEY`
Space secret. Never put the token in this repository.

## Discover models

```bash
curl -sS \
  -H "Authorization: Bearer $FLOW_API_KEY" \
  https://abalanescu-flow.hf.space/v1/models
```

Only model IDs returned by this endpoint are live. Supported model files:
- `Qwen3.8-27B-Q6_K.gguf` (lazy-downloaded from `unsloth/Qwen3.8-27B-GGUF` into `/data`)
- `gemma-4-26B-A4B-it-ultra-uncensored-heretic.i1-Q4_K_M.gguf`
- `gemma-4-26B-A4B-it-ultra-uncensored-heretic.i1-Q6_K.gguf`

The aliases `gemma-q4` and `gemma-q6` are accepted by chat requests when the corresponding file is present.

## Chat with the exact live model ID

### Qwen 3.8 27B Q6 (Native Context, No Artificial Caps)

```bash
MODEL_ID="Qwen3.8-27B-Q6_K.gguf"
curl -sS \
  -H "Authorization: Bearer $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  https://abalanescu-flow.hf.space/v1/chat/completions \
  -d "$(python3 -c 'import json,os; print(json.dumps({"model":os.environ["MODEL_ID"],"messages":[{"role":"user","content":"Tell me a joke."}],"max_tokens":64}))')"
```

### Gemma 4 26B Heretic Q4

```bash
MODEL_ID="gemma-4-26B-A4B-it-ultra-uncensored-heretic.i1-Q4_K_M.gguf"
curl -sS \
  -H "Authorization: Bearer $FLOW_API_KEY" \
  -H "Content-Type: application/json" \
  https://abalanescu-flow.hf.space/v1/chat/completions \
  -d "$(python3 -c 'import json,os; print(json.dumps({"model":os.environ["MODEL_ID"],"messages":[{"role":"user","content":"Reply with FINAL_LIVE_OK"}],"max_tokens":32}))')"
```

Set `MODEL_ID` in the shell before running the example. An unknown model returns HTTP 400 instead of silently selecting a different GGUF.

## Verification status

- **Gemma 4 26B Heretic (Q4_K_M & Q6_K)**: Live-verified on ZeroGPU.
- **Qwen 3.8 27B (Q6_K)**: Live-verified on ZeroGPU (`unsloth/Qwen3.8-27B-GGUF`), native context (`n_ctx=0`, max 262,144 tokens).
- Vision, streaming, embeddings, STT, and TTS are not claimed here until each has a live test on the Space.