Connect Higgsfield AI to Claude Code

Generate images and video from a prompt, then poll until the file is ready. Add Toolspoke to Claude Code once and it can use 5 Higgsfield AI actions. Your Higgsfield AI credential stays in Toolspoke, and you choose which actions Claude Code may call.

Set it up in Claude Code

Three steps, the first one once for every toolkit you will ever add.

  1. Add Toolspoke to Claude Code

    Run it in your project, then /mcp to sign in

    claude mcp add --transport http toolspoke https://toolspoke.com/mcp

    The sign-in opens in your browser, and Toolspoke asks you to approve it.

  2. Install Higgsfield AI and connect it

    Add Higgsfield AI to a project in your Toolspoke workspace.

    API key. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.

    API key
    cloud.higgsfield.ai → API keys. Paste the key id and the key secret joined by a colon, in that order. Higgsfield's own header format is `Key {api_key_id}:{api_key_secret}`, and its Python SDK reads the same pair from one HF_KEY variable.
  3. Choose what Claude Code may do

    All 5 actions start on. Switch off any of the 3 actions that change something in Higgsfield AI, and Claude Code gets a refusal if it tries.

What you can ask Claude Code for

A few of the Higgsfield AI actions that only read, so they are safe to try first.

  • Price a generation before running it
  • Check a generation started by `generate`

What Claude Code can do in Higgsfield AI

2 actions read and 3 write.

Reads

  • Estimate cost

    Price a generation before running it. Send the same model path and the same body `generate` would take, and Higgsfield answers with what it would cost this account in `credits` and in `usd`. Nothing is queued and no credit is spent, which is why this is a read and why it is also the connection test. Always call it before an expensive video generation, cost rises steeply with duration and resolution, and this is the only way to see the number in advance.

  • Get request status

    Check a generation started by `generate`. `status` is queued, in_progress, completed, failed, nsfw, or canceled, the last four are terminal. Poll about every two seconds at first and back off towards ten. A completed request carries the output: `images` for image models, `video` for video models, `audio` or `audios` for audio. Those URLs are kept for at least seven days and then may be removed, so anything worth keeping has to be copied elsewhere. `failed` and `nsfw` requests are not charged and any reserved credits are refunded.

Writes

  • Generate

    Queue a generation and get back a `request_id`. This spends the account's credits, call estimate_cost with the same arguments first. Nothing but the id and `status: queued` comes back: poll get_request_status until the status is terminal, then read `images`, `video` or `audio` from it. Every model has its own path and its own parameters and refuses parameters belonging to another, so read the model's entry in Higgsfield Cloud before composing `body`. Confirmed paths include higgsfield-ai/soul/standard (text to image), higgsfield-ai/dop/standard (image to video), and kling-video/v2.1/pro/image-to-video. Submissions take no idempotency key, so a call that times out ambiguously must not be blindly repeated, look for the request with get_request_status instead.

  • Cancel request

    Stop a generation that has not started yet, so it stops costing anything. Only works while the request is still `queued`, once it is `in_progress` Higgsfield refuses with a 400 and the work runs to completion. A successful cancellation refunds the reserved credits and returns an empty body. This destroys nothing: there is no output yet to lose.

  • Create upload url

    Get a place to put an input file that is not already on a public HTTPS URL. Returns `public_url`, the value to pass into `generate`, plus a one-hour `upload_url` and the `upload_headers` the bytes must be sent with. The upload itself is a PUT this gateway does not make: hand `upload_url` and `upload_headers` to whatever holds the file, and never send Higgsfield's credentials to it. Accepted types are image/jpeg, image/png, image/webp, image/gif, audio/wav and video/mp4.

Higgsfield AI in Claude Code: questions

Does Claude Code see my Higgsfield AI credential?

No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Claude Code only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.

Can I stop Claude Code from changing things in Higgsfield AI?

Yes. Each of the 5 actions can be switched off for a project. Turn off the 3 that change something and Claude Code can only read.

Will 5 actions crowd Claude Code's context?

No. Toolspoke shows Claude Code five bridge tools, plus a guide where a toolkit has one, and Claude Code searches for the Higgsfield AI action it needs when it needs it. Adding more toolkits does not add more tools to its list.

Can I add it once for every project?

Yes. Add --scope user to the command and Claude Code keeps Toolspoke in every project on this machine. Without it, the server is added to the project you ran the command in.

What does it cost?

Tool calls are free on every plan, and a Higgsfield AI call does not run in a sandbox, so it bills nothing.

Try Higgsfield AI in Claude Code

Free to start, and tool calls cost nothing on any plan.