HEhedra-labs
Run a model

Run a model by id

Changed on

Runs any model in the catalog by its public id, with input passed through untyped — the same call the typed operations below make, minus the compile-time schema.

Reach for it when the model is not known ahead of time: a client generated before a model shipped can still run it, and an id read from GET /v3/models at runtime needs no regeneration. Prefer the typed operation whenever your client already has one — input here is validated against the same published schema (GET /v3/models/{model}), so a bad field is a 400 at submit rather than an error before the call.

Submits an asynchronous job and returns 202 with a job id. Fetch the result at GET /v3/jobs/{job_id} — each item in its outputs[] follows the OutputItem schema — or track progress via GET /v3/jobs/{job_id}/status / the SSE stream at GET /v3/jobs/{job_id}/stream.

post/models/{model}

Request

  • Base URL
    https://api.hedra.com/v3
  • Auth
    • API key in header Authorization
    • or HTTP bearer

Path parameters

modelstring required

The model's public id (GET /v3/models).

Headers

Idempotency-Keystring

Caller-chosen key that makes retrying this submit safe. A repeat submit with the same key returns the original job's ack (with Idempotent-Replayed: true) instead of queueing and charging a second job. Keys are scoped to the calling user and workspace. Failed jobs release their keys; retrying after failure or deletion of the original job can create and charge a new job. The request is fingerprinted by model and input: reusing a key with a different request is a 409 ALREADY_EXISTS, and retrying while the original is still being accepted is a 409 ALREADY_IN_PROGRESS carrying Retry-After.

Request body

inputobject required

Model-specific inputs, validated at submit against the model's published input schema (GET /v3/models/{model}).

webhookstring uri nullable

URL to receive a signed completion webhook.

Response

Accepted. The job runs asynchronously; poll status_url / result_url from the ack.

job_idstring required

This job's id — server-issued, and opaque.

modelstring required

The resolved model id this job runs on.

status'IN_QUEUE' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' required

The four states a job can be in.

status_urlstring required

Path of this job's status monitor: poll GET /v3/jobs/{job_id}/status for status, progress, and the estimated completion time.

result_urlstring required

Path of the job resource itself: GET /v3/jobs/{job_id} returns the result envelope, including the outputs once it completes. Also the value of this response's Location header.

estimated_completion_atstring date-time nullable

ISO-8601 instant this job is estimated to finish, as of this response. Null when no estimate is available yet, and when the job has already finished. The estimate can change while the job runs: poll GET /v3/jobs/{job_id}/status for the current one.

Changes