By RamthaMedia
RamthaMedia Free eBooks · August 2026
Price: Priceless
· 10 min read
Preface
Someone opens Hedra wanting one finished video, and finds an agent, a canvas, twenty-plus models, Skills, Spaces and a credit system all sitting behind one login with no map between them. This book is that map: which manual tool to reach for over the agent and when, how Elements and references actually hold a face or a product steady across generations, what a webhook or a log drain buys a developer who is tired of polling, and where the API's error codes and retry rules save a real job from failing silently. It covers the full model catalog Hedra exposes through its v3 API, the mechanics of asset chaining between jobs, and the account and billing rules that decide whether a subscription is worth it before a single credit is spent.
Chapter 1
An Agent, a Canvas, and No Idea Where to Start
A freelance editor has been asked for a fifteen-second product ad by tomorrow morning. She opens Hedra expecting an image generator and instead finds a chat box asking what she's trying to make. She types the brief. The agent asks a follow-up about the product's look. This is not what she expected from a creative tool, and for the first ten minutes she isn't sure whether she's using software or talking to someone.
That confusion is the point worth explaining before anything else. Hedra is built around a persistent agent that holds a conversation, a visual canvas, reference material and outputs together in one place called a Space, rather than a single generate-and-download screen. You brief it the way you'd brief a person, hand it context — a product photo, a brand reference, a rough sketch — and it works within that Space until the result is close enough to refine by hand.
The four manual tools sit underneath the agent for exactly the moments when a person wants to skip the conversation: Image, Video, Speech and Edit Video, each giving direct control over model choice, references and output settings. Knowing when to reach past the agent into one of those four is most of what separates someone who fights Hedra for an hour from someone who gets a usable result in fifteen minutes.
The rest of this book walks through both paths — the agent's own way of working, and the manual tools underneath it — model by model, limit by limit, so that brief from tomorrow morning has an actual plan behind it rather than a chat window and a guess.
Chapter 2
Give the Agent Something to Hold Onto
A brand's junior designer needs forty images of the same mascot character for a social campaign. Generate that character twice on most AI tools and you get two different faces, two different outfits — nothing a brand could put its name on. The fix Hedra offers is to store the identifying material once, as a reference or an Element, and call it back in every later generation rather than re-describing it each time.
References are the looser version — an uploaded image the agent or a manual model treats as visual context for a single job. Elements are the persistent version, saved into the Library so a character, a product shot or a brand's colour and type direction can be pulled into any future Space without re-uploading anything. The distinction matters because a reference forgotten after one job is a reference you'll be re-describing for the fortieth image too.
This is also where the model catalog's own reference limits stop being trivia and start being a planning constraint. Nano Banana Pro accepts up to fourteen images total, split as six high-fidelity objects, five characters and three style references — a number worth knowing before assembling a shot that needs more inputs than that. Nano Banana's plain tier caps at three images total, a real drop from its Pro sibling that changes which model actually fits a multi-reference job.
Skills add a second kind of persistent memory: saved instructions the agent reuses automatically, rather than being retyped into every conversation. A studio that always wants product shots on a white background with a specific rim light can save that once as a Skill instead of writing it into every brief.
Chapter 3
Twenty-Some Models, One Submit Endpoint, and No Single Right Answer
A developer wiring Hedra into their own app opens the model catalog expecting to pick 'the video model' and finds instead a genuine spread — Seedance 2.0, Seedance 2.0 Mini, Veo 3, Veo 3.1, Kling V3, Kling O3, PixVerse V6, Vidu Q3, Vidu Q3 Reference, Happy Horse, Hedra Avatar, Gemini Omni Flash — each with its own required fields, its own resolution ceiling and its own duration options.
The pattern worth noticing across all of them: every model is submitted the same way, POST to /models/{model_id} with input fields specific to that model, and every one returns the same 202 envelope — job_id, status, status_url, result_url. That consistency is deliberate and it is what makes swapping models mid-project realistic rather than a rewrite.
But the fields inside input diverge in ways that decide which model actually fits a job. Kling V3 requires both a start_image and an end_image — it is built around first-and-last-frame video, not open text-to-video — and caps its prompt at 2,500 characters. Veo 3.1 makes no image required at all but supports a negative_prompt field the Kling models don't expose. Seedance 2.0 offers duration options from 4 to 15 seconds in one-second steps; Vidu Q3 goes as low as 1 second. A job built for one model rarely drops cleanly into another without adjusting which fields are even present.
Resolution ceilings vary just as sharply. Nano Banana Pro and GPT Image 2 both reach 4K; Nano Banana's non-Pro tier tops out lower; Kling V3 offers 1080p or 4K but nothing between. Choosing a model by name alone, without checking its actual input schema, is how a job gets rejected for a field the previous model never asked for.
Chapter 4
The Difference Between a Job That Finishes and One You Have to Watch
Every job submitted to Hedra's API comes back as a 202 with three things to poll or wait on: status_url for a lightweight progress check, result_url for the full envelope once it's done, and an estimated_completion_at that is null until the model has enough history to guess one. A developer's first instinct is usually to poll status_url in a loop — and that instinct works, right up until the app is running fifty jobs at once and that becomes fifty loops.
The alternative Hedra documents is a webhook: register a URL, either per job or as one account-wide default, and the terminal event — job.completed or job.failed — is POSTed there instead. The payload is the same result envelope GET /jobs/{job_id} would return, minus a few poll-only fields like logs and cost, so nothing is lost by switching from polling to waiting.
What makes this safe to build on rather than a leap of faith: every delivery carries a hex-encoded ed25519 signature over five specific fields, fetched once from a public-key endpoint and cached, so a delivery can be verified before anything in it is trusted. Delivery is at-least-once, with up to 12 retry attempts spread over roughly six hours, backing off from 10 seconds to hourly — which means an endpoint that's briefly down doesn't lose the event, but it does mean the same event might arrive twice. Deduplicating on the X-Hedra-Webhook-Id header — the job's own id, byte-identical across every retry — is what keeps a doubled delivery from doubling a downstream action.
One detail that has real consequences if missed: generated media is retained for 48 hours after a job completes, counted from the original completion time, not from when a webhook happens to be replayed. A delivery replayed after that window carries outputs marked EXPIRED with a null download URL. Downloading promptly, or chaining the output's asset_id into a later job before the window closes, is the difference between a finished asset and a job that has to be re-run.
You may also like:
What Google Flow Actually Lets You Build
Chapter 5
When a Job Fails, the Error Tells You Whether to Retry
A generation fails at 2am and the on-call developer has to decide, half asleep, whether to resubmit it or leave it alone. Hedra's error envelope is built for exactly that moment: every failure carries a code from one fixed vocabulary — INVALID_ARGUMENT, INSUFFICIENT_BALANCE, MODERATION_FAILED, RESOURCE_EXHAUSTED, DEADLINE_EXCEEDED, and others — plus a retryable boolean that says outright whether trying again could help, and a retry_after in seconds when it can.
This removes the guesswork that usually comes with third-party API failures. RESOURCE_EXHAUSTED and UNAVAILABLE are typically retryable; INVALID_ARGUMENT and MODERATION_FAILED are not, because resubmitting the same bad input just fails the same way again. INSUFFICIENT_BALANCE comes with its own billing object naming the balance, the price and where to add funds, so an app can surface a real fix rather than a generic error string.
One code deserves special attention for anyone building something meant to run for months: GONE, paired with a replaced_by field naming the successor model. When Hedra retires a model, jobs submitted to its old id don't just start failing silently — they fail with a pointer to what replaced it, which is the one place in this whole API where a developer is told, in the error itself, exactly what to change.
The same structured-error discipline carries into webhook and log-drain delivery failures: last_error on both objects reports a code, a message and retryable, so a failing integration can be diagnosed by reading a field rather than by guessing from an HTTP status alone.
Chapter 6
Watching a Job From the Inside, Not Just the Outcome
Most APIs only tell you a job succeeded or failed. A log drain streams the whole lifecycle instead — queued, started, moderation.passed, provider.submitted, provider.error, retry.scheduled, progress, finalizing, download.ready, completed, failed, recovered — as it happens, to an HTTPS endpoint of the developer's own choosing.
Two wire formats are offered and they suit different setups. NDJSON posts one JSON object per line, signed with an HMAC-SHA256 header keyed to the drain's own secret — a natural fit for a custom receiver. OTLP posts a binary protobuf batch that any standard OpenTelemetry collector already knows how to ingest, authenticating through headers instead of a signed body, which suits a team that already runs Datadog or a collector rather than building a bespoke listener.
A drain that fails five times in a row disables itself automatically, flipping enabled to false and reporting consecutive_failures as the reason — a safeguard against a broken endpoint quietly eating every event forever without anyone noticing. Re-enabling it clears the counter and delivery resumes from there. The one failure code that won't be fixed by retrying is FAILED_PRECONDITION, which means the destination URL resolves to a blocked address range; no amount of re-enabling helps until the URL itself changes.
None of this is required to use Hedra successfully. It exists for the specific case of an application running enough jobs that watching a single result envelope stops being enough — and it's documented in more procedural depth than most billing pages, which is its own small signal about who Hedra expects to be reading it.
You may also like:
What Krea’s One Login Actually Replaces
Chapter 7
Credits, Plans, and the Reset Nobody Reads Twice
The most common way a Hedra subscription surprises someone isn't the price — it's the reset. A plan's monthly credit allotment behaves differently from a purchased credit pack, and mixing up which pool is which is exactly the kind of thing a support page states plainly and a fast-moving subscriber skims past.
The pattern worth carrying into a plan decision: check the reset behaviour before the credit count, because a plan whose credits reset monthly rewards steady, ongoing use, while a plan or add-on that carries balance forward rewards occasional bursts of heavy work. Which shape actually matches a workflow — weekly output versus one big push before a launch — decides plan value more than the headline credit number does.
Annual subscriptions apply their own logic to how credits arrive across the year rather than issuing the full annual amount as one lump sum on day one, which is worth checking before assuming a year's credits are all available immediately after signing up.
For anyone integrating through the API specifically, an automatic top-up option exists so a workflow doesn't stop mid-run for lack of balance — useful for an unattended pipeline, but worth pairing with the INSUFFICIENT_BALANCE error handling from earlier in this book rather than relying on it alone, since a top-up can itself fail or be capped.
Chapter 8
Real-Time Collaboration, and What Happens to a Shared Space
A small studio wants two people editing the same video concept at once rather than passing files back and forth by email. Hedra's Spaces support exactly that: invite a teammate by email, choose their access level, and both people work inside the same live canvas, conversation and outputs simultaneously.
This turns a Space from a personal workspace into something closer to a shared document, and it changes how references and Elements should be organised — material saved into the Library becomes something a whole team draws from, not just one person's private stash. A studio that treats Elements as personal scratch space rather than a shared asset library will find teammates quietly re-uploading things that already exist.
The practical upshot for anyone planning team use before subscribing: access control is per-invite, not all-or-nothing, so a Space can be opened to a client for review without handing them the same editing rights a teammate gets.
Chapter 9
Closing the Loop: What to Decide Before the Next Job
The freelance editor from the opening chapter now has a real decision tree instead of a guess: brief the agent when the goal is still fuzzy, drop into a manual tool the moment the goal is a specific model with a specific field; save a reused face or product as an Element rather than re-uploading it each time; and check a model's own input schema before assuming it works like the last one she tried.
For anyone building on the API rather than working in the app, the decision is similar in shape: poll for a quick script, register a webhook for anything running at real volume, and read the error code before deciding whether to retry — the API is built to answer that question directly rather than making a developer guess from an HTTP status alone.
Pricing, credit costs per model, and current plan tiers were not part of what this book captured — they move often enough that the safest place to check them is Hedra's own pricing and billing pages, linked at the end of this book, rather than a number printed here that could go stale within a season.
Questions readers actually ask
Can I use Hedra without ever touching the API, just through the website?
Yes — the agent workspace and the four manual tools (Image, Video, Speech, Edit Video) are the app experience, and none of it requires an API key. The API exists for developers building Hedra into their own product.
What happens to my downloaded outputs after they expire?
Nothing is recoverable through the same job. Once the 48-hour retention window passes, outputs[].url returns null and the asset_id can no longer be used to reference the file — the only path forward is regenerating the job.
Do all Hedra models accept an image as a starting point?
No. Some, like Kling V3, actually require both a start_image and end_image. Others, like Flux Dev or Sana, are text-to-image only and take no image input at all. Checking a specific model's schema before assuming it works like another is worth the extra minute.
Is there a way to test my webhook setup without running a real generation?
Yes — POST to /webhooks/default/test fires a test delivery immediately and reports the response status, so wiring can be confirmed before a real job depends on it.
What's the difference between a Reference and an Element in Hedra?
A reference is scoped to one job or conversation — useful context that isn't necessarily kept. An Element is saved into the Library deliberately, meant to be reused across future Spaces without re-uploading the same material each time.
Can two people work in the same Hedra Space at once?
Yes, through the realtime multiplayer feature — invite a teammate by email and set their access level, and both people see the same live canvas and conversation.
If a job fails, how do I know whether retrying will help?
Read the error's retryable field, not just its code. It's a direct boolean answer rather than something to infer from an HTTP status, and retry_after tells you how long to wait when retrying is worth it.
What's a Skill, and how is it different from just writing detailed prompts each time?
A Skill is a saved instruction the agent applies automatically once configured, so a repeatable requirement — a specific background, a brand's tone — doesn't need retyping into every new conversation.
Contact / More useful information from RamthaMedia
Official source links:
Hedra
Disclaimer: This eBook is compiled from publicly available information and was accurate at the time of writing. For full and up-to-date details, please visit the official website linked above. RamthaMedia accepts no legal liability for any decision made on the basis of this eBook, and nothing here is professional, financial or legal advice. The image used for the cover page is illustrative only – a stock photo from Pexels or an AI-generated image, never a real photograph of the site described.
