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`
- `Qwen3.8-9B-Distill-uncensored-heretic-Q8_0.gguf` / `...-F16.gguf` (lazy-downloaded from `petruhonk/Qwen3.8-9B-Distill-uncensored-heretic-GGUF`)
- `DeepSeek-V4-Pro-Qwen3.5-9B-MTP-Q4_K_M.gguf` / `...-Q8_0.gguf` / `...-BF16.gguf` (lazy-downloaded from `Jackrong/DeepSeek-V4-Pro-Qwen3.5-9B-MTP-GGUF`)

Accepted aliases for chat completions include:
- `gemma-q4`, `gemma-q6`
- `qwen3.8-heretic`, `petruhonk/qwen3.8-9b-distill-uncensored-heretic`, `qwen-heretic`
- `deepseek-v4`, `deepseek-v4-pro`, `jackrong/deepseek-v4-pro-qwen3.5-9b-mtp`, `deepseek-v4-pro-q8`, `deepseek-v4-pro-bf16`

## 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.