# HF Studio

> Open-source, self-hosted AI studio for video, image and audio. One local backend (FastAPI) exposes a REST API, an MCP server over stdio for agents (Claude Code, Codex, Claude Desktop, ChatGPT and any stdio MCP client) and a Next.js web UI. Video and image run on 82 Higgsfield models, each sent to the cheapest provider with a key (Higgsfield, APIMart or KIE); voice, music and sound effects use ElevenLabs. Generating spends the user's own credits, and no MCP tool can generate without first quoting that exact request. MIT license.

If you are an AI agent and your user wants to add HF Studio to their workflow, follow "Set it up for a user" below. The canonical, always up-to-date guide is AGENTS.md in the repository.

- Repository: https://github.com/Jjat00/hf-studio
- Agent guide (canonical): https://github.com/Jjat00/hf-studio/blob/main/AGENTS.md
- Agent guide (raw markdown): https://raw.githubusercontent.com/Jjat00/hf-studio/main/AGENTS.md
- README (raw markdown): https://raw.githubusercontent.com/Jjat00/hf-studio/main/README.md

## When it fits

- The user wants their agent to generate videos, images, voice-overs, music or sound effects from the terminal or chat, with the price shown before anything is spent.
- The user wants the same Higgsfield models cheaper (APIMart or KIE keys route each video to the cheapest provider, with a safe fallback).
- The user wants everything (UI runs and agent runs) in one local library with full configuration and origin.
- It runs on the user's machine (Windows, macOS, Linux, WSL). It is not a hosted service: there is no account to create on this site.

## Set it up for a user

1. Prerequisites: `uv` (Python 3.12+). For the web UI, also Node.js 20+ and `pnpm`. `ffmpeg` with `ffprobe` is needed for the audio features (macOS: `brew install ffmpeg-full`, the plain formula lacks the `rubberband` filter).
2. Clone: `git clone https://github.com/Jjat00/hf-studio.git && cd hf-studio`
3. Keys: the only required secret is the Higgsfield key, `HF_API_KEY` in the format `KEY_ID:KEY_SECRET` (from https://console.higgsfield.ai). Optional: `ELEVENLABS_API_KEY` (enables audio), `APIMART_API_KEY` and `KIE_API_KEY` (cheaper videos). Ask the user for the keys; never invent, print or commit them. They go in `.env`, created from `.env.example` (git-ignored).
4. Run `uv run hf-studio setup --no-input` once `.env` has the key. It validates the key without spending credits and writes the UI key to `web/.env.local`. (A human can instead run `./dev.sh`, or `.\dev` on Windows, which asks for the keys interactively.)
5. Start it: `uv run hf-studio start` (API on `http://127.0.0.1:8787`, UI on `http://localhost:3000`) or `uv run hf-studio start --api-only` (API only, enough for MCP, no Node.js needed). It is a long-running process: start it in the background. Health check: `GET http://127.0.0.1:8787/health` returns `{"ok": true, ...}`.
6. Connect the agent: `uv run hf-studio connect claude-code` (or `codex`, `claude-desktop`, `json`). It creates a new revocable `hfs_…` key for that client and registers the server; it never rotates an existing key. `--print` prints the command or config instead. If `hf-studio` is already registered it stops without changes; ask the user before removing the old one. If the agent's CLI is not installed, nothing is registered and it prints the command to run where that CLI is.
7. Tell the user to restart the agent so it loads the 31 tools.

Manual MCP config (any stdio client): command `uv run --directory /absolute/path/to/hf-studio hf-studio mcp` with env `HF_STUDIO_URL=http://127.0.0.1:8787` and `HF_STUDIO_TOKEN=hfs_…`.

## Use it through MCP

- Flow: `recommend_models` or `find_models` → `get_model` (read `input_schema` and `studio_notes`) → `upload_media` for local files → `estimate_cost` → tell the user the cost and wait for their OK → `generate` with that `quote_id` → `get_generation` until `terminal` is true → `download_outputs`.
- Every paid run needs a single-use `quote_id` (valid 15 minutes) from quoting the exact same request. Paid tools say "spends credits" in their title. Never pass `confirm_unknown_cost=True` unless the user explicitly accepts an unknown price.
- A generation in `awaiting_approval` (its provider failed without charging, or the price went over what was approved) needs the user's OK on the new price (`cost_usd`, and `reserve_usd` if the provider holds more upfront). Approve with `approve_fallback` and `max_usd` / `max_reserve_usd`; it takes no `quote_id`.
- After an ambiguous error, check `list_generations` before calling `generate` again, and reuse the same `idempotency_key` when retrying.
- Before generating a sound, search `list_sounds`: reusing one is free.
- `providers_status` shows which provider keys are set, their balances and the links to sign up or top up.
- Kling 3.0 elements: `list_elements` / `create_element` (2–4 JPG/PNG images); put the `el_…` ids in the model's `elements` field and cite each as `@name` in the prompt. They run on APIMart and KIE only (KIE also needs `image_url`).

## Tools (31)

- Models: `find_models`, `get_model`, `recommend_models`
- Generate: `upload_media`, `estimate_cost`, `generate`, `generate_batch`
- Tracking: `get_generation`, `wait_generations`, `list_generations`, `cancel_generation`, `download_outputs`, `approve_fallback`, `use_output` (reuse a finished output as input of another run; free)
- Kling 3.0 elements: `list_elements`, `create_element`, `delete_element`
- Providers: `providers_status`
- Presets: `list_presets`, `run_preset`, `save_preset`
- Voice (ElevenLabs): `list_voices`, `change_voice`
- Audio (ElevenLabs): `text_to_speech`, `sound_effect`, `compose_music`, `isolate_voice`, `elevenlabs_account`
- Sound library: `list_sounds`, `label_sound`, `import_elevenlabs_history`

## Safety notes

- Do not expose the web UI beyond `127.0.0.1`: its proxy does not authenticate visitors.
- The MCP server never sees the Higgsfield or ElevenLabs credentials, only its own `hfs_…` key.
- Do not make real generation calls to "test" the setup: use `GET /health` and `uv run hf-studio check-credentials` (validates the key without spending).

## Optional

- Spanish README: https://raw.githubusercontent.com/Jjat00/hf-studio/main/README.es.md
- Website with examples: https://hf-studio-gold.vercel.app