README.md

---
title: Using External Apis
emoji: 🌖
colorFrom: yellow
colorTo: purple
sdk: gradio
sdk_version: 6.14.0
app_file: app.py
pinned: false
license: mit
short_description: using-external-apis
---

# Using external APIs (OpenAI) on Hugging Face Spaces

This Space runs a small [Gradio](https://www.gradio.app/) app with **two tabs** that both call **OpenAI Chat Completions** the same way a student would in a notebook—once with plain HTTP (`requests`) and once with Hugging Face’s client (`huggingface_hub.InferenceClient`).

Official Space configuration reference: [Spaces config reference](https://huggingface.co/docs/hub/spaces-config-reference).

## How to use the app

1. **Set your API key** (see [Secrets](#secrets-openai_api_key) below). Without `OPENAI_API_KEY`, the app will raise when it reads the environment variable.
2. Open the Space and pick a tab:
   - **`requests`** — builds a `POST` to `https://api.openai.com/v1/chat/completions` with JSON `model` + `messages` and a `Bearer` token header. Useful when you are teaching REST, curl, or reading OpenAI’s HTTP docs side by side with the code.
   - **`huggingface_hub`** — creates an `InferenceClient` aimed at OpenAI’s `/v1` base URL and calls `chat.completions.create(...)`. The request shape matches the “OpenAI-style” chat API described in the [huggingface_hub inference guide](https://huggingface.co/docs/huggingface_hub/guides/inference).
3. Type a question, submit, and read the answer in the output box. Both tabs use the same model name (`MODEL` in [`app.py`](app.py)).

## Secrets: `OPENAI_API_KEY`

- In the Space: **Settings → Variables and secrets** (or **Repository secrets** depending on UI), add a **secret** named exactly **`OPENAI_API_KEY`** with your OpenAI API key as the value.
- Hugging Face exposes repository secrets to the running app as **environment variables** with the same name. The code uses `os.environ["OPENAI_API_KEY"]`—no key files, no pasting keys into the README or `app.py`.
- **Do not** commit keys to git or put them in this README’s YAML frontmatter. If a key ever leaks, rotate it in the OpenAI dashboard.

### Gotchas with secrets

- **Name must match**: `OPENAI_API_KEY` (case-sensitive) must match what [`app.py`](app.py) expects.
- **Restart**: After adding or changing a secret, **restart the Space** (or trigger a new build) if the app still behaves as if the variable were missing.
- **Local runs**: On your laptop, export the variable yourself, for example:
  - macOS/Linux: `export OPENAI_API_KEY="sk-..."` then run the app.
  - Never check a `.env` file with real keys into version control.

## `requirements.txt` on Hugging Face Spaces

This repo’s [`requirements.txt`](requirements.txt) lists **one Python package per line**. Spaces use it to `pip install` dependencies before starting the app.

- **Blank lines** are usually fine; avoid stray text that is not a valid `pip` requirement.
- **Pinning** (e.g. `gradio==6.14.0`) improves reproducibility so a future `gradio` major release does not surprise your class. The README frontmatter’s `sdk_version` should stay compatible with the Gradio version you install (see below).
- **Order** does not matter for `pip`, but keeping standard library–heavy teachers first (`requests`, `huggingface_hub`) can make the file easier to read.

## README formatting for Hugging Face Spaces

Spaces treat the top of this file specially:

- The block between the **first** `---` and the **second** `---` is **YAML frontmatter**. Hugging Face reads fields like `sdk`, `sdk_version`, `app_file`, and `title` from it.
- **Do not remove** that block unless you know how you will configure the Space elsewhere.
- **Common gotchas**:
  - **`app_file`** must point to the file that calls `launch()` (here: `app.py`).
  - **`sdk_version`** should match the Gradio major/minor you rely on; a mismatch with `requirements.txt` can produce confusing import or layout errors.
  - **Indentation** in YAML matters; keep values simple strings without unquoted colons that break parsing.
- **Content below the closing `---`** is normal Markdown for humans (this section). You can edit it freely without changing how the Space boots, as long as the frontmatter stays valid.

## Other setup gotchas

- **Model name**: `MODEL` in [`app.py`](app.py) must be a model your OpenAI **account** and **billing** can access. If OpenAI returns an error, the simplified app does not catch it—you will see the raw exception in the Space logs, which is fine for teaching debugging.
- **Network**: The Space runtime must reach `api.openai.com`. Corporate or restricted networks are rare on HF but worth knowing for local copies.
- **`huggingface_hub` vs Hub login**: This app sends your **OpenAI** key to **OpenAI** (`base_url="https://api.openai.com/v1"`). You do **not** need a Hugging Face user token for these two tabs unless you change the code to call HF Inference Providers or the HF router instead.

## Local quick start (optional)

From this directory, with Python 3 and a virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
export OPENAI_API_KEY="sk-..."   # use your real key; do not commit it
python app.py
```

Then open the URL Gradio prints (often `http://127.0.0.1:7860`).