Pipelines, models and runs, from code or an agent.

The API is an MCP server at https://api.heddla.com/mcp (Streamable HTTP, stateless). Any client that speaks MCP over HTTP connects to that address. No key is needed: the client sends you to the heddla studio, where you sign in the way you made your account (Apple, Google or a password) and approve the connection (OAuth 2.1 with PKCE, the protocol's own authorization). The connection then appears under Settings → API & agents in the studio, named after the client, and is disconnected there like any key.

Claude (claude.ai, Claude Desktop)

Settings → Connectors → Add custom connector, paste https://api.heddla.com/mcp, then Connect and sign in.

Claude Code

claude mcp add --transport http heddla https://api.heddla.com/mcp

Claude Code opens the sign-in the first time you use a tool (/mcp shows the status). To skip the sign-in, on a server or in CI, pass a key instead:

claude mcp add --transport http heddla https://api.heddla.com/mcp \
  --header "Authorization: Bearer heddla_your_key_here"

Cursor, Codex, ChatGPT and others

Anything that takes an HTTP MCP server. Sign-in happens on connect when the client supports OAuth; otherwise add the header:

{
  "mcpServers": {
    "heddla": {
      "type": "http",
      "url": "https://api.heddla.com/mcp",
      "headers": {"Authorization": "Bearer heddla_your_key_here"}
    }
  }
}

As a skill

Agents that work from instructions rather than tools (a Claude Code skill, a Codex AGENTS.md, a system prompt) can load https://api.heddla.com/docs/skill.md: the same rules and endpoints as a Markdown skill that reads the key from HEDDLA_API_KEY. Save it as .claude/skills/heddla/SKILL.md (or wherever your agent keeps skills), put the key in the environment, and the agent knows how to use heddla.

Tools

On connect the server hands the agent the pipeline rules below as its instructions, then offers these tools:

Every tool runs the matching REST endpoint in-process, so validation, pricing and error messages are identical whichever way you call. Files included: upload_file takes the bytes as base64 or a public https url and runs the same upload as POST /v1/files; for real files on disk, begin_upload hands back a presigned PUT url so the bytes go straight to storage from the shell, and finish_upload makes the file ready.

For your own code, or an agent without a browser: create a key under Settings → API & agents in the studio, or Settings → API keys in the app. It is shown once. Send it on every request:

Authorization: Bearer heddla_your_key_here

A key, and a signed-in agent, acts as the account behind it: the pipelines it makes are that account's, the runs it starts spend that account's balance and show up in the Runs tab. Neither can mint or revoke keys, add funds, or publish recipes. Those stay in the app and the studio, so a leaked key is contained. Revoke it there if it leaks.

curl https://api.heddla.com/v1/balance -H "Authorization: Bearer heddla_your_key_here"

Answers with balance_usd and topup_url, the page where the account's owner adds funds by card (?amount_usd=25 preselects an amount). A run or draft the balance cannot cover is refused with 402 before anything starts, and the error carries the same topup_url; an agent hands it to you. Agents cannot add funds themselves.

1 · Browse the catalog

curl "https://api.heddla.com/v1/models?view=summary&current=true&output=image" \
  -H "Authorization: Bearer heddla_your_key_here"

Filters: provider, input, output (a type: text, image, audio, video, document, web, archive), available=true, and current=true, which leaves out models a newer one replaces (they carry superseded_by; steps that already use them keep running, new steps take the successor). view=summary leaves out the long descriptions and option schemas; GET /v1/models/{id} has everything for one model.

2 · Create a pipeline

curl -X POST https://api.heddla.com/v1/pipelines \
  -H "Authorization: Bearer heddla_your_key_here" \
  -H "Content-Type: application/json" \
  -d @pipeline.json

The body is validated against the catalog; a 422 says exactly what to fix. The answer carries the pipeline's id and total_cost_usd per run. GET /v1/pipelines/{id}/spec shows the run contract: the inputs a caller must send, the options open to them, and an example request.

3 · Run it

curl -X POST https://api.heddla.com/v1/pipelines/PIPELINE_ID/executions \
  -H "Authorization: Bearer heddla_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"brief": {"type": "text", "text": "a lighthouse at dawn"}},
       "step_options": {"paint": {"size": "1024x1024"}}}'

The API answers 202 at once with the execution; the price is reserved from the balance up front and the run continues server-side whether or not you keep watching.

4 · Read the result

curl "https://api.heddla.com/v1/executions/EXECUTION_ID?wait=60" \
  -H "Authorization: Bearer heddla_your_key_here"

?wait= holds the request until the run has completed or failed, up to 120 seconds, and returns the latest snapshot either way: one call instead of a polling loop. GET /v1/executions/{id}/events streams the same snapshots over SSE. Results sit under results[step_id].outputs, and the outputs a pipeline names as its deliverables come back under deliverables as well. Binary outputs carry a file_id and a presigned url that expires after about an hour.

{
  "name": "Poster maker",
  "description": "A one-line brief becomes a poster",
  "steps": [
    {
      "step_id": "write",
      "name": "Write the image prompt",
      "model_id": "google-gemini-4-argon",
      "input_sources": {
        "text": {
          "pre_input": "Write one vivid, specific image prompt for this brief:\n",
          "sources": [{"step_id": "", "output_key": "brief"}]
        }
      }
    },
    {
      "step_id": "paint",
      "name": "Paint it",
      "model_id": "openai-image-2-5",
      "input_sources": {
        "text": {"sources": [{"step_id": "write", "output_key": "text"}]}
      },
      "options": {
        "size": {"ask": true, "default": "1024x1536", "note": "Pick the canvas"}
      }
    }
  ],
  "input_meta": {
    "brief": {"label": "Brief", "placeholder": "A lighthouse in a storm, seen from the sea", "help": "What should the poster show?"}
  }
}

• Steps run in array order. Each step has step_id (^[a-z0-9_-]{1,50}$), model_id (a catalog id), input_sources, and optional name and options.
• input_sources has one entry per input TYPE the model declares — the key is the type name ("text", "image", "audio", "video", "document"), the value is {"sources": [...]} with an optional "pre_input" (text inputs only: hidden text placed before the joined sources).
• A source is exactly one of: an earlier step's output {"step_id": "<earlier step>", "output_key": "<that step's output type>"}; a run input the caller supplies at execution time {"step_id": "", "output_key": "<input name>"}; a fixed text value {"value": {"type": "text", "text": "..."}} (bake prompts and instructions in here); or a baked file {"value": {"type": "image|audio|video|document", "file_id": "..."}} — a file the account uploaded that every run reuses (a driving clip for motion transfer, a style frame, a logo), so runners never supply it. Only reference file_ids that exist on the account.
• Types line up exactly: an image input needs an image source. Text inputs may fan in several sources (joined in order); binary inputs take one source unless the model's multi_inputs allows more (then order matters, e.g. clips join in wiring order).
• Run input names are shared identity: two steps wiring the same name receive the same caller value; different names mean separate values. Name inputs after what they are ("photo", "clip", "brief"), never a different type than the input they feed.
• Options: {"value": "<canonical string>"} fixes an option; {"ask": true, "default": "...", "note": "..."} opens it to runners, who pass it as step_options[step_id][key] at run time; an asked choice option may add "choices": ["<answer>", ...] to offer only those answers, in that order (at least two, the default among them). Only option keys the model lists exist; get_model shows them with choices, ranges and what each does to the price. An option marked "clip_length": true (in get_model and the spec) is the length in seconds of the clip its step takes in, and what the step is priced for: one longer video clip is cut to it from its start; a longer recording, or clips that run longer together, are refused. To send other parts of a clip, cut them first: cut_clip (POST /v1/files/{id}/cut) joins the parts a runner picks into a new video of theirs; send that as the clip, and set the option to the parts' total rounded up to the option's step (at least its min), so the step takes the cut as it is.
• input_meta gives run inputs a label, help text and, for text inputs, a placeholder (an example of what to type, shown greyed in the empty field, at most 120 characters) or a fixed list of choices, keyed by input name.
• Optional inputs and steps: input_meta {"optional": true} lets runners leave a run input empty, and the sources that read it drop out. A step may carry "when": {"input": "<run input>", "provided": true} (or false: the optional input was left empty) or {"input": "<choice input>", "equals": "<one of its choices>"}; when it does not hold the step is skipped, and so is any step left with nothing to feed one of its inputs. A one-value binary input may list alternatives: the first source that is there is used (a cover from the photo step when there is a photo, else from the words step). input_meta {"choices": ["Off", "On"], "toggle": true} shows a two-choice input as a switch, off unless sent; an input only conditions read needs no wiring, just its choices. A deliverable's "alternatives": [{"step_id", "output"}] stand in, in order, when its step was skipped. Every way a run can go must still make at least one deliverable, and a run reserves only the steps it will take.
• Casts: input_meta {"multi": true, "cast": {"of": "<video run input>"}} makes an image run input the photos that replace people found in that clip. Runners find the people with find_people (POST /v1/files/{clip}/people) and send one photo per person to replace, each naming them: [{"type": "image", "file_id": "...", "person": "p2"}]; anyone not named stays. Read as images (an image input wired to it) the cast is the photos in the order sent, Image 1 first; read as text it is the cast list: who each Image replaces, with their clearest moment and box, who stays, and who is where at those moments. tool-cast-sheet draws that on one picture for a vision step (its video must be the cast's own clip input).
• deliverables names what a run gives: a list of {"name", "step_id", "output"} promoting step outputs to results by name (e.g. hero → step "page" output "web"); runs return them under deliverables, the spec lists them, and screens show them first. Set them on every pipeline whose result is more than its last step's output.
• Two output kinds exist only as step outputs, never as uploads: web (one self-contained HTML page: its url renders it in a sandbox, its download_url is the file) and archive (a zip, download only). tool-web-page makes both from a template baked into its template option — placeholders {{text}}, {{image}}, {{video}}, {{audio}}, {{document}} and {{video.mime}} and the like, nothing executable — so a pipeline can hand over a piece of a website, not just a clip.
• Keep pipelines lean — no steps the goal does not need — and price with get_pipeline_spec (total_cost_usd) before running.

Prefer not to wire by hand? POST /v1/pipelines/draft with {"brief": "..."} asks heddla's builder to compose a pipeline from plain language. It answers 202 with a pipeline in status drafting; GET /v1/pipelines/{id}?wait=60 holds until it is ready (or draft_failed, with draft_error). Drafts may spend a test_budget on real test generations; what they do not spend is refunded.

Making a pipeline together with a person, stage by stage? Keep the record as a build: POST /v1/builds opens one, journal entries go to POST /v1/builds/{id}/entries, and POST /v1/builds/{id}/finalize closes it with the finished pipeline's id. Over MCP the same steps are start_build, log_build and finalize_build, and the build_pipeline prompt carries the contract.

Every input and output is a typed value. Text travels inline; binary data never does:

{"type": "text", "text": "hello"}
{"type": "image", "file_id": "<id from POST /v1/files>"}

Upload first (images, audio, video, PDF and DOCX; 25 MB, or 200 MB for video), then use the returned id:

curl -X POST https://api.heddla.com/v1/files \
  -H "Authorization: Bearer heddla_your_key_here" \
  -F "file=@photo.jpg"

For large files, or from a machine that should not stream through the API: POST /v1/files/uploads with the file's name and size answers with a file id and a presigned PUT url, the bytes go straight to storage, and POST /v1/files/{id}/finish makes the file ready.

Uploads stay in the account's library until the owner removes them, next to what its runs made; the same bytes uploaded twice are kept once, and the second upload answers with the first file (existing: true), which then lists first. GET /v1/files lists the library to pick from, GET /v1/files/usage says how much room it takes.

To send part of a clip to a step that takes a clip by length (an option marked clip_length), cut it first: POST /v1/files/{id}/cut with {"parts": [{"start": 12.5, "end": 20}]} cuts the parts, joined in the order they play, into a new video kept like an upload (cut_from names the clip and the parts; the same parts again answer with the same file). It answers 202 with the cut's id while it cuts, ?wait= holds until it is made, and GET /v1/files/{id}?wait= on the cut's id keeps waiting. Send the cut as the clip and set the option to the parts' total, rounded up to its step: the cut never runs longer, so the step takes it as it is.

A voice worth keeping: POST /v1/voices with {"name": "Anna", "file_ids": ["…"], "consent": true} clones audio files from the library and keeps the voice on the account. consent is the person's own answer to the words GET /v1/voices gives as consent_text, recorded with the time. Each voice has a value: send it as the answer to any option marked saved_voices. A voice works only on the account that saved it, so a recipe cannot fix one, and a person running a recipe answers with their own. DELETE /v1/voices/{id} removes it at any time; its recordings stay in the library until they are removed too.

Everything a key can reach. Pagination is ?limit=&offset=; ids are UUIDs.

Key-authed requests are budgeted per key at 120 per minute with a burst of 60; a run that exceeds the account's balance is refused with 402 before anything starts. Error bodies are {"error": "…", "details": "…"} (a 402 adds topup_url).