HEheygen
Durable Workflows

Start a workflow run

Changed on

Starts a run of a workflow and submits the run for execution. No video is created and nothing is charged by this call. Omit version_number to use the latest published version, resolved exactly once per Idempotency-Key. The key is required: repeating it returns that original run, reusing it with different inputs returns 409 conflict, and it is how to recover from a retryable 503.

post/v3/workflow-runs

Request

  • Base URL
    https://api.heygen.com
  • URL
    https://api.heygen.com/v3/workflow-runs
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Headers

Idempotency-Keystring required

Required client-supplied key for safely retrying creation. The key is stored with the created resource, so a retry returns the original resource indefinitely — there is no expiry window. Scope is the space plus the specific workflow version: the same key against a different version is independent. A retry whose body differs from the original returns 409 conflict. It is required rather than optional because this request is submitted for execution: when that submission cannot be confirmed the response is a retryable 503, and repeating the request with the same key is what resumes the original run instead of starting a second one. A missing or blank value is rejected with 400. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default.

Request body

workflow_idstring required

Workflow to run.

version_numberinteger nullable

Published version to run. Omit to run the latest published version, resolved once when the request's Idempotency-Key is first accepted; the response reports the exact version_number the run is pinned to.

inputsobject

Values for the version's declared run inputs. Validated against the frozen plan. Media inputs accept an asset id (a bare string, or {"type": "asset_id", "asset_id": ...}), a publicly accessible HTTPS source ({"type": "url", "url": ...}), or bounded inline content ({"type": "base64", "media_type": ..., "data": ...}); URL and inline sources are imported into your asset library before the run executes. URL sources are limited to 32 MB for images and 32 MB for audio; inline content to 5 MB for images and 16 MB for audio, and it must also fit this endpoint's 1 MiB request-body limit.

Response

Existing run returned for a repeated Idempotency-Key.

Changes