HF Studio

Español · English · Website and examples

A self-hosted AI video, image and audio studio on top of the Higgsfield and ElevenLabs APIs. One backend gives you a REST API, an MCP server so your agents (Claude Code, Codex, Claude Desktop, ChatGPT…) can generate for you, and a web UI to do it by hand. Everything lands in the same library.

Its MCP server is built around one rule: an agent cannot spend credits without first quoting that exact request, so it always has a price to show you before it generates.

Why

• The cheapest provider for each video: the same model through Higgsfield, APIMart or KIE, quoted on all of them, with a safe fallback (see Cheaper with more providers).
• One place for 82 Higgsfield endpoints (Seedance, Kling, Wan, Hailuo, PixVerse, LTX, Grok Imagine, Ideogram, Recraft…), searchable by what they do (text-to-video, first/last frame, video edit, motion transfer…) instead of by brand.
• Agents that quote before they spend. Every MCP tool that starts a paid run requires a single-use quote_id from a prior quote of the same request, and the server tells the agent to show you that cost and wait for your OK.
• Persistent jobs. Async jobs stored in a database, with validation before spending, deduplication, Idempotency-Key, a local queue that respects your account's concurrency, and local copies of every output (Higgsfield only keeps them for 7 days). Higgsfield jobs keep being tracked after a restart; audio jobs cut off by a restart are marked as failed, not resumed.

Cheaper with more providers

The same model is often sold by several providers at very different prices. HF Studio can send each generation to the cheapest provider that offers the exact same model and settings:

| Provider | Key | What it adds | | --- | --- | --- | | Higgsfield | HF_API_KEY, required | Every catalog model, and it stores your input files (uploading is free) | | APIMart | APIMART_API_KEY, optional | Usually the cheapest for Seedance and Wan | | KIE | KIE_API_KEY, optional | Usually the cheapest for Hailuo and MiniMax |

• Quote every provider, run the cheapest. /v1/estimate, the UI and estimate_cost show every option, the savings against Higgsfield and why a provider was left out (no key, no balance, or no exact equivalent for your settings). Prices come from each reseller's public price list, refreshed daily. On 2026-10-03, Seedance 2.0 at 720p for 5 s cost 0.71 USD on APIMart, 1.025 on KIE and 1.51 on Higgsfield.
• Same model, never a substitute. A setting a provider cannot reproduce (a fixed seed, a bitrate, an aspect ratio…) leaves that provider out instead of being dropped.
• Unofficial channels, labeled. A provider may also sell a cheaper unofficial channel of the same model (e.g. APIMart's grok-imagine-1.5-video-ext for Grok Imagine 1.5, about 6× cheaper). It is one more option, marked "unofficial channel"; if it fails, the official one is the fallback under the usual approval rule, and once you approve a channel that is the one sent.
• Every generation says what it cost. The history shows the provider, the provider's model (and whether the channel is unofficial) and the cost in USD (~ when estimated); failed generations show no cost.
• Kling 3.0 elements. Save characters, products or locations on the Elements page (or with create_element): a name, a description and 2 to 4 JPG/PNG images, stored locally and shared by the UI and your agents. Pick them in Kling 3.0 (up to 3) and cite them in the prompt as @name. They run on APIMart and KIE (KIE also needs a first frame); Higgsfield's public API cannot create or read elements, so those requests skip it.
• Fallback without double charges. If a provider rejects the request or the task fails without charging, the next one is tried on its own only if it costs the same or less than what you approved; otherwise the generation waits for your approval. A submission that may have reached the provider (timeout, unclear answer) is never retried anywhere.
• Prices checked again before sending. APIMart and KIE are priced from local tables, so they are re-priced right before every send; Higgsfield quotes are reused for 15 minutes and asked again after that. Before the first automatic send the whole plan is redone with current prices. The generation stops for your approval when the checked price goes over your approved cap, when the price becomes unknown and you did not accept an unknown cost for that option, or when an upfront hold (some providers hold more than they charge and refund the difference) goes over the hold you approved. If you accepted an unknown cost without a cap for an option, that option can run at whatever price it ends up having; holds are always approved separately.
• Add a key: uv run hf-studio providers --add apimart (or kie) asks for it, checks it for free and saves it; --open NAME opens the page where you create it, and hf-studio providers shows status and balances. The UI has a Providers page with the same links.
• Add a provider (developers): write a Provider subclass in src/hf_studio/providers/ (key check, submit, poll, optional price list) plus its model table, and list it in registry.py. Setup, the UI, the MCP and the worker pick it up from there.

Features

• Spaces, a node canvas to generate step by step (/spaces, inspired by Magnific Spaces): connect texts, media, lists and any catalog model, and each step's output feeds the next one. Every node shows its cost in USD before you generate and keeps its run history. Right-click or press / to add a node; drag an output to an empty spot to add the next step already connected.
  • Runs on the server ("Run all" or "Generate this and what follows"): every step is quoted, you approve a total budget, and the run pauses to ask you if a step does not fit, has no price or its fallback provider costs more. It keeps going if you close the tab and never pays twice after a restart.
  • Lists for batches: a generator connected to a list runs once per checked item, and the batch follows the chain in pairs (5 prompts → 5 images → 5 videos).
  • Free local tools (ffmpeg): first or last frame of a video, combine videos, mix audio over a video.
  • Audio nodes (ElevenLabs): voiceover with your voices, sound effects and music.
  • Assistant node (Claude, optional ANTHROPIC_API_KEY): writes or improves prompts, describes images and drafts scripts; its text feeds other nodes.
  • Flows: publish a canvas with labeled inputs and run it from Presets by filling a form.
• 82 Higgsfield endpoints (66 video, 15 image, 1 custom references), each with its JSON Schema taken from the official docs (hf-studio sync-catalog).
• Every video and image capability: text-to-video, image-to-video, first and last frame, reference videos, video edit and extend, motion transfer, object swap (Genjutsu), text-to-image and image editing.
• ElevenLabs audio (optional): change the voice on a segment of a video (with deep, monster and ghost effects), text-to-speech, sound effects, music and voice isolation.
• Keep the original audio when editing a video: HF Studio muxes the source audio back onto the result (free, with ffmpeg), handy when the model returns a silent clip.
• Cost visible before generating: next to the button in the UI, and required by the MCP tools (one quote per request). On the REST API, the ElevenLabs routes require their own quote; the Higgsfield routes offer /v1/estimate and dry_run and trust whoever holds the hfs_… key.
• Library in a masonry grid with everything generated from the UI and from agents (with its origin), filters and a detail page per result with its full configuration (model, prompt, parameters, input files and JSON).
• Sound library: all your ElevenLabs sounds (including voices made on their website, imported for free) sorted by kind (voices, screams, laughs, creatures, ambience, impacts, foley, transitions, music) with editable titles and tags, so you can reuse them instead of paying again.
• Presets (recipes with variables), batches with a total quote, a natural-language model recommender (English and Spanish) and 22 use cases with step-by-step tutorials for the UI and for agents.
• Bilingual UI: Spanish by default, English one click away.

| Use cases | Model catalog | | --- | --- | | | |

Requirements

Runs natively on Windows, macOS and Linux (and in WSL). CI tests the backend on all three.

• Python 3.12+ and uv
• Node.js 20+ and pnpm (for the UI)
• ffmpeg with ffprobe (voice change, original audio and isolation; also used by the tests). Linux: sudo apt install ffmpeg. Windows: winget install ffmpeg. macOS: brew install ffmpeg-full, because the plain ffmpeg formula lacks the rubberband filter that the voice effects use (HF Studio finds ffmpeg-full on its own and warns at startup if the filter is missing).
• A Higgsfield API key (console.higgsfield.ai). Generating spends your credits.
• Optional: APIMart and KIE API keys, to make videos cheaper (see Cheaper with more providers).
• Optional: an ElevenLabs API key (elevenlabs.io/app/settings/api-keys) for voice, effects and music. Pay-as-you-go balance or a plan both work.

Quick start

git clone https://github.com/Jjat00/hf-studio.git
cd hf-studio
./dev.sh        # macOS, Linux, WSL
.\dev          # Windows (cmd or PowerShell)

Both are shortcuts for uv run hf-studio start, which works the same on Windows, macOS and Linux.

The first run asks for your Higgsfield key (and, optionally, your ElevenLabs key), validates it without spending credits, creates .env and the UI key, installs the dependencies and starts everything. To add the ElevenLabs key later, put it in ELEVENLABS_API_KEY in .env and restart.

• Web UI: http://localhost:3000
• API and interactive docs: http://127.0.0.1:8787/docs

Only want to use it from your agents? ./dev.sh api (Windows: .\dev api, or anywhere uv run hf-studio start --api-only) starts just the API, no Node.js needed. Then connect your agent in one line (see Connect your agents):

uv run hf-studio connect claude-code     # or: codex, claude-desktop, json

Setting it up with an AI agent? Point it to AGENTS.md.

Commands

| Command | Use | | --- | --- | | hf-studio start [--api-only] | Sets up on the first run and starts the API and UI (or only the API); ./dev.sh and dev.cmd run it | | hf-studio setup [--no-input] | First-run setup: .env, key check and UI key (start runs it) | | hf-studio connect CLIENT [--print] | Registers the MCP server in claude-code or codex, or prints the config (claude-desktop, json) | | hf-studio serve | Starts the