ElevenCreativeImage & VideoFlowsTemplatesRuns

Create Template Run

Start a run of a flows template. Pass `version_id` to pin a snapshot, or omit it / pass `latest` to run the latest published version. Set input values under `inputs`, keyed by input port id. The response is the run in its initial state, with every output already listed under its port id in `outputs`. Include `webhook` to receive a `flows_template_run` event carrying the finished run once its `status` is `completed` or `failed`; this is the recommended way to wait. Without one, fetch `GET /v1/flows/templates/{template_id}/runs/{run_id}` at a modest interval until the `status` is terminal.

Path parameters

template_idstringRequired

The ID of the template, as shown in the ElevenLabs app or by GET /v1/flows/templates.

Headers

xi-api-keystringOptional

Request

This endpoint expects an object.
inputsmap from strings to strings or booleans or integers or doubles or objects or lists of TemplateRunInputRequired

Input values keyed by input port id. Every input port of the version being run must be given; a missing or unknown id is rejected. Pass {} for a template with no inputs.

version_idstring or nullOptional>=1 character

The template snapshot to run. Pass a specific version id to pin that snapshot, or latest (the default when omitted) to run the template’s most recently published version. Only published versions can be pinned, except by the template’s owner, who may also pin an unpublished saved snapshot to try it out before publishing. The live draft is never run through this API.

webhookobject or nullOptional

Include to send the run’s result to the workspace’s configured flows webhooks once the run’s status reaches completed or failed. One event for the whole run: the flows_template_run event’s data matches the terminal response of GET /v1/flows/templates/{template_id}/runs/{run_id}.

Response

Successful Response
idstring
The unique identifier of the run.
template_idstring

The template this run executed, so a webhook consumer running several templates can tell their runs apart without keeping a run-to-template map.

version_idstring

The template version this run executed. Resolved when the run is created, so a run started with latest records the concrete version it ran.

statusenum

The run’s status, rolled up from its outputs: pending until an output starts, generating while any output is unfinished, completed once every output has completed, and failed once every output has finished and at least one failed. completed and failed are terminal: the flows_template_run webhook fires once the run reaches either.

outputsmap from strings to objects

The run’s outputs, keyed by output port id. Each is a TemplateOutput discriminated on type, the type of its port’s content_schema.

Errors

422
Unprocessable Entity Error