Submit A Hedra Generation Job
hedra_submit_jobSubmit a generation job to a Hedra model, returning an async job ID for tracking. Check the model schema first and confirm input before starting billed work.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Model-specific input object. Fetch the exact shape with hedra_get_model_input_schema first. | |
| webhook | No | HTTPS URL to receive a signed job-completion webhook. | |
| model_id | Yes | The model's public id (e.g. 'seedance-20', 'gpt-image-2', 'hedra-avatar'). Get valid ids from hedra_list_models. | |
| idempotency_key | No | Replays the original ack for a retried submit instead of creating a duplicate job. |