HOWTOUSE.md

# How to use the API

One base URL fronts all three services. Every `/gpt`, `/gemini`, `/flow` call needs the
`API_KEY` as a Bearer token. The monitor UI (`/`) needs no key.

- **Base URL:** `https://akash1313-selfapi-v2.hf.space`
- **Auth header:** `Authorization: Bearer YOUR_API_KEY`  *(your real key is in the gitignored `./api-key`)*

> ⚠️ **You must be logged in** to ChatGPT / Gemini / Flow inside the browser
> (`https://akash1313-selfapi-v2.hf.space/`) for real responses. The servers reply even when
> logged out, but with `extensionConnected:false` / empty data. Check first:
> ```bash
> curl -H "Authorization: Bearer YOUR_API_KEY" https://akash1313-selfapi-v2.hf.space/gpt/health
> ```
> `extensionConnected:true` = ready.

---

## ChatGPT — `/gpt`

| Endpoint | Method | Body |
|----------|--------|------|
| `/gpt/health` | GET | — |
| `/gpt/api/chat` | POST | `{"prompt": "...", "wait_for_response": true}` |
| `/gpt/api/chat/bulk` | POST | `{"prompts": ["...","..."], "delay_seconds": 2}` |
| `/gpt/v1/chat/completions` | POST | OpenAI-compatible (see below) |

```bash
# Simple chat
curl -X POST https://akash1313-selfapi-v2.hf.space/gpt/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"Write a haiku about the sea","wait_for_response":true}'

# OpenAI-compatible (drop-in for OpenAI SDKs — set base_url=.../gpt/v1)
curl -X POST https://akash1313-selfapi-v2.hf.space/gpt/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"gpt-5","messages":[{"role":"user","content":"hello"}],"stream":false}'
```
Optional fields: `"model"`, `"thinking_effort"`, `"conversation_id"` (continue a thread).

---

## Gemini — `/gemini`  (form-encoded, not JSON)

| Endpoint | Method | Body |
|----------|--------|------|
| `/gemini/status` | GET | — |
| `/gemini/chat` | POST (form) | `prompt`, `user_id`, `new_chat`, `stream` |
| `/gemini/music` | POST (form) | `prompt` |
| `/gemini/reset` | POST | — |
| `/gemini/output/<file>` | GET | — (generated media) |

```bash
curl -X POST https://akash1313-selfapi-v2.hf.space/gemini/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "prompt=Explain quantum entanglement simply&new_chat=true"
```

---

## Flow (video / image) — `/flow`  (JSON)

| Endpoint | Method | Body |
|----------|--------|------|
| `/flow/health` | GET | — |
| `/flow/generate/video` | POST | `{"prompt":"...","aspect":"portrait","duration":10,"count":1}` |
| `/flow/generate/image` | POST | `{"prompt":"...","aspect":"portrait","count":1}` |
| `/flow/upload/image` · `/flow/upload/video` | POST | multipart file |
| `/flow/download/<filename>` | GET | — |

```bash
# Text-to-video (aspect: portrait|landscape ; duration: 4,6,8,10)
curl -X POST https://akash1313-selfapi-v2.hf.space/flow/generate/video \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"a cat surfing a wave, cinematic","aspect":"landscape","duration":8}'

# Text-to-image
curl -X POST https://akash1313-selfapi-v2.hf.space/flow/generate/image \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"neon city at night","aspect":"square"}'
```

---

## Auth errors

| Code | Meaning |
|------|---------|
| `401` | Missing/wrong key |
| `503` | `API_KEY` not set on the server (gateway disabled, fail-closed) |
| `502` | Backend server not reachable (still booting / crashed — check `/chrome.log`) |

Rotate the key anytime: change the `API_KEY` secret in the Space settings (auto-restarts).