List every AI model available through the Hedra API — image, video, and audio/avatar generation models from partners like ByteDance (Seedance, Seedream), Google (Veo, Imagen), OpenAI (GPT Image), Kling, ElevenLabs, and Hedra's own avatar models.

Use this first to discover a model's public id (e.g. "seedance-20", "veo-31", "hedra-avatar") before calling hedra_get_model_input_schema or hedra_submit_job with it.

Args:

• modality ('IMAGE' | 'VIDEO' | 'AUDIO', optional): filter to only models of this output type. Omit to list all.

Returns: JSON with a "models" array, each entry having at least {id, name, modality}.

Examples:

• Use when: "What video models can I use?" -> modality="VIDEO"

• Use when: "Find the Seedance model id" -> list all, look for name containing "Seedance"

• Don't use when: you already know the model id and just need its input schema (use hedra_get_model_input_schema instead)

Get full catalog details for one Hedra model: display name, modality, description, and any capability metadata Hedra publishes for it.

This gives a human-readable overview. For the exact, machine-typed input parameters needed to submit a job (required fields, enums, media roles), use hedra_get_model_input_schema instead — this tool alone is not enough to construct a valid hedra_submit_job call.

Args:

• model_id (string, required): the model's public id from hedra_list_models (e.g. "seedance-20").

Returns: JSON object describing the model.

Error Handling:

• Returns "Error [NOT_FOUND]: Model '' not found." if the id doesn't exist — double check with hedra_list_models.

Get the exact, typed JSON Schema for one model's submit "input" object — required fields, enums (e.g. allowed resolutions, aspect ratios, durations), and which fields accept media references (images/videos/audios/start_image/end_image) versus plain text/numbers.

ALWAYS call this before hedra_submit_job for a model you haven't used yet in this session — model input shapes vary significantly (e.g. Seedance uses duration_ms as an enum of fixed values; image models use a "quality" tier instead). Guessing the shape wastes a submit call and API validation is strict.

Args:

• model_id (string, required): the model's public id (e.g. "seedance-20").

Returns: A standalone OpenAPI operation object for this model's POST endpoint. The interesting part is components.schemas.Input_ (or similarly named) — its "properties" lists every input field with type, enum, and description; "required" lists which are mandatory.

Examples:

• Use when: about to call hedra_submit_job for "seedance-20" and unsure of valid resolutions -> call this first, read the resolution enum

• Don't use when: you already fetched this model's schema earlier in the same conversation and nothing has changed

List the text-to-speech voices a specific model accepts (scoped to that model's voice provider — e.g. ElevenLabs voices differ from Hedra Avatar's own voices).

Use this before submitting a job to a speech or avatar model that takes a voice_id input.

Args:

• model_id (string, required): the model's public id (e.g. "hedra-avatar", "elevenlabs-v3").

Returns: JSON with a "voices" array of {id, name, ...}.

Error Handling:

• Returns "Error [NOT_FOUND]..." if the model doesn't accept voice input at all.

Estimate the cost in USD of running a model with a given input, WITHOUT submitting a job or spending any wallet balance.

Strongly recommended before hedra_submit_job for expensive operations (long videos, 4K, high-duration audio) so the person can approve spend first. Some models cannot be precisely quoted until inputs are measured server-side (e.g. audio-length-dependent avatar video) — in that case the response indicates the price isn't quotable yet and the real cost will be shown if a submit is refused for insufficient balance.

Args:

• model_id (string, required): the model's public id.

• input (object, required): the same "input" object you'd pass to hedra_submit_job for this model — build it against hedra_get_model_input_schema.

Returns: JSON with the estimated price and currency (fields vary by model; some return {quotable:false} instead).

Examples:

• Use when: about to generate a 4K video and want to confirm cost first

• Don't use when: the model is cheap/fixed-price and the person hasn't asked about cost

Submit a generation job to a Hedra model. This starts real, billed work against the API wallet — always confirm the model and input with the person for anything non-trivial, and consider calling hedra_estimate_cost first for expensive requests.

Submission is asynchronous: this returns immediately with a job_id in IN_QUEUE or IN_PROGRESS status, not the finished result. Follow up with hedra_wait_for_job (simplest) or poll hedra_get_job_status / hedra_get_job yourself.

Before your first call to this tool for a given model in this session, call hedra_get_model_input_schema to get the exact required fields and enums — submitting a malformed input wastes a round trip and Hedra's validation is strict (e.g. Seedance's duration_ms only accepts specific values: 4000, 5000 ... 15000).

For any input field that takes a media reference (images, videos, audios, start_image, end_image, reference audio for voice cloning, etc.), first upload the file with hedra_upload_file and pass {"source":"url","url":} — or reuse a prior job's output with {"source":"asset","asset_id":<from outputs[].asset_id>}.

Args:

• model_id (string, required): the model's public id (e.g. "seedance-20").

• input (object, required): model-specific input, matching hedra_get_model_input_schema's schema exactly.

• webhook (string, optional): HTTPS URL to receive a signed completion webhook instead of polling.

• idempotency_key (string, optional): pass the same key on a retried submit to get back the original job's ack instead of creating a duplicate paid job.

Returns: JSON {job_id, model, status, status_url, result_url, estimated_completion_at}.

Error Handling:

• "Error [INVALID_ARGUMENT]..." lists every invalid field with the allowed values — fix and resubmit.

• "Error [INSUFFICIENT_BALANCE]..." means the API wallet needs funding; the message includes the funding URL and, when quotable, the exact amount short.

• "Error [MODERATION_FAILED]..." means an input (often a reference image) was refused by content moderation.

Fetch the full result envelope for a job, including its outputs (with download URLs and asset_ids) once complete, or its error if it failed.

Use this to retrieve the final generated file's URL, or the failure reason for a FAILED job. For a lighter-weight progress check while a job is still running, use hedra_get_job_status instead — or use hedra_wait_for_job to block until it finishes.

Args:

• job_id (string, required): the job id returned by hedra_submit_job (format job_).

Returns: JSON {job_id, model, status, outputs: [{url, asset_id, content_type, ...}], error, created_at, updated_at}. outputs[].url is the downloadable result; outputs[].asset_id can be fed back into another model's input as {"source":"asset","asset_id":...}.

Error Handling:

• "Error [NOT_FOUND]: Job not found." — double check the job_id, or that it belongs to this API key's workspace.

Lightweight poll of a job's current status and progress — cheaper than hedra_get_job for repeated polling while a job is still running.

Args:

• job_id (string, required): the job id from hedra_submit_job.

Returns: JSON {job_id, status: 'IN_QUEUE'|'IN_PROGRESS'|'COMPLETED'|'FAILED', progress, estimated_completion_at}. Once status is COMPLETED or FAILED, call hedra_get_job for the full result/outputs.

Examples:

• Use when: manually polling a long-running job in a loop with your own delay

• Don't use when: you just want to wait for completion and get the result in one call (use hedra_wait_for_job instead)

Poll a job until it reaches COMPLETED or FAILED (or the timeout elapses), then return the full result in one call. This is the simplest way to generate-and-wait without managing your own poll loop.

For batches of jobs, call this once per job_id rather than trying to wait on several at once — there is no multi-job wait tool by design, to keep timeout/backoff behavior predictable per job.

Args:

• job_id (string, required): the job id from hedra_submit_job.

• timeout_ms (number, optional, default 300000/5min, max 1200000/20min): give up and return the last-known status after this many milliseconds if the job hasn't finished.

• poll_interval_ms (number, optional, default 4000): delay between status checks.

Returns: JSON {job_id, status, outputs, error, timed_out}. timed_out is true if the timeout elapsed before completion — in that case status reflects the last poll and the job may still finish later; call hedra_get_job again after more time.

Examples:

• Use when: "generate this video and tell me when it's ready" -> submit, then wait

• Don't use when: doing many jobs in parallel and want to check on all of them periodically yourself (poll hedra_get_job_status per job instead, to avoid blocking on one at a time)

List jobs submitted with this API key across all models, most recent activity first, paginated.

Args:

• limit (number, optional, default 20, max 100): items per page.

• cursor (string, optional): pass the previous response's next_cursor to get the next page; omit for the first page.

Returns: JSON {jobs: [...], next_cursor}. has_more can be inferred from next_cursor being non-null.

Examples:

• Use when: "what have I generated recently?" or "find my last few jobs across any model"

• Don't use when: you already know the model and want only its jobs (use hedra_list_model_jobs — narrower and often faster)

List jobs submitted to one specific model, most recent first, paginated.

Args:

• model_id (string, required): the model's public id.

• limit (number, optional, default 20, max 100): items per page.

• cursor (string, optional): pass the previous response's next_cursor for the next page.

Returns: JSON {jobs: [...], next_cursor}.

Upload a file (image, video, or audio) to Hedra and get back a short-lived presigned URL to use as a media input in hedra_submit_job (e.g. a start_image, a reference image, a voice-cloning audio sample).

Free — works even with $0.00 in the API wallet; funding is only enforced at job submission. The returned url expires 1 hour after upload; if it lapses before you submit, upload again.

Provide EXACTLY ONE source:

• file_path: a path readable on the machine running this MCP server.

• source_url: an https URL Hedra should fetch and re-upload (a plain external URL is NOT accepted directly by model inputs — it must go through this upload step first).

• base64_data + filename: raw bytes inline, for clients that can't provide a local path or URL.

Returns: JSON {url, content_type, expires_at}. Pass this straight into a model's input as {"source":"url","url":} for the appropriate field (per hedra_get_model_input_schema).

Examples:

• Use when: about to run an image-to-video model and need to upload the start frame first

• Use when: cloning a voice from an audio sample the person uploaded

• Don't use when: reusing a previous Hedra generation's output as input — pass {"source":"asset","asset_id":...} directly to hedra_submit_job instead, no re-upload needed

Error Handling:

• "Error: file not found at " if file_path doesn't exist on the server's filesystem.

• "Error [MODERATION_FAILED]..." can occur later at submit time if the uploaded content is refused, not at upload time.

Get the current spendable balance of the Hedra API wallet — the prepaid USD balance that pays for API generations. This is SEPARATE from Hedra Studio credits; funding one does not fund the other.

Check this before submitting expensive or bulk jobs to confirm there's enough balance, or when a submit was refused with an INSUFFICIENT_BALANCE error.

Returns: JSON {balance, currency}.

Examples:

• Use when: about to submit a batch of jobs and want to sanity-check funds first

• Use when: a hedra_submit_job call failed with a billing error and you want to confirm the current balance before advising the person

Get API wallet usage/spend history and breakdown.

Returns: JSON with usage details (shape depends on Hedra's current usage report format).

Examples:

• Use when: "how much have I spent on the API this month?"

• Don't use when: you just want the current balance (use hedra_get_balance instead — cheaper, simpler)